O endpoint de redirecionamento e autorização - Amazon Cognito
GET /oauth2/authorizeExemplo: concessão de código de autorizaçãoExemplo: concessão de código de autorização com PKCEExemplo: exigir reautenticação com prompt=loginExemplo: autenticação silenciosa com prompt=noneExemplo: concessão de token (implícita) sem escopo openidExemplo: concessão simbólica (implícita) com escopo openidRespostas de erro

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á.

O endpoint de redirecionamento e autorização

O endpoint /oauth2/authorize é um endpoint de redirecionamento compatível com dois destinos de redirecionamento. Se você incluir um identity_provider ou idp_identifier no URL, ele redirecionará silenciosamente o usuário para a página de login desse provedor de identidades (IdP). Do contrário, ele redirecionará para o Endpoint de login com os mesmos parâmetros de URL que você incluiu em sua solicitação.

O endpoint de autorização redireciona para o login gerenciado ou para uma página de login do IdP. O destino de uma sessão de usuário nesse endpoint é uma página da web com a qual o usuário deve interagir diretamente no navegador.

Para usar o endpoint de autorização, invoque o navegador do usuário em /oauth2/authorize com parâmetros que forneçam ao seu grupo de usuários os detalhes a seguir do grupo de usuários.

  • O cliente da aplicação no qual você deseja fazer login.

  • O URL de retorno de chamada ao qual você deseja chegar.

  • Os escopos OAuth 2.0 que você deseja solicitar no token de acesso do seu usuário.

  • Opcionalmente, o IdP de terceiros que você deseja usar para fazer login.

Você também pode fornecer os parâmetros state e nonce que o Amazon Cognito usa para validar as solicitações recebidas.

GET /oauth2/authorize

O endpoint /oauth2/authorize só é compatível com HTTPS GET. Sua aplicação normalmente inicia essa solicitação no navegador do usuário. Você só pode fazer solicitações ao endpoint /oauth2/authorize por HTTPS.

Você pode saber mais sobre a definição de endpoint de autorização no padrão do OpenID Connect (OIDC) em Authorization Endpoint (Endpoint de autorização).

Parâmetros de solicitação

response_type

Obrigatório.

O tipo de resposta. Precisa ser code ou token.

Uma solicitação bem-sucedida com um response_type do code retorna uma concessão de código de autorização. Uma concessão de código de autorização é um parâmetro code que o Amazon Cognito anexa ao URL de redirecionamento. Sua aplicação pode trocar o código por Endpoint de token para acesso, ID e tokens de atualização. Como prática recomendada de segurança e para receber tokens de atualização para os usuários, use uma concessão de código de autorização na aplicação.

Uma solicitação bem-sucedida com um response_type do token retorna uma concessão implícita. Uma concessão implícita é um ID e um token de acesso que o Amazon Cognito anexa ao URL de redirecionamento. A concessão implícita é menos segura porque expõe tokens e possíveis informações de identificação aos usuários. Você pode desativar o suporte para concessões implícitas na configuração do cliente da aplicação.

client_id

Obrigatório.

O ID do cliente do aplicativo

O valor de client_id deve ser o ID de um cliente da aplicação no grupo de usuários em que você faz a solicitação. O cliente da aplicação deve ser compatível com o login de usuários locais do Amazon Cognito ou pelo menos um IdP de terceiros.

redirect_uri

Obrigatório.

O URL para o qual o servidor de autenticação redireciona o navegador depois que o Amazon Cognito autoriza o usuário.

Um identificador de recurso uniforme (URI) de redirecionamento deve ter os seguintes atributos:

  • Deve ser um URI absoluto.

  • É necessário pré-registrar o URI em um cliente.

  • Não pode incluir um componente de fragmento.

Consulte OAuth 2.0 - Endpoint de redirecionamento.

O Amazon Cognito exige que seu URI de redirecionamento use HTTPS, exceto para http://localhost, que você pode definir como um URL de retorno de chamada para fins de teste.

O Amazon Cognito também oferece suporte ao retorno de chamadas URLs de aplicativos, como. myapp://example

state

Opcional, recomendado.

Quando sua aplicação adiciona um parâmetro state a uma solicitação, o Amazon Cognito retorna o valor para a aplicação quando o endpoint /oauth2/authorize redireciona o usuário.

Adicione esse valor às suas solicitações para se proteger contra ataques CSRF.

Não é possível definir o valor de um parâmetro state como uma string JSON codificada por URL. Para transmitir uma string que corresponda a esse formato em um parâmetro state, codifique-a como Base64 e, depois, decodifique-a em sua aplicação.

identity_provider

Opcional.

Adicione esse parâmetro para ignorar o login gerenciado e redirecionar seu usuário para a página de login de um provedor. O valor do parâmetro identity_provider é o nome do provedor de identidade (IdP) da forma como ele aparece no grupo de usuários.

  • Para provedores sociais, você pode usar os valores identity_providerFacebook, Google e LoginWithAmazon e SignInWithApple.

  • Para grupos de usuários do Amazon Cognito, use o valor COGNITO.

  • Para provedores de identidade SAML 2.0 e OpenID Connect (OIDC) (IdPs), use o nome que você atribuiu ao IdP em seu grupo de usuários.

idp_identifier

Opcional.

Adicione esse parâmetro para redirecionar para um provedor com um nome alternativo para o nome de identity_provider. Você pode inserir identificadores para seu SAML 2.0 e OIDC no menu de provedores sociais e externos IdPs do console do Amazon Cognito.

scope

Opcional.

Pode ser uma combinação de quaisquer escopos reservados ao sistema ou de escopos personalizados associados a um cliente. Os escopos devem ser separados por espaços. Os escopos reservados ao sistema são openid, email, phone, profile e aws.cognito.signin.user.admin. Qualquer escopo usado deve ser associado ao cliente ou ele será ignorado durante o tempo de execução.

Se o cliente não solicita qualquer escopo, o servidor de autenticação usa todos os escopos associados ao cliente.

Um token de ID só é retornado se o escopo openid é solicitado. O token de acesso só pode ser usado com relação a grupos de usuários do Amazon Cognito se o escopo aws.cognito.signin.user.admin é solicitado. Os escopos phone, email e profile só podem ser solicitados se o escopo openid também é solicitado. Esses escopos ditam as solicitações que entram no token de ID.

code_challenge_method

Opcional.

O protocolo de hashing que você usou para gerar o desafio. O PKCE RFC define dois métodos, S256 e simples; no entanto, o servidor de autenticação do Amazon Cognito só é compatível com o S256.

code_challenge

Opcional.

O desafio de prova de troca de código chave (PKCE) que você gerou a code_verifier partir do. Para obter mais informações, consulte Como usar PKCE em concessões de código de autorização.

Obrigatório somente quando você especifica um parâmetro code_challenge_method.

nonce

Opcional.

Um valor aleatório que você pode adicionar à solicitação. O valor nonce fornecido está incluído no token de ID que o Amazon Cognito emite. Para se proteger contra ataques de repetição, a aplicação pode inspecionar a reivindicação nonce no token de ID e compará-la com o que você gerou. Para obter mais informações sobre a solicitação nonce, consulte “ID Token Validation” (Validação de tokens de ID) no OpenID Connect Standard (Padrão do OpenID Connect).

lang

Opcional.

O idioma em que você deseja exibir páginas interativas com o usuário. As páginas de login gerenciadas podem ser localizadas, mas as páginas de interface de usuário hospedadas (clássicas) não. Para obter mais informações, consulte Localização gerenciada de login.

login_hint

Opcional.

Um prompt de nome de usuário que você deseja enviar ao servidor de autorização. Você pode coletar um nome de usuário, endereço de e-mail ou número de telefone do seu usuário e permitir que o provedor de destino preencha previamente o nome de login do usuário. Quando você envia um login_hint parâmetro e nenhum parâmetro idp_identifier ou identity_provider parâmetros para o oauth2/authorize endpoint, o login gerenciado preenche o campo do nome de usuário com o valor da dica. Você também pode passar esse parâmetro para o Endpoint de login e preencher automaticamente o valor do nome de usuário.

Quando sua solicitação de autorização invoca um redirecionamento para o OIDC ou o Google IdPs , o Amazon Cognito adiciona um login_hint parâmetro à solicitação para esse autorizador terceirizado. Você não pode encaminhar dicas de login para SAML, Apple, Login With Amazon ou Facebook (Meta). IdPs

prompt

Opcional.

Um parâmetro OIDC que controla o comportamento de autenticação para sessões existentes. Disponível somente na versão de identidade visual de login gerenciado, não na interface hospedada clássica. Para obter mais informações sobre a especificação do OIDC, consulte Solicitação de autenticação. Os valores none e login têm um efeito no comportamento de autenticação do grupo de usuários.

O Amazon Cognito encaminha todos os valores de, prompt exceto none para o seu, IdPs quando os usuários selecionam a autenticação com provedores terceirizados. Isso ocorre quando o URL que os usuários acessam inclui um idp_identifier parâmetro identity_provider ou, ou quando o servidor de autorização os redireciona para o Endpoint de login e eles selecionam um IdP nos botões disponíveis.

Valores de parâmetros do prompt
prompt=none

O Amazon Cognito continua silenciosamente a autenticação para usuários que têm uma sessão autenticada válida. Com esse prompt, os usuários podem se autenticar silenciosamente entre diferentes clientes de aplicativos em seu grupo de usuários. Se o usuário ainda não estiver autenticado, o servidor de autorização retornará um login_required erro.

prompt=login

O Amazon Cognito exige que os usuários se autentiquem novamente, mesmo que tenham uma sessão existente. Envie esse valor quando quiser verificar a identidade do usuário novamente. Usuários autenticados que tenham uma sessão existente podem retornar ao login sem invalidar essa sessão. Quando um usuário que tem uma sessão existente faz login novamente, o Amazon Cognito atribui a ele um novo cookie de sessão. Esse parâmetro também pode ser encaminhado para o seu IdPs. IdPsque aceitam esse parâmetro também solicitam uma nova tentativa de autenticação do usuário.

prompt=select_account

Esse valor não tem efeito no login local e deve ser enviado em solicitações que redirecionam para o. IdPs Quando incluído na sua solicitação de autorização, esse parâmetro é adicionado prompt=select_account ao caminho da URL para o destino de redirecionamento do IdP. Quando IdPs oferecem suporte a esse parâmetro, eles solicitam que os usuários selecionem a conta com a qual desejam fazer login.

prompt=consent

Esse valor não tem efeito no login local e deve ser enviado em solicitações que redirecionam para o. IdPs Quando incluído na sua solicitação de autorização, esse parâmetro é adicionado prompt=consent ao caminho da URL para o destino de redirecionamento do IdP. Quando IdPs oferecem suporte a esse parâmetro, eles solicitam o consentimento do usuário antes de serem redirecionados de volta para seu grupo de usuários.

Quando você omite o prompt parâmetro da sua solicitação, o login gerenciado segue o comportamento padrão: os usuários devem fazer login, a menos que o navegador tenha um cookie de sessão de login gerenciado válido. Você pode combinar vários valores prompt com um delimitador de caracteres de espaço, por exemplo. prompt=login consent

Exemplo: concessão de código de autorização

Este é um exemplo de solicitação de concessão de código de autorização.

A solicitação a seguir inicia uma sessão para recuperar um código de autorização que seu usuário passa para a aplicação de destino redirect_uri. Essa sessão solicita escopos para atributos de usuário e acesso às operações da API de autoatendimento do Amazon Cognito.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=openid+profile+aws.cognito.signin.user.admin

O servidor de autenticação do Amazon Cognito faz o redirecionamento de volta à aplicação com o estado e o código de autorização. O código de autorização é válido por cinco minutos.

HTTP/1.1 302 Found
Location: https://www.example.com?code=a1b2c3d4-5678-90ab-cdef-EXAMPLE11111&state=abcdefg

Exemplo: concessão de código de autorização com PKCE

Esse exemplo de fluxo executa uma concessão de código de autorização com o PKCE.

Essa solicitação adiciona um code_challenge parâmetro. Para concluir a troca de um código por um token, você deve incluir o parâmetro code_verifier em sua solicitação para o endpoint /oauth2/token.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=aws.cognito.signin.user.admin&
code_challenge_method=S256&
code_challenge=a1b2c3d4...

O servidor de autorização redireciona de volta para seu aplicativo com o código e o estado da autorização. Seu aplicativo processa o código de autorização e o troca por tokens.

HTTP/1.1 302 Found
Location: https://www.example.com?code=a1b2c3d4-5678-90ab-cdef-EXAMPLE11111&state=abcdefg

Exemplo: exigir reautenticação com prompt=login

A solicitação a seguir adiciona um prompt=login parâmetro que exige que o usuário se autentique novamente, mesmo que tenha uma sessão existente.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=openid+profile+aws.cognito.signin.user.admin&
prompt=login

O servidor de autorização redireciona para o endpoint de login, exigindo uma nova autenticação.

HTTP/1.1 302 Found Location: https://mydomain.auth.us-east-1.amazoncognito.com/login?response_type=code&client_id=1example23456789&redirect_uri=https://www.example.com&state=abcdefg&scope=openid+profile+aws.cognito.signin.user.admin&prompt=login

Exemplo: autenticação silenciosa com prompt=none

A solicitação a seguir adiciona um prompt=none parâmetro que verifica silenciosamente se o usuário tem uma sessão válida.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=openid+profile+aws.cognito.signin.user.admin&
prompt=none

Quando não existe uma sessão válida, o servidor de autorização retorna um erro ao URI de redirecionamento

HTTP/1.1 302 Found Location: https://www.example.com?error=login_required&state=abcdefg

Quando existe uma sessão válida, o servidor de autorização retorna um código de autorização.

HTTP/1.1 302 Found Location: https://www.example.com?code=AUTHORIZATION_CODE&state=abcdefg

Exemplo: concessão de token (implícita) sem escopo openid

Esse exemplo de fluxo gera uma concessão implícita e retorna JWTs diretamente para a sessão do usuário.

A solicitação é para uma concessão implícita do seu servidor de autorização. Ele solicita escopos no token de acesso que autorizam as operações de autoatendimento do perfil do usuário.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=token&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=aws.cognito.signin.user.admin

O servidor de autorização redireciona de volta para seu aplicativo somente com um token de acesso. Como o escopo openid não foi solicitado, o Amazon Cognito não retorna um token de ID. Além disso, o Amazon Cognito não retorna um token de atualização nesse fluxo.

HTTP/1.1 302 Found
Location: https://example.com/callback#access_token=eyJra456defEXAMPLE&token_type=bearer&expires_in=3600&state=STATE

Exemplo: concessão simbólica (implícita) com escopo openid

Esse exemplo de fluxo gera uma concessão implícita e retorna tokens para o navegador do usuário.

A solicitação é para uma concessão implícita do seu servidor de autorização. Ele solicita escopos no token de acesso que autorizam o acesso aos atributos do usuário e às operações de autoatendimento.

GET
https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize? 
response_type=token& 
client_id=1example23456789& 
redirect_uri=https://www.example.com& 
state=abcdefg&
scope=aws.cognito.signin.user.admin+openid+profile

O servidor de autorização redireciona de volta para seu aplicativo com o token de acesso e o token de ID (porque o openid escopo foi incluído):

HTTP/1.1 302 Found
Location: https://www.example.com#id_token=eyJra67890EXAMPLE&access_token=eyJra12345EXAMPLE&token_type=bearer&expires_in=3600&state=abcdefg

Exemplos de respostas negativas

O Amazon Cognito pode negar sua solicitação. As solicitações negativas vêm com um código de erro HTTP e uma descrição que você pode usar para corrigir os parâmetros da solicitação. Veja a seguir exemplos de respostas negativas.

  • Se client_id e redirect_uri forem válidos, mas os parâmetros da solicitação não estiverem formatados corretamente, o servidor de autenticação redirecionará o erro para o redirect_uri do cliente e anexará uma mensagem de erro em um parâmetro de URL. Veja a seguir exemplos de formatos incorretos.

    • A solicitação não inclui um parâmetro response_type.

    • A solicitação de autorização forneceu um parâmetro code_challenge, mas não um parâmetro code_challenge_method.

    • O valor do parâmetro code_challenge_method não é S256.

    Veja a seguir um exemplo de resposta para a solicitação com formato incorreto.

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request

  • Se o cliente solicitar code ou token em response_type, mas não tiver permissão para essas solicitações, o servidor de autorização do Amazon Cognito retornará unauthorized_client ao redirect_uri do cliente da seguinte forma:

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=unauthorized_client

  • Se o cliente solicitar um escopo inválido, desconhecido ou malformado, o servidor de autorização do Amazon Cognito deverá retornar o invalid_scope ao redirect_uri do cliente da seguinte forma: 

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_scope

  • Se acontece um erro inesperado no servidor, o servidor de autenticação retorna server_error ao redirect_uri do cliente. Como o erro HTTP 500 não é enviado ao cliente, ele não aparece no navegador do usuário. O servidor de autorização retorna o erro a seguir.

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=server_error

  • Quando o Amazon Cognito se autentica por meio de federação para terceiros, IdPs o Amazon Cognito pode enfrentar problemas de conexão, como os seguintes:

    • Se ocorrer um tempo limite de conexão ao solicitar o token do IdP, o servidor de autenticação redirecionará o erro para o redirect_uri do cliente da seguinte maneira:

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Timeout+occurred+in+calling+IdP+token+endpoint

    • Se ocorrer um tempo limite de conexão na chamada do endpoint jwks_uri para validação do token de ID, o servidor de autenticação redirecionará o erro para o redirect_uri do cliente da seguinte maneira:

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=error_description=Timeout+in+calling+jwks+uri

  • Ao se autenticar por meio de federação com terceiros IdPs, os provedores podem retornar respostas de erro. Isso pode acontecer em razão de erros de configuração ou outros motivos, como os seguintes:

    • Se uma resposta de erro for recebida de outros provedores, o servidor de autenticação redirecionará o erro para o redirect_uri do cliente da seguinte maneira:

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=[IdP name]+Error+-+[status code]+error getting token

    • Se uma resposta de erro for recebida do Google, o servidor de autenticação redirecionará o erro para o redirect_uri do cliente da seguinte maneira: 

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Google+Error+-+[status code]+[Google-provided error code]

  • Quando o Amazon Cognito encontra uma exceção de comunicação com um IdP externo, o servidor de autenticação redireciona o erro para o redirect_uri do cliente com uma das seguintes mensagens:

    • HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Connection+reset
    • HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Read+timed+out