Esta página ainda não foi traduzida: mostrando a versão em inglês.

Access & Roles

Os papéis são compostos, nunca fixos no código. Permissões atômicas se combinam em papéis; os papéis controlam o acesso aos dados até a linha e a coluna e decidem quais interfaces de módulo um build chega a ver. Isso substitui a divisão entre chave de cliente e chave de servidor: a credencial aponta para uma identidade, e os papéis dela são resolvidos a cada requisição.

Quando usar

• Você precisa de uma credencial mais restrita que “cliente” ou “servidor”: por trás dela, papéis (role) compostos são resolvidos a cada requisição.
• O acesso aos dados precisa parar em linhas e colunas: escopo por região, máscaras para dados pessoais, prestadores de serviço com acesso somente leitura.
• Um build só deve ver as interfaces que o papel dele libera: para um visitante, expulsar e fechar simplesmente não existem.
• A sua UI precisa desabilitar botões com precisão: CanI avalia a mesma política que o servidor vai aplicar.
• Dispensável quando os presets que vêm com a plataforma (player, room-owner, seller, …) já correspondem aos seus atores. Todo módulo os respeita por padrão; o catálogo completo está em Conceitos principais.

Quem faz o quê

Resumo

[Role("entry-validator")]
public class EntryValidator
{
    [Allow(Rooms.Membership.Administer)] public Permit GateEntries;
    [Allow(Data.Records.Read, table: "player_profile", rows: "banned == false",
           columns: "id, display_name")] public Permit SeeProfiles;
}

await PlayServ.Access.Grant(staffId, Roles.EntryValidator, Roles.MatchOrganizer);
var key = await PlayServ.Access.IssueKey(staffId);   // the credential names no roles

// any actor, before attempting an operation:
if (await PlayServ.Access.CanI(Commerce.Orders.Administer)) Hud.ShowRefund();

@Role('entry-validator')
export class EntryValidator {
  @Allow(Rooms.membership.administer) gateEntries: Permit;
  @Allow(Data.records.read, { table: 'player_profile', rows: 'banned == false',
                              columns: ['id', 'display_name'] }) seeProfiles: Permit;
}

await playserv.access.grant(staffId, Roles.entryValidator, Roles.matchOrganizer);
const key = await playserv.access.issueKey(staffId);  // the credential names no roles

// any actor, before attempting an operation:
if (await playserv.access.canI(Commerce.orders.administer)) hud.showRefund();

@role("entry-validator")
class EntryValidator:
    gate_entries = allow(rooms.membership.administer)
    see_profiles = allow(data.records.read, table="player_profile",
                         rows="banned == false", columns=["id", "display_name"])

await playserv.access.grant(staff_id, roles.ENTRY_VALIDATOR, roles.MATCH_ORGANIZER)
key = await playserv.access.issue_key(staff_id)   # the credential names no roles

# any actor, before attempting an operation:
if await playserv.access.can_i(commerce.orders.administer):
    hud.show_refund()

// declarations compile into the same pushed model — playserv push from the UE project or CI
USTRUCT(PSRole = "entry-validator")
struct FEntryValidator
{
    GENERATED_BODY()

    UPROPERTY(PSAllow = (Atom = "Rooms.Membership.Administer"))
    FPSPermit GateEntries;

    UPROPERTY(PSAllow = (Atom = "Data.Records.Read", Table = "player_profile",
                         Rows = "banned == false", Columns = "id, display_name"))
    FPSPermit SeeProfiles;
};

// granting is an operator act; a build checks what its identity resolves to
const FPSActor Me = Client->Whoami();   // which interfaces this actor unlocks
Client->Access->CanI(TEXT("Commerce.Orders.Administer"),
    TPSOnResult<bool>::CreateWeakLambda(this, [this](const TPSResult<bool>& Result)
    {
        if (!Result.HasValue()) { return; }
        if (Result.Value()) { Hud->ShowRefund(); }
    }));
// co_await support ships later: a built-in SDK coroutine wrapper that respects Unreal's GC and threading.

// the same `[Role]` / `[Allow]` declaration as the server tab, on the Unity 2021.3 runtime
var me = playserv.Whoami();               // which interfaces this actor unlocks
if (await playserv.Access.CanI(Commerce.Orders.Administer)) hud.ShowRefund();

Uma permissão atômica é um par: um recurso e um de quatro verbos — read, write, execute, administer. O conjunto de verbos é fixo; um caso que não se encaixa nele divide o recurso em vez de aumentar a lista. Por isso, controlar a entrada de outra pessoa é Rooms.Membership.Administer, e não um verbo ValidateEntry só para isso: agir sobre a participação de outro ator é administração, enquanto entrar você mesmo é Rooms.Membership.Write no mesmo recurso.

O modelo

O ACL de dados é papel × operação × predicado de linhas × máscara de campos — um único modelo, idêntico seja ele escrito no código, pela API ou na grade de papéis do painel.

Do que o acesso é feito.

O que cada credencial libera.

A legenda das tags (fn / cl / mc / adm) fica em Conceitos principais.

O que vale para toda verificação.

Quem distribui os papéis. Conceder e revogar o papel de um jogador, assim como o papel padrão que o projeto declara para um jogador novo, são operações de Auth & Players — esse módulo é dono das identidades, e o papel é resolvido pela identidade que está na credencial.

Erros

• O que um predicado esconde responde not found, não forbidden: senão a própria recusa contaria a quem chamou que aquilo existe.
• Um direito que quem chama não tem responde forbidden quando a existência do alvo não é segredo, e a resposta diz o que faltou em vez de falhar sem explicação.
• Um campo fora da máscara não aparece na resposta, em vez de vir presente e vazio: um valor vazio e um valor mascarado seriam indistinguíveis.
• Um papel que inclui a si mesmo, diretamente ou por uma cadeia, é um erro de configuração — recusado já como declaração, e não resolvido em runtime.
• A delegação nunca amplia a capacidade: uma chamada que o ator não poderia fazer por conta própria é recusada quando feita em nome de um jogador.

Limites

Os números chegam com o capítulo de limites da plataforma; o que acontece em cada teto já está definido.

• O tamanho de uma seleção sob um predicado de linhas é limitado, e o modelo de ACL declara esse limite em vez de descobri-lo na prática. Uma leitura acima do teto recebe o teto em linhas, mais o marcador de que foi cortada — nunca uma página menor sem aviso.
• O limite de desatualização de uma permissão resolvida é declarado, e uma revogação não espera por ele: invalida na hora.