Tokens de atualização - Amazon Cognito
Tokens de atualizaçãoAlternância de tokens de atualizaçãoAtualização de tokens de API e SDKOAuth atualização de tokenComo revogar tokens de atualização

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Tokens de atualização

Você pode usar o token de atualização para recuperar novos tokens de ID e acesso. Por padrão, o token de atualização expira 30 dias depois que o usuário da aplicação fizer login no seu grupo de usuários. Ao criar uma aplicação para seu grupo de usuários, você pode definir a validade do token de atualização da aplicação em qualquer valor entre 60 minutos e 10 anos.

Obter novos tokens de acesso e identidade com um token de atualização

O Amazon Cognito emite tokens de atualização em resposta à autenticação bem-sucedida com o fluxo do código de autorização de login gerenciado e com operações de API ou métodos de SDK. O token de atualização retorna novos tokens de ID e acesso e, opcionalmente, um novo token de atualização. Você pode usar tokens de atualização das maneiras a seguir.

GetTokensFromRefreshToken

A operação GetTokensFromRefreshTokenda API emite novos tokens de ID e acesso a partir de um token de atualização válido. Você também receberá um novo token de atualização se tiver habilitado a alternância de tokens de atualização.

InitiateAuth and AdminitiateAuth

As operações InitiateAuthda API AdminInitiateAuthou incluem o fluxo de REFRESH_TOKEN_AUTH autenticação. Nesse fluxo, você transmite um token de atualização e recebe novos tokens de ID e acesso. Não é possível autenticar com REFRESH_TOKEN_AUTH em clientes da aplicação com a alternância de tokens de atualização habilitada.

OAuth ponto final do token

O endpoint de token em grupos de usuários com um domínio tem um tipo de concessão refresh_token que emite novos tokens de ID, tokens de acesso e, opcionalmente (com alternância de tokens de atualização), tokens de atualização com base em um token de atualização válido.

Alternância de tokens de atualização

Opcionalmente, é possível configurar a alternância de tokens de atualização no cliente da aplicação. Com a alternância de tokens de atualização, o cliente pode invalidar o token de atualização original e emitir um novo token de atualização a cada atualização de token. Quando essa configuração está habilitada, cada solicitação bem-sucedida em todas as formas de atualização de token retorna um novo token de ID, token de acesso e token de atualização. Quando essa configuração está desabilitada, as solicitações de atualização de token retornam somente novos tokens de acesso e ID, e o token de atualização original permanece válido. O novo token de atualização é válido pela duração restante do token de atualização original. É possível configurar clientes da aplicação para alternar os tokens de atualização ou manter o token de atualização original. Para permitir novas tentativas por um breve período, também é possível configurar um período de carência para o token de atualização original de até 60 segundos.

O que é importante saber sobre a alternância de tokens de atualização

  • Após habilitar a alternância de tokens de atualização, novas declarações são adicionadas aos tokens web JSON do grupo de usuários. As solicitações origin_jti e jti são adicionadas aos tokens de acesso e de ID. Essas reivindicações aumentam o tamanho do JWTs.

  • A alternância de tokens de atualização não é compatível com o fluxo de autenticação REFRESH_TOKEN_AUTH. Para implementar a rotação do token de atualização, você deve desativar esse fluxo de autenticação no seu cliente de aplicativo e projetar seu aplicativo para enviar solicitações de atualização de token com a operação de GetTokensFromRefreshTokenAPI ou o método SDK equivalente.

  • Com a alternância de tokens de atualização inativa, você pode concluir solicitações de atualização do token com GetTokensFromRefreshToken ou REFRESH_TOKEN_AUTH.

  • Quando a memorização de dispositivos está ativa no grupo de usuários, é necessário fornecer a chave do dispositivo nas solicitações GetTokensFromRefreshToken. Se o usuário não tiver uma chave de dispositivo confirmada que sua aplicação envia na solicitação de autenticação inicial, o Amazon Cognito emitirá uma nova. Para atualizar os tokens nessa configuração, é necessário fornecer uma chave de dispositivo, independentemente de ter especificado uma em AuthParameters ou recebido uma nova na resposta de autenticação.

  • Você pode transmitir ClientMetadata para o acionador do Lambda de pré-geração de tokens na solicitação GetTokensFromRefreshToken. Esses dados, que são transmitidos para o evento de entrada do acionador, fornecem contexto adicional que você pode usar na lógica personalizada da função do Lambda.

Como prática recomendada de segurança, habilite a alternância de tokens de atualização nos clientes da aplicação.

Enable refresh token rotation (console)

O procedimento a seguir ativa ou desativa a alternância de tokens de atualização para o cliente da aplicação. Esse procedimento requer um cliente da aplicação existente. Para saber mais sobre como criar um cliente da aplicação, consulte Configurações específicas da aplicação com clientes de aplicação.

Como habilitar a alternância de token de atualização

  1. Acesse o console do Amazon Cognito. Se solicitado, insira suas AWS credenciais.

  2. Escolha User Pools (Grupos de usuários).

  3. Escolha um grupo de usuários existente da lista.

  4. Navegue até o menu Clientes da aplicação e selecione um cliente da aplicação existente.

  5. Clique em Editar na seção Informações do cliente de aplicação da página.

  6. Em Configurações avançadas de segurança, localize a opção Habilitar alternância de tokens de atualização.

  7. Para habilitar a alternância, marque a caixa de seleção. Para desabilitar a alternância, desmarque a caixa de seleção.

  8. Em Período de carência de alternância de tokens de atualização, insira um número de segundos, até 60, que você deseja definir como o atraso antes que o token de atualização alternado seja revogado.

Enable refresh token rotation (API)

Configure a rotação do token de atualização em uma solicitação de UpdateUserPoolClientAPI CreateUserPoolClientou de uma solicitação. O corpo parcial da solicitação a seguir ativa a alternância de tokens de atualização e define o período de carência para 10 segundos.

"RefreshTokenRotation" : {
   "Feature" : "ENABLED,
   "RetryGracePeriodSeconds" : 10
}

Atualização de tokens de API e SDK

Há duas maneiras de usar o token de atualização para obter novos tokens de ID e acesso com a API de grupos de usuários, dependendo se a alternância de tokens de atualização está ativa. Em clientes de aplicativos com a rotação do token de atualização ativa, use a operação de GetTokensFromRefreshTokenAPI. Em clientes de aplicativos sem rotação de token de atualização, use o REFRESH_TOKEN_AUTH fluxo das operações AdminInitiateAuthou da InitiateAuthAPI.

nota

Os usuários podem se autenticar com grupos de usuários no login gerenciado ou em aplicativos personalizados que você cria com AWS SDKs as operações da API do Amazon Cognito. O fluxo REFRESH_TOKEN_AUTH e GetTokensFromRefreshToken podem concluir a atualização de token para usuários de login gerenciado. A atualização de token em aplicações personalizadas não afeta as sessões de login gerenciado. Essas sessões são definidas em um cookie do navegador e são válidas por 1 hora. A resposta GetTokensFromRefreshToken emite novos tokens de ID, de acesso e, opcionalmente, de atualização, mas não renova o cookie da sessão de login gerenciado.

REFRESH_TOKEN_AUTH não está disponível em clientes da aplicação com a alternância de tokens de atualização habilitada.

GetTokensFromRefreshToken

GetTokensFromRefreshTokenretorna novos tokens de ID, acesso e atualização de uma solicitação que você autoriza com um token de atualização. Veja a seguir um exemplo de corpo da solicitação para GetTokensFromRefreshToken. Você pode enviar metadados do cliente para acionadores do Lambda em solicitações para essa operação.

{
    "RefreshToken": "eyJjd123abcEXAMPLE",
    "ClientId": "1example23456789",
    "ClientSecret": "myappclientsecret123abc",
    "ClientMetadata": { 
      "MyMetadataKey" : "MyMetadataValue" 
   },
}
AdminInitiateAuth/InitiateAuth

Para usar o token de atualização quando a rotação do token de atualização estiver inativa, use as operações de API AdminInitiateAuthou InitiateAuth. Transmita REFRESH_TOKEN_AUTH para o parâmetro AuthFlow. Na propriedade AuthParameters de AuthFlow, transmita o token de atualização do usuário como o valor de "REFRESH_TOKEN". O Amazon Cognito retorna novos tokens de ID e acesso depois que sua solicitação à API passar por todos os desafios.

Veja a seguir um exemplo de corpo de solicitação para uma atualização de token com a API InitiateAuth ou AdminInitiateAuth.

{
    "AuthFlow": "REFRESH_TOKEN_AUTH",
    "ClientId": "1example23456789",
    "UserPoolId": "us-west-2_EXAMPLE",
    "AuthParameters": {
        "REFRESH_TOKEN": "eyJjd123abcEXAMPLE",
        "SECRET_HASH": "kT5acwCVrbD6JexhW3EQwnRSe6fLuPTRkEQ50athqv8="
    }
}

OAuth atualização de token

Você também pode enviar tokens de atualização para o Endpoint de token em um grupo de usuários em que configurou um domínio. No corpo da solicitação, inclua um valor grant_type de refresh_token e um valor refresh_token do token de atualização do usuário.

As solicitações para o endpoint do token estão disponíveis em clientes da aplicação com a alternância de tokens de atualização ativa e naqueles em que ela está inativa. Quando a alternância de tokens de atualização está ativa, o endpoint do token retorna um novo token de atualização.

Veja a seguir um exemplo de solicitação com um token de atualização.

POST /oauth2/token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw
Content-Length: **

client_id=1example23456789&grant_type=refresh_token&refresh_token=eyJjd123abcEXAMPLE

Como revogar tokens de atualização

Você pode revogar tokens de atualização que pertencem a um usuário. Para obter mais informações sobre revogação de tokens, consulte Encerrar sessões de usuário com revogação de token.

nota

A revogação do token de atualização revogará todos os tokens de ID e acesso que o Amazon Cognito emitiu de solicitações de atualização com esse token.

Para desconectar os usuários de toda a sessão atual conectada, revogue todos os seus tokens ou solicitações de API. GlobalSignOutAdminUserGlobalSignOut Depois que o usuário é desconectado, os seguintes efeitos acontecem:

  • O token de atualização do usuário não pode obter novos tokens para ele.

  • O token de acesso do usuário não pode fazer solicitações de API autorizadas por token.

  • O usuário precisa se autenticar novamente para obter novos tokens. Como os cookies de sessão de login gerenciado não expiram automaticamente, o usuário pode se autenticar novamente com um cookie de sessão, sem nenhuma solicitação adicional de credenciais. Após desconectar os usuários de login gerenciado, redirecione-os para o Endpoint de logout, onde o Amazon Cognito limpará o cookie da sessão.

Com os tokens de atualização, você pode manter as sessões dos usuários na aplicação por um longo tempo. Com o tempo, os usuários podem querer desautorizar algumas aplicações nas quais permaneceram conectados com seus tokens de atualização. Para desconectar o usuário de uma única sessão, revogue o token de atualização. Quando seu usuário quiser sair de todas as sessões autenticadas, gere uma solicitação de GlobalSignOutAPI. A aplicação pode oferecer ao usuário uma opção como Sair de todos os dispositivos. GlobalSignOut aceita o token de acesso válido/inalterado, não expirado e não revogado de um usuário. Como essa API é autorizada por token, um usuário não pode usá-la para iniciar a saída de outro usuário.

No entanto, você pode gerar uma solicitação de AdminUserGlobalSignOutAPI autorizada com suas AWS credenciais para desconectar qualquer usuário de todos os seus dispositivos. O aplicativo administrador deve chamar essa operação de API com credenciais de AWS desenvolvedor e passar o ID do grupo de usuários e o nome de usuário do usuário como parâmetros. A API AdminUserGlobalSignOut pode retirar qualquer usuário no grupo de usuários.

Para obter mais informações sobre solicitações que você pode autorizar com AWS credenciais ou com o token de acesso de um usuário, consulte. Lista de operações de API agrupadas por modelo de autorização