Pular para o conteúdo principal

Token de acesso pessoal (Personal access token)

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 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 (Access tokens)

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

Requisição

O aplicativo faz uma requisiçã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 requisições de token.
  4. scope: OPCIONAL. Os escopos solicitados, igual a outras requisiçõ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 requisiçã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 requisiçõ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

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

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&scope=profile
&subject_token=pat_W51arOqe7nynW75nWhvYogyc
&subject_token_type=urn%3Alogto%3Atoken-type%3Apersonal_access_token
HTTP/1.1 200 OK
Content-Type: application/json

{
"access_token": "eyJhbGci...zg",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "profile"
}

O payload de exemplo do token de acesso:

{
"jti": "iFtbZBeh2M1cTTBuKbHk4",
"sub": "123",
"iss": "https://tenant.logto.app/oidc",
"exp": 1672531200,
"iat": 1672527600,
"scope": "profile",
"client_id": "client-id"
}

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 (Machine-to-Machine), definição de API Keys e seus cenários no mundo real