Escopos e claims
Os escopos que o Authio entende, as claims que cada um acrescenta ao ID token, ao access token e ao UserInfo, e como criar escopos e claims próprios.
Um escopo é uma permissão que a aplicação pede na requisição de autorização; uma claim é um campo dentro de um token. Os escopos decidem quais claims o Authio escreve: email acrescenta o endereço, roles acrescenta os papéis, offline_access acrescenta um refresh token.
Um client só pode pedir os escopos habilitados nele, listados na aba Acesso do client. Pedir um escopo que não está habilitado é recusado com invalid_scope antes de qualquer pessoa entrar.
Escopos padrão do protocolo
| Escopo | Atribuição | O que acrescenta |
|---|---|---|
openid | Padrão | Torna a requisição OpenID Connect: um ID token é emitido e o UserInfo responde. Só é concedido quando a requisição o pede. |
profile | Padrão | name, given_name, family_name, unique_name, preferred_username e updated_at |
email | Padrão | email e email_verified |
phone | Opcional | phone_number e phone_number_verified |
roles | Padrão | As claims de papéis do access token — veja Papéis e permissões |
offline_access | Opcional | Um refresh token, nos grants que emitem um |
address | Opcional | Nada: o Authio não guarda endereço postal dos usuários |
Escopos padrão e opcionais
Todo escopo tem uma atribuição. Um escopo Padrão habilitado no client é concedido tenha ou não sido pedido; um Opcional, só quando a requisição o pede. openid é a exceção: só é concedido quando pedido.
O que foi concedido está na claim scope do token, separado por espaços. Leia-a primeiro quando uma claim esperada não aparecer.
Escopos sobre uma pessoa — openid, profile, email, phone, address e offline_access — nunca entram num token emitido para uma máquina pelo grant client credentials.
openid é obrigatório por padrão
Os clients começam com Exigir OpenID Connect ligado, na Configuração do client: uma requisição de autorização sem openid é recusada com invalid_scope. Desligue para uma aplicação que só precisa de um access token para chamar uma API e não tem uso para o ID token.
ID token, access token e UserInfo
Os três respondem a perguntas diferentes, e o Authio preenche cada um de um jeito:
| Aspecto | ID token | Access token | UserInfo |
|---|---|---|---|
| Para quem | A sua aplicação, para saber quem entrou | A sua API, como credencial de cada chamada | A sua aplicação, para ler os dados atuais da pessoa |
aud | O client_id do client | A API pedida com resource, ou a audiência configurada no client | — |
| Perfil, e-mail e telefone | Nome, username, e-mail e telefone, com as flags de verificação, sempre que openid foi concedido | As claims de profile, email e phone, para cada um concedido | As claims de profile, email e phone, para cada um concedido, lidas no momento da chamada |
| Papéis | Nunca | Com o escopo roles | Nunca |
| Organização | org_id e org_alias | org_id e org_alias | — |
| Mapeadores de claims | Quando o mapeador o tem como destino | Quando o mapeador o tem como destino | — |
| Validade | A duração de sessão do client | A duração de access token do client | — |
Claims do access token
| Claim | Valor |
|---|---|
iss | O emissor do realm, como https://authio.api.hyperio.tech/realms/acme |
sub | O ID do usuário no realm |
aud | A API pedida com resource, ou a audiência configurada no client |
azp | O client_id do client para o qual o token foi emitido |
scope | Os escopos concedidos, separados por espaços |
typ | Bearer. ID tokens trazem ID e refresh tokens, Refresh. |
iat, nbf, exp, jti | Momento da emissão, janela de validade e ID único |
sid | A sessão a que o token pertence |
auth_time | Quando a pessoa se autenticou |
amr | Como ela se autenticou: pwd, otp, swk (passkey), user, mca, fed, mais mfa quando houve dois fatores distintos |
acr | 1 para um fator, 2 para vários, 3 para vários com uma credencial resistente a phishing |
idp | O alias do provedor externo, quando o login começou nele |
org_id, org_alias | A organização do login — veja Organizações |
{
"iss": "https://authio.api.hyperio.tech/realms/acme",
"sub": "6f1c2e7a-4b8d-4f0e-9a51-3c2d7e8b9f10",
"aud": "https://api.acme.com",
"azp": "acme-web",
"typ": "Bearer",
"scope": "openid profile email offline_access",
"sid": "0b7e4c2a-9d1f-4a6e-8c3b-5f2d1e9a7c40",
"auth_time": 1791370800,
"acr": "2",
"amr": ["pwd", "otp", "mfa"],
"email": "maria@acme.com",
"email_verified": true,
"name": "Maria Silva",
"given_name": "Maria",
"family_name": "Silva",
"unique_name": "maria",
"preferred_username": "maria",
"updated_at": 1790000000,
"iat": 1791370800,
"nbf": 1791370800,
"exp": 1791372600,
"jti": "e5a8c1d4-7b2f-4c9e-a3d6-1f8b0e4c7a25"
}UserInfo
O UserInfo devolve os dados atuais da pessoa, lidos no momento da chamada: um nome alterado ou um e-mail confirmado depois do login aparece na hora. Chame-o com o access token, por GET ou POST.
curl https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/userinfo \
-H "Authorization: Bearer $ACCESS_TOKEN"subvem sempre;profile,emailephoneacrescentam as claims deles quando o token os recebeu.- Valores vazios ficam de fora.
- Um token sem
openidrecebe403cominsufficient_scope; um token inválido, ou cujo usuário não está mais ativo, recebe401cominvalid_token.
Escopos próprios
Crie escopos para as suas APIs, como invoices:read ou reports.export, em Permissões › Escopos globais com Novo escopo — ou exclusivos de um realm ou de um client, pela página desse registro. Um escopo exclusivo de um client já nasce habilitado nele. Escopos que pertencem a uma única API também podem ser declarados no servidor de recurso dela.
| Campo | Regras |
|---|---|
| Nome | Até 200 caracteres ASCII imprimíveis, sem espaços, aspas ou barras invertidas. Os escopos padrão acima, role_list, web-origins, acr e microprofile-jwt são reservados. |
| Texto de consentimento | Até 500 caracteres, mostrado à pessoa na tela de consentimento quando o client pede consentimento. |
| Protocolo | Uma classificação: OpenID Connect, OAuth 2.0, Client Credentials ou SAML. Escopos classificados como SAML nunca entram num JWT. |
| Atribuição | Padrão ou Opcional, como descrito acima. |
Um escopo próprio acrescenta o nome dele à claim scope e nada mais; a sua API o confere ali. Para colocar dados no token, use um mapeador de claims.
Claims próprias
Os mapeadores de claims acrescentam claims suas aos tokens que um client emite. Abra a aba Acesso do client, vá até Mapeadores de claims e crie uma regra por claim: o nome, de onde vem o valor e quais tokens a recebem.
| Origem | Valor |
|---|---|
| Propriedade do usuário | E-mail, e-mail confirmado, nome de usuário, nome, sobrenome, nome completo, telefone, telefone confirmado, data de criação da conta ou status |
| Papéis | Os nomes dos papéis da pessoa, diretos ou por grupo |
| Grupos | Os nomes dos grupos ativos da pessoa |
| Valor fixo | Uma constante que você digita, de até 512 caracteres |
- Cada regra escreve no access token, no ID token ou nos dois; pelo menos um.
- O nome da claim tem até 64 caracteres, começa com letra ou
_, usa só letras, dígitos,_,:e-, e é único entre os mapeadores do client. - Nomes que o protocolo escreve são recusados:
iss,aud,exp,nbf,iat,jti,azp,nonce,typ,alg,kid,sub,scope,client_id,sid,acr,amr,idp,at_hash,c_hasheauth_time. - Os mapeadores não dependem de escopos: um mapeador ativo escreve a claim em todo token que tem como destino. Uma origem com vários valores, como papéis, é escrita como array.
Antes de salvar, a tela do mapeador mostra o token resultante para um usuário real do client. Claims adicionadas direto a um usuário, no passo Permissões da edição do usuário, entram nos access tokens dele.