Pular para o conteúdo principal

Token de acesso pessoal

Tokens de acesso pessoal (PATs) fornecem uma maneira segura para os usuários concederem token de acesso (Access token) sem usar suas credenciais e login interativo. Isso é útil para CI/CD, scripts ou aplicativos que precisam acessar recursos programaticamente.

Gerenciando tokens de acesso pessoal​

Usando o Console​

Você pode gerenciar tokens de acesso pessoal na página de Detalhes do Usuário do Console > Gerenciamento de usuários. No cartão "Autenticação (Authentication)", você pode ver a lista de tokens de acesso pessoal e criar novos.

Usando a Management API​

Após configurar a Management API, você pode usar os endpoints da API para criar, listar e excluir tokens de acesso pessoal.

Usar PATs para conceder tokens de acesso​

Após criar um PAT, você pode usá-lo para conceder tokens de acesso ao seu aplicativo utilizando o endpoint de troca de token.

Equivalência do fluxo de token:

Tokens de acesso obtidos usando PATs funcionam identicamente aos tokens obtidos pelo fluxo padrão de refresh_token. Isso significa:

  • Contexto de organização: Tokens obtidos por PAT suportam as mesmas permissões e escopos de organização que os fluxos de refresh token
  • Fluxo de autorização: Você pode usar tokens de acesso trocados por PAT para permissões de organização e recursos de API em nível de organização
  • Validação de token: A mesma lógica de validação se aplica - apenas o tipo de concessão inicial é diferente

Se você estiver trabalhando com organizações, os padrões de acesso e permissões são os mesmos independentemente de usar PAT ou refresh tokens.

Requisição​

Pré-requisitos:

Antes de usar a concessão de troca de token, você precisa habilitá-la para seu aplicativo:

  1. Vá para Console > Aplicativos e selecione seu aplicativo.
  2. Nas configurações do aplicativo, encontre a seção "Troca de token".
  3. Ative a opção "Permitir troca de token".

A troca de token está desabilitada por padrão por motivos de segurança. Se você não habilitá-la, receberá um erro "token exchange is not allowed for this application".

O aplicativo faz uma solicitação de troca de token para o endpoint de token do tenant com um tipo de concessão especial usando o método HTTP POST. Os seguintes parâmetros são incluídos no corpo da requisição HTTP usando o formato application/x-www-form-urlencoded.

  1. client_id: OBRIGATÓRIO. O client ID do aplicativo.
  2. grant_type: OBRIGATÓRIO. O valor deste parâmetro deve ser urn:ietf:params:oauth:grant-type:token-exchange indicando que uma troca de token está sendo realizada.
  3. resource: OPCIONAL. O indicador de recurso, igual a outras solicitações de token.
  4. scope: OPCIONAL. Os escopos solicitados, igual a outras solicitações de token.
  5. subject_token: OBRIGATÓRIO. O PAT do usuário.
  6. subject_token_type: OBRIGATÓRIO. O tipo do token de segurança fornecido no parâmetro subject_token. O valor deste parâmetro deve ser urn:logto:token-type:personal_access_token.

Resposta​

Se a solicitação de troca de token for bem-sucedida, o endpoint de token do tenant retorna um token de acesso que representa a identidade do usuário. A resposta inclui os seguintes parâmetros no corpo da resposta HTTP usando o formato application/json.

  1. access_token: OBRIGATÓRIO. O token de acesso do usuário, igual a outras solicitações de token como authorization_code ou refresh_token.
  2. issued_token_type: OBRIGATÓRIO. O tipo do token emitido. O valor deste parâmetro deve ser urn:ietf:params:oauth:token-type:access_token.
  3. token_type: OBRIGATÓRIO. O tipo do token. O valor deste parâmetro deve ser Bearer.
  4. expires_in: OBRIGATÓRIO. O tempo de vida em segundos do token de acesso.
  5. scope: OPCIONAL. Os escopos do token de acesso.

Exemplo de troca de token​

Para aplicativos web tradicionais ou aplicativos máquina para máquina com segredo do aplicativo, inclua as credenciais no cabeçalho Authorization usando autenticação HTTP Basic:

POST /oidc/token HTTP/1.1
Host: tenant.logto.app
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(app-id:app-secret)>

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&resource=http://my-api.com
&scope=read
&subject_token=pat_W51arOqe7nynW75nWhvYogyc
&subject_token_type=urn:logto:token-type:personal_access_token

Para single-page applications (SPA) ou aplicativos nativos sem segredo do aplicativo, inclua o client_id no corpo da requisição:

POST /oidc/token HTTP/1.1
Host: tenant.logto.app
Content-Type: application/x-www-form-urlencoded

client_id=your-app-id
&grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&resource=http://my-api.com
&scope=read
&subject_token=pat_W51arOqe7nynW75nWhvYogyc
&subject_token_type=urn:logto:token-type:personal_access_token

Uma resposta bem-sucedida:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "eyJhbGci...zg",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read"
}

Então, se você decodificar o token de acesso com o decodificador JWT, você obterá o seguinte payload de exemplo do token de acesso:

{
  "jti": "VovNyqJ5_tuYac89eTbpF",
  "sub": "rkxl1ops7gs1",
  "iat": 1756908403,
  "exp": 1756912003,
  "scope": "read",
  "client_id": "your-app-id",
  "iss": "https://tenant-id.logto.app/oidc",
  "aud": "http://my-api.com"
}

O que é um token de acesso pessoal? Quando devo usar tokens de acesso pessoal?

Tokens de acesso pessoal, autenticação máquina para máquina e definição de API Keys e seus cenários do mundo real