Formato de solicitação Exemplo: código de autorização Exemplo: credenciais do cliente com autorização básica Exemplo: credenciais do cliente com autorização do corpo Exemplo: código de autorização com PKCE Exemplo: concessão de tokens de atualização sem alternância Exemplo: alternância de tokens de atualização Respostas de erro

O endpoint do emissor de tokens

O endpoint de token OAuth 2.0 em /oauth2/token emite tokens web JSON (JWTs) para aplicações que desejam concluir fluxos de concessão de código de autorização e credenciais de cliente. Esses tokens são o resultado da autenticação com um grupo de usuários. Eles contêm informações sobre o usuário (token de ID), o nível de acesso do usuário (token de acesso) e o direito do usuário de persistir na sessão conectada (token de atualização). As bibliotecas independentes do OpenID Connect (OIDC) gerenciam cargas úteis de solicitações e respostas desse endpoint. Os tokens fornecem prova verificável de autenticação, informações de perfil e um mecanismo para acesso a sistemas de backend.

O servidor de autorização do OAuth 2.0 do grupo de usuários emite JSON web tokens (JWTs) do endpoint do token para os tipos de sessão a seguir:

Usuários que concluíram uma solicitação de concessão de código de autorização. O resgate bem-sucedido de um código retorna tokens de ID, acesso e atualização.
Sessões entre máquinas (M2M) que concluíram uma concessão de credenciais de cliente. A autorização bem-sucedida com o segredo do cliente retorna um token de acesso.
Usuários que já fizeram login e receberam tokens de atualização. A autenticação de token de atualização retorna novos tokens de ID e acesso.

nota
Os usuários que fazem login com uma concessão de código de autorização no login gerenciado ou por meio da federação sempre podem atualizar seus tokens por meio do endpoint de token. Usuários que fazem login com as operações da API InitiateAuth e AdminInitiateAuth podem atualizar seus tokens com o endpoint do token quando os dispositivos memorizados não estão ativos em seu grupo de usuários. Se os dispositivos memorizados estiverem ativos, atualize os tokens com a API relevante ou a operação de atualização de token do SDK para seu cliente de aplicação.

O endpoint do token fica disponível ao público quando você adiciona um domínio ao grupo de usuários. Ele aceita solicitações HTTP POST. Para fins de segurança da aplicação, use o PKCE com eventos de login com código de autorização. O PKCE verifica se o usuário que está transmitindo um código de autorização é o mesmo usuário que se autenticou. Para obter mais informações sobre PKCE, consulte IETF RFC 7636.

Você pode aprender mais sobre os clientes da aplicação do grupo de usuários e seus tipos de concessão, segredos do cliente, escopos permitidos e IDs de clientes em Configurações específicas da aplicação com clientes de aplicação. Você pode aprender mais sobre autorização M2M, concessões de credenciais de clientes e autorização com escopos de token de acesso em Escopos, M2M e APIs com servidores de recursos.

Para recuperar informações sobre um usuário por meio do token de acesso, transmita-o para endpoint userinfo ou para uma solicitação de API GetUser. O token de acesso deve conter os escopos apropriados para essas solicitações.

Formatar uma solicitação POST para o endpoint de token

O endpoint /oauth2/token só é compatível com HTTPS POST. Esse endpoint não é interativo com o usuário. Gerencie solicitações de token com uma biblioteca OpenID Connect (OIDC) em sua aplicação.

O endpoint de token é compatível com a autenticação de client_secret_basic e client_secret_post. Para obter mais informações sobre a especificação do OIDC, consulte Client Authentication. Para obter mais informações sobre o endpoint de token na especificação do OpenID Connect, consulte Endpoint de token.

Parâmetros de solicitação no cabeçalho

Você pode transmitir os parâmetros a seguir no cabeçalho da sua solicitação para o endpoint de token.

Authorization

Se um segredo foi emitido para o cliente, ele precisa passar o client_id e o client_secret no cabeçalho de autorização como autorização HTTP client_secret_basic. Você também pode incluir o client_id e client_secret no corpo da solicitação como autorização de client_secret_post.

A string do cabeçalho de autorização é Basic Base64Encode(client_id:client_secret). O exemplo a seguir é um cabeçalho de autorização para o cliente da aplicação djc98u3jiedmi283eu928 com segredo do cliente abcdef01234567890 usando a versão codificada em Base64 da string djc98u3jiedmi283eu928:abcdef01234567890:


Authorization: Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw

Content-Type

Defina o valor desse parâmetro como 'application/x-www-form-urlencoded'.

Parâmetros de solicitação no corpo

A seguir estão os parâmetros que você pode solicitar em formato x-www-form-urlencoded no corpo da solicitação para o endpoint de token.

grant_type

Obrigatória.

O tipo de concessão do OIDC que você deseja solicitar.

Deve ser authorization_code ou refresh_token ou client_credentials. Você pode solicitar um token de acesso para um escopo personalizado a partir do endpoint do token sob as seguintes condições:

Você habilitou o escopo solicitado na configuração do cliente da aplicação.
Você configurou o cliente da aplicação com um segredo do cliente.
Você ativa a concessão de credenciais do cliente em seu cliente de aplicação.

nota

O endpoint de token retorna um token de atualização somente quando o grant_type é authorization_code.

client_id

Opcional. Não é obrigatório quando você fornece o ID do cliente de aplicação no cabeçalho Authorization.

O ID de um cliente de aplicação no grupo de usuários. Especifique o mesmo cliente de aplicação que autenticou o usuário.

Você deve fornecer esse parâmetro se o cliente for público e não tiver um segredo ou com client_secret na autorização client_secret_post.

client_secret

Opcional. Não é obrigatório quando você fornece o segredo do cliente no cabeçalho Authorization e quando o cliente de aplicação não tem um segredo.

O segredo do cliente de aplicação, caso o cliente de aplicação tenha um, para autorização client_secret_post.

scope

Opcional.

Pode ser uma combinação de quaisquer escopos associados ao seu cliente de aplicação. O Amazon Cognito ignora escopos na solicitação que não são permitidos para o cliente de aplicação solicitado. Se você não fornecer esse parâmetro de solicitação, o servidor de autorização retornará uma declaração scope de token de acesso com todos os escopos de autorização que você habilitou na configuração do cliente de aplicação. É possível solicitar qualquer um dos escopos permitidos para o cliente de aplicação solicitado: escopos padrão, escopos personalizados de servidores de recursos e o escopo de autoatendimento do usuário aws.cognito.signin.user.admin.

redirect_uri

Opcional. Não é obrigatório para concessões de credenciais de clientes.

Precisa ser o mesmo redirect_uri usado para obter o authorization_code em /oauth2/authorize.

Você deve fornecer esse parâmetro se grant_type for authorization_code.

refresh_token

Opcional. Usado somente quando o usuário já tem um token de atualização e deseja obter um novo ID e tokens de acesso.

Para gerar novos tokens de acesso e ID para a sessão de um usuário, defina o valor de refresh_token para um token de atualização válido emitido pelo cliente de aplicação solicitado.

Retorna um novo token de atualização com um novo token de ID e acesso quando a alternância de tokens de atualização está ativa, caso contrário, retorna somente tokens de ID e acesso. Se o token de acesso original estiver vinculado a um recurso da API, o novo token de acesso manterá o URL da API solicitado na declaração aud.

code

Opcional. Obrigatório somente em concessões de código de autorização.

O código de autorização de uma concessão de código de autorização. Você deve fornecer esse parâmetro se sua solicitação de autorização incluir grant_type de authorization_code.

aws_client_metadata

Opcional.

Informações que você deseja transmitir para Acionador do Lambda antes da geração do token em fluxos de autorização máquina-a-máquina (M2M). Sua aplicação pode coletar informações de contexto sobre a sessão e transmiti-las neste parâmetro. Quando você transmite aws_client_metadata no formato JSON codificado por URL, o Amazon Cognito o inclui no evento de entrada para sua função do Lambda do acionador. Sua versão do evento de acionador de pré-geração de tokens ou a versão global de acionador do Lambda deve ser configurada para a versão três ou posterior. Embora o Amazon Cognito aceite solicitações para este endpoint em fluxos M2M de código de autorização e credenciais do cliente, seu grupo de usuários só transmite aws_client_metadata para o acionador de pré-geração de tokens por meio de solicitações de credenciais do cliente.

code_verifier

Opcional. Obrigatório somente se você tiver fornecido os parâmetros code_challenge_method e code_challenge em sua solicitação de autorização inicial.

O verificador de código gerado que sua aplicação usou para calcular code_challenge em uma solicitação de concessão de código de autorização com PKCE.

Como trocar um código de autorização por tokens

A solicitação a seguir gera tokens de ID, acesso e atualização com sucesso após a autenticação com uma concessão de código de autorização. A solicitação transmite o segredo do cliente no formato client_secret_basic no cabeçalho Authorization.


POST https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token&
Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw

grant_type=authorization_code&
client_id=1example23456789&
code=AUTHORIZATION_CODE&
redirect_uri=com.myclientapp://myclient/redirect

A resposta emite novos tokens de ID, acesso e atualização para o usuário, com metadados adicionais.


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

{
    "access_token": "eyJra1example",
    "id_token": "eyJra2example",
    "refresh_token": "eyJj3example",
    "token_type": "Bearer",
    "expires_in": 3600
}

Credenciais do cliente com autorização básica

A solicitação a seguir de uma aplicação M2M solicita a concessão de credenciais do cliente. Como as credenciais do cliente exigem um segredo do cliente, a solicitação é autorizada com um cabeçalho Authorization derivado do ID e do segredo do cliente de aplicação. A solicitação resulta em um token de acesso com os dois escopos solicitados. A solicitação também inclui metadados do cliente que fornecem informações de endereço IP e um token emitido para o usuário atribuído a essa concessão. O Amazon Cognito transmite os metadados do cliente para o acionador do Lambda de pré-geração de tokens.


POST https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token >
Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw

grant_type=client_credentials&
client_id=1example23456789&
scope=resourceServerIdentifier1%2Fscope1%20resourceServerIdentifier2%2Fscope2&
&aws_client_metadata=%7B%22onBehalfOfToken%22%3A%22eyJra789ghiEXAMPLE%22,%20%22ClientIpAddress%22%3A%22192.0.2.252%22%7D

O Amazon Cognito transmite o evento de entrada a seguir para o acionador do Lambda de pré-geração de tokens.


{
    version: '3',
    triggerSource: 'TokenGeneration_ClientCredentials',
    region: 'us-east-1',
    userPoolId: 'us-east-1_EXAMPLE',
    userName: 'ClientCredentials',
    callerContext: {
        awsSdkVersion: 'aws-sdk-unknown-unknown',
        clientId: '1example23456789'
    },
    request: {
        userAttributes: {},
        groupConfiguration: null,
        scopes: [
           'resourceServerIdentifier1/scope1',
           'resourceServerIdentifier2/scope2'
        ],
        clientMetadata: {
            'onBehalfOfToken': 'eyJra789ghiEXAMPLE',
            'ClientIpAddress': '192.0.2.252'
        }
    },
    response: { claimsAndScopeOverrideDetails: null }
}

A resposta retorna um token de acesso. As concessões de credenciais do cliente são para autorização máquina-a-máquina (M2M) e retornam somente tokens de acesso.


HTTP/1.1 200 OK
Content-Type: application/json
{
    "access_token": "eyJra1example",
    "token_type": "Bearer",
    "expires_in": 3600
}

Credenciais do cliente com autorização do corpo POST

A solicitação de concessão de credenciais do cliente a seguir inclui o parâmetro client_secret no corpo da solicitação e não inclui um cabeçalho Authorization. Essa solicitação usa a sintaxe de autorização client_secret_post. A solicitação resulta em um token de acesso com o escopo solicitado. A solicitação também inclui metadados do cliente que fornecem informações de endereço IP e um token emitido para o usuário atribuído a essa concessão. O Amazon Cognito transmite os metadados do cliente para o acionador do Lambda de pré-geração de tokens.


POST /oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
X-Amz-Target: AWSCognitoIdentityProviderService.Client credentials request
User-Agent: USER_AGENT
Accept: /
Accept-Encoding: gzip, deflate, br
Content-Length: 177
Referer: http://auth.example.com/oauth2/token
Host: auth.example.com
Connection: keep-alive

grant_type=client_credentials&
client_id=1example23456789&
scope=my_resource_server_identifier%2Fmy_custom_scope&
client_secret=9example87654321&
aws_client_metadata=%7B%22onBehalfOfToken%22%3A%22eyJra789ghiEXAMPLE%22,%20%22ClientIpAddress%22%3A%22192.0.2.252%22%7D

O Amazon Cognito transmite o evento de entrada a seguir para o acionador do Lambda de pré-geração de tokens.


{
    version: '3',
    triggerSource: 'TokenGeneration_ClientCredentials',
    region: 'us-east-1',
    userPoolId: 'us-east-1_EXAMPLE',
    userName: 'ClientCredentials',
    callerContext: {
        awsSdkVersion: 'aws-sdk-unknown-unknown',
        clientId: '1example23456789'
    },
    request: {
        userAttributes: {},
        groupConfiguration: null,
        scopes: [
           'resourceServerIdentifier1/my_custom_scope'
        ],
        clientMetadata: {
            'onBehalfOfToken': 'eyJra789ghiEXAMPLE',
            'ClientIpAddress': '192.0.2.252'
        }
    },
    response: { claimsAndScopeOverrideDetails: null }
}

A resposta retorna um token de acesso. As concessões de credenciais do cliente são para autorização máquina-a-máquina (M2M) e retornam somente tokens de acesso.


HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Tue, 05 Dec 2023 16:11:11 GMT
x-amz-cognito-request-id: 829f4fe2-a1ee-476e-b834-5cd85c03373b

{
    "access_token": "eyJra12345EXAMPLE",
    "expires_in": 3600,
    "token_type": "Bearer"
}

Concessão de código de autorização com PKCE

O exemplo a seguir conclui uma solicitação de autorização que incluiu os parâmetros code_challenge_method e code_challenge em uma solicitação de concessão de código de autorização com PKCE.


POST https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token
Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw

grant_type=authorization_code&
client_id=1example23456789&
code=AUTHORIZATION_CODE&
code_verifier=CODE_VERIFIER&
redirect_uri=com.myclientapp://myclient/redirect

A resposta retorna tokens de ID, acesso e atualização da verificação bem-sucedida do PKCE pela aplicação.


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

{
    "access_token": "eyJra1example",
    "id_token": "eyJra2example",
    "refresh_token": "eyJj3example",
    "token_type": "Bearer",
    "expires_in": 3600
}

Atualização de token sem alternância de tokens de atualização

O exemplo de solicitações a seguir fornece um token de atualização para um cliente de aplicação no qual a alternância de tokens de atualização está inativa. Como o cliente de aplicação tem um segredo do cliente, a solicitação fornece um cabeçalho Authorization.


POST https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token >
Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw

grant_type=refresh_token&
client_id=1example23456789&
refresh_token=eyJj3example

A resposta retorna novos tokens de ID e acesso.


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

{
    "access_token": "eyJra1example",
    "id_token": "eyJra2example",
    "token_type": "Bearer",
    "expires_in": 3600
}

Atualização de token com alternância de tokens de atualização

O exemplo de solicitações a seguir fornece um token de atualização para um cliente de aplicação no qual a alternância de tokens de atualização está ativa. Como o cliente de aplicação tem um segredo do cliente, a solicitação fornece um cabeçalho Authorization.


POST https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token >
Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw

grant_type=refresh_token&
client_id=1example23456789&
refresh_token=eyJj3example

A resposta retorna novos tokens de ID, acesso e atualização.


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

{
    "access_token": "eyJra1example",
    "id_token": "eyJra2example",
    "refresh_token": "eyJj4example",
    "token_type": "Bearer",
    "expires_in": 3600
}

Exemplos de respostas negativas

Solicitações malformadas geram erros no endpoint de token. Veja a seguir um mapa geral do corpo da resposta quando as solicitações de token geram um erro.


HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
"error":"invalid_request|invalid_client|invalid_grant|unauthorized_client|unsupported_grant_type"
}

invalid_request

A solicitação não tem um parâmetro obrigatório, inclui um valor de parâmetro não compatível (diferente de unsupported_grant_type) ou está malformado. Por exemplo, grant_type é refresh_token , mas refresh_token não está incluído.

invalid_client

Falha na autenticação do cliente. Por exemplo, quando o cliente inclui client_id e client_secret no cabeçalho de autorização, mas não há tal cliente com esse client_id e client_secret.

invalid_grant

O token de atualização foi revogado.

O código de autorização já foi consumido ou não existe.

O cliente da aplicação não tem acesso de leitura a todos os atributos no escopo solicitado. Por exemplo, a aplicação solicita o escopo email e o cliente da aplicação consegue ler o atributo email, mas não email_verified.

unauthorized_client

O cliente não tem permissão para fluxo de concessão de código ou para tokens de atualização.

unsupported_grant_type

Retornado se grant_type for diferente de authorization_code, refresh_token ou client_credentials.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Autorizar endpoint

endpoint userinfo