Como usar o token de acesso

O token de acesso ao grupo de usuários contém alegações sobre o usuário autenticado, uma lista dos grupos do usuário e uma lista de escopos. O objetivo do token de acesso é autorizar as operações de API. Seu grupo de usuários aceita tokens de acesso para autorizar as operações de autoatendimento do usuário. Por exemplo, é possível usar o token de acesso para conceder ao usuário acesso para adicionar, alterar ou excluir atributos de usuário.

Com os escopos do OAuth 2.0 em um token de acesso, derivados dos escopos personalizados que você adiciona ao grupo de usuários, é possível autorizar o usuário a recuperar informações de uma API. Por exemplo, o Amazon API Gateway é compatível com a autorização com tokens de acesso do Amazon Cognito. Você pode preencher um autorizador de API REST com informações do grupo de usuários ou usar o Amazon Cognito como um autorizador do token web JSON (JWT) para uma API HTTP. Para gerar um token de acesso com escopos personalizados, é necessário solicitá-lo por meio dos endpoints públicos do grupo de usuários.

O token de acesso do usuário é a permissão para solicitar mais informações sobre os atributos do usuário no Endpoint do UserInfo. O token de acesso do usuário também é permissão para ler e gravar atributos do usuário. O nível de acesso aos atributos que seu token de acesso concede depende das permissões atribuídas ao cliente da aplicação e dos escopos concedidos no token.

O token de acesso é um JSON Web Token (JWT). O cabeçalho do token de acesso tem a mesma estrutura que o token de ID. O Amazon Cognito assina tokens de acesso com uma chave diferente da chave que assina os tokens de ID. O valor de uma reivindicação de ID de chave de acesso (kid) não corresponderá ao valor da reivindicação kid em um token de ID da mesma sessão do usuário. No código da aplicação, verifique os tokens de ID e os tokens de acesso de forma independente. Não confie nas reivindicações em um token de acesso até verificar a assinatura. Para ter mais informações, consulte Como verificar um token Web JSON. Você pode definir a validade do token de acesso para qualquer valor entre cinco minutos e um dia. Esse valor pode ser definido para cada cliente da aplicação.

Importante

Para tokens de acesso e de ID, não especifique um mínimo inferior a uma hora se você usar a IU hospedada. A UI hospedada do Amazon Cognito usa cookies válidos por uma hora. Se você inserir um mínimo de menos de uma hora, não obterá um tempo de validade menor.

Cabeçalho do token de acesso

O cabeçalho contém duas informações: o ID de chave (kid) e o algoritmo (alg).

{
"kid" : "1234example="
"alg" : "RS256",
}

kid

O ID da chave. Seu valor indica a chave usada para proteger a JSON web signature (JWS) do token. É possível ver os IDs de chave de assinatura do grupo de usuários no endpoint jwks_uri.

Para mais informações sobre o parâmetro kid, consulte Key identifier (kid) header parameter [Parâmetro de cabeçalho do identificador de chave (kid)].

alg

O algoritmo criptográfico que o Amazon Cognito usou para proteger o token de acesso. Os grupos de usuários utilizam um algoritmo criptográfico RS256, que é uma assinatura RSA com SHA-256.

Para obter informações sobre o parâmetro alg, consulte Algorithm (alg) header parameter (Parâmetro de cabeçalho algoritmo [alg]).

Carga útil do token de acesso

Esta é uma carga útil de exemplo de um token de acesso. Para mais informações, consulte JWT claims (Declarações JWT).

<header>.
{
   "sub":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "device_key": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "cognito:groups":[
      "testgroup"
   ],
   "iss":"https://cognito-idp.us-west-2.amazonaws.com/us-west-2_example",
   "version":2,
   "client_id":"xxxxxxxxxxxxexample",
   "origin_jti":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "event_id":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "token_use":"access",
   "scope":"phone openid profile resourceserver.1/appclient2 email",
   "auth_time":1676313851,
   "exp":1676317451,
   "iat":1676313851,
   "jti":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "username":"my-test-user"
}
.<token signature>

sub

Um identificador exclusivo (UUID), ou assunto, do usuário autenticado. O nome de usuário pode não ser exclusivo em seu grupo de usuários. A reivindicação sub é a melhor maneira de identificar determinado usuário.

cognito:groups

Uma matriz dos nomes dos grupos de usuários que têm o usuário como membro.

iss

O provedor de identidade que emitiu o token. A reivindicação tem o formato a seguir.

https://cognito-idp.<Region>.amazonaws.com/<your user pool ID>

client_id

O cliente de aplicação do grupo de usuários que autenticou o usuário. O Amazon Cognito renderiza o mesmo valor na reivindicação aud do token de ID.

origin_jti

Um identificador de revogação de token associado ao token de atualização do seu usuário. O Amazon Cognito faz referência à origin_jti reivindicação quando verifica se você revogou o token do seu usuário com a operação da API Revogar endpoint ou da RevokeTokenAPI. Quando você revoga um token, o Amazon Cognito invalida todos os tokens de acesso e ID com o mesmo valor origin_jti.

token_use

A finalidade do token. Em um token de acesso, seu valor é access.

scope

Uma lista de escopos do Oauth 2.0 que definem o acesso que o token oferece. Um token do Endpoint de token pode conter qualquer escopo compatível com seu cliente de aplicação. Um token do login da API do Amazon Cognito contém somente o escopo aws.cognito.signin.user.admin.

auth_time

A hora de autenticação, no formato de hora Unix, em que o usuário concluiu a autenticação.

exp

O tempo de validade, no formato de horário Unix, em que o token do usuário expira.

iat

A emissão no momento, no formato de horário Unix, em que o Amazon Cognito emitiu o token do usuário.

jti

O identificador exclusivo do JWT.

username

O nome do usuário no grupo de usuários.

Assinatura do token de acesso

A assinatura do token de acesso é calculada com base no cabeçalho e na carga útil do token JWT. Quando o token de ID for usado fora de uma aplicação em suas APIs da Web, sempre será necessário verificar essa assinatura antes de aceitá-lo. Para ter mais informações, consulte Como verificar um token Web JSON.