autorizacao

Home > Autenticação > Papéis e políticas 🚧

Papéis e políticas: quem pode usar cada rota

Important

Em desenvolvimento (2.0). Ainda não está numa versão lançada e pode mudar.

Vale para a 2.0 · Delphi XE em diante e Lazarus/FPC 3.2 em diante · Nível: intermediário

Em uma frase: a autenticação diz quem é o usuário; os papéis (Roles) e as políticas (Policy) da rota dizem o que ele pode fazer, com qualquer autenticador (Basic, JWT, Digest, OAuth2, OpenID Connect).

Você vai precisar: um autenticador ligado ao servidor (pacote RALPluginAuthPackage) e, para políticas, o TRALAuthorizationPlugin do mesmo pacote.

A identidade do pedido

Quando um autenticador aceita o pedido, ele preenche ARequest.Identity:

propriedade	o que é
Name	o usuário (Basic e Digest: o login; JWT e OAuth2: a claim sub)
Roles	os papéis, um por linha
Claims	as claims do token, nome=valor (Identity.Claim('email'))
AuthScheme	o esquema que aceitou (ratBasic, ratBearer, ratDigest)

De onde vêm os papéis:

autenticador	papéis
TRALServerBasicAuth, TRALServerDigest	o evento OnGetRoles
TRALServerJWTAuth	as claims de RolesClaim (padrão roles,role,groups)
TRALServerOAuth2	RolesClaim (padrão roles,role,groups,scope: um escopo vale como papel)
TRALOIDCLogin	a claim do provedor (OpenID Connect)

Uma claim de papéis pode ser um array JSON (["admin","financeiro"]), uma lista com espaços (como scope) ou com vírgulas.

procedure TForm1.BasicGetRoles(ARequest: TRALRequest; const AUserName: StringRAL;
  AIdentity: TRALIdentity);
begin
  if AUserName = 'ana' then
    AIdentity.AddRoles('admin,financeiro');
end;

Papéis na rota e no grupo

Server.CreateRoute('relatorios', Relatorios).RequireRoles('financeiro,admin');
Server.CreateRoute('fechamento', Fechar).RequireRoles('financeiro,gerente', True); // os dois
Server.RouteGroups.AddGroup('admin', '/admin').Roles := 'admin';

• Roles: basta um dos papéis da lista; com RequireAllRoles precisa de todos.
• Uma rota sem Roles usa os do grupo; a da rota vale mais que a do grupo.
• Faltou papel: 403 (o usuário é conhecido, só não pode). Sem credencial ou com credencial errada continua 401.

Políticas

Uma política é uma regra com nome, para não repetir listas e para regras que papéis não expressam. Ligue um TRALAuthorizationPlugin ao servidor e crie as políticas nele:

Authz := TRALAuthorizationPlugin.Create(Self);
with Authz.Policies.AddPolicy('editores', 'editor,admin') do
begin
  Claims.Add('departamento=vendas|ti');   // valor exato, alternativas com |
  Claims.Add('email_verified=*');         // * = basta a claim existir
  Scopes := 'pedidos:escrever';           // todos os escopos da claim scope/scp
  OnEvaluate := AvaliarHorario;           // a última palavra
end;
Authz.Server := Servidor;

Server.CreateRoute('pedidos', Pedidos).Policy := 'editores';

Tudo o que a política define precisa valer. OnEvaluate recebe o resultado das regras e pode mudá-lo (horário comercial, IP, um valor do banco).

Erros comuns

sintoma	causa
a rota com Policy sempre dá 403	não há TRALAuthorizationPlugin ligado, ou o nome da política está diferente (um nome que não existe recusa, de propósito)
Roles não tem efeito	o servidor não tem autenticador: sem autenticação nada é perguntado
JWT com papéis dá 403	os papéis estão numa claim fora de RolesClaim (ajuste a lista)
papel com vírgula no nome	dentro de um array JSON a vírgula vira ; ("a,b" → a;b)

Veja também

• Autenticação
• OpenID Connect
• Senhas e TOTP
• Rotas avançadas: grupos