Pular para o conteúdo principal

Token opaco (Opaque token)

Durante o processo de autenticação, se nenhum recurso for especificado, o Logto emitirá um token de acesso opaco em vez de um JWT. O token opaco é uma string aleatória e é muito mais curto que um JWT:

{
  "access_token": "some-random-string", // token opaco
  "expires_in": 3600,
  "id_token": "eyJhbGc...aBc", // JWT
  "scope": "openid profile email",
  "token_type": "Bearer"
}

O token opaco pode ser usado para chamar o endpoint userinfo e acessar recursos protegidos que exigem autenticação. Como ele não é um JWT, como o servidor de recursos pode validá-lo?

O Logto fornece um endpoint de introspecção que pode ser usado para validar tokens opacos. Por padrão, o endpoint de introspecção é /oidc/token/introspection e aceita requisições POST. O seguinte parâmetro é obrigatório:

  • token: o token opaco a ser validado

O endpoint também exige autenticação do cliente. Você pode usar um dos seguintes métodos:

  • Autenticação HTTP Basic: Use o cabeçalho Authorization com o valor Basic <credenciais-base64>. As credenciais devem ser o client ID e o client secret separados por dois pontos (:) e codificados em base64.
  • Autenticação HTTP POST: Use os parâmetros client_id e client_secret:
    • client_id: o client ID do aplicativo que solicitou o token
    • client_secret: o client secret do aplicativo que solicitou o token

O client ID (ID do app) e o client secret (segredo do app) podem ser as credenciais de qualquer aplicativo "web tradicional" ou "máquina para máquina" no Logto. O endpoint de introspecção retornará um erro se as credenciais forem inválidas.

O endpoint de introspecção retorna um objeto JSON com as reivindicações (claims) do token:

{
  "active": true, // se o token é válido ou não
  "sub": "1234567890", // o sujeito do token (o ID do usuário)
  "acr": "urn:logto:acr:1fa", // nível de garantia de autenticação, quando alcançado
  "amr": ["pwd"], // métodos de autenticação usados na interação
  "auth_time": 1787745600 // quando o usuário autenticou (segundos epoch)
}

Se o token for inválido, o campo active será false e as outras reivindicações serão omitidas. Veja Autenticação step-up para saber como validar acr, amr e auth_time. Observe que tokens de acesso JWT estruturados não podem ser introspectados em /oidc/token/introspection—sempre valide tokens de acesso JWT localmente contra o JWKS do seu tenant.

Aqui está um exemplo não normativo da requisição de introspecção:

curl --location \
  --request POST 'https://[tenant-id].logto.app/oidc/token/introspection' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'token=some-random-string' \
  --data-urlencode 'client_id=1234567890' \
  --data-urlencode 'client_secret=1234567890'

Lembre-se de substituir [tenant-id] pelo ID do seu tenant.

Token opaco e organizações (Opaque token and organizations)​

Tokens opacos podem ser usados para recuperar informações de associação a organizações via endpoint userinfo. Quando você solicita o escopo urn:logto:scope:organizations, o endpoint userinfo retornará as reivindicações relacionadas à organização do usuário, como organizations (IDs das organizações) e organization_data.

No entanto, tokens opacos não podem ser usados como tokens de organização. Tokens de organização são sempre emitidos no formato JWT porque:

  1. Tokens de organização contêm reivindicações específicas da organização (como organization_id e permissões com escopo) que precisam ser validadas pelos servidores de recursos.
  2. O formato JWT permite que os servidores de recursos verifiquem o token e extraiam o contexto da organização sem chamadas adicionais de API.

Para obter um token de organização, você precisa usar o fluxo de refresh token ou o fluxo de client credentials com parâmetros de organização.