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: exigência de reautenticação com prompt=loginExemplo: autenticação silenciosa com prompt=noneExemplo: concessão de código de autorização com vinculação de recursosExemplo: concessão de token (implícita) sem escopo openidExemplo: concessão de token (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 a 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 uma página de login do 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 hash que você usa 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 da chave de prova para troca de código (PKCE) que você gerou por meio de code_verifier. 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 no qual você deseja exibir as páginas interativas. As páginas de login gerenciado podem ser localizadas, mas as páginas de IU hospedada (clássica) não. Para obter mais informações, consulte Managed login localization.

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 parâmetro login_hint e nenhum parâmetro idp_identifier ou identity_provider para o endpoint oauth2/authorize, 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 IU hospedada clássica. Para obter mais informações da especificação do OIDC, consulte Authentication request. 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 parâmetro identity_provider ou idp_identifier, 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 de 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 da aplicação no grupo de usuários. Se o usuário ainda não estiver autenticado, o servidor de autorização retornará um erro login_required.

prompt=login

O Amazon Cognito exige que os usuários se autentiquem novamente, mesmo que já tenham uma sessão ativa. 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 com uma sessão ativa 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 solicitação de autorização, esse parâmetro adiciona prompt=select_account ao caminho do 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 solicitação de autorização, esse parâmetro adiciona prompt=consent ao caminho do 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 parâmetro prompt da 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 para prompt com um delimitador de espaço, por exemplo, prompt=login consent.

resource

Opcional.

O identificador de um recurso que você deseja vincular ao token de acesso na declaração aud. Quando você inclui esse parâmetro, o Amazon Cognito valida se o valor é um URL e define o público do token de acesso resultante para o recurso solicitado. Você pode solicitar um servidor de recursos do grupo de usuários com um identificador em formato de URL ou um URL de sua escolha. Os valores desse parâmetro devem começar comhttps://, http://localhost ou com um esquema de URL personalizado, como myapp://.

A vinculação de recursos é definida no RFC 8707. Para obter mais informações sobre servidores de recursos e vinculação de recursos, consulte Vinculação de recursos.

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

Este fluxo de exemplo realiza uma concessão de código de autorização com PKCE.

Esta solicitação adiciona um parâmetro code_challenge. 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 à aplicação com o estado e o código de autorização. Sua aplicação 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: exigência de reautenticação com prompt=login

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

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 parâmetro prompt=none 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 há 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 há 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 código de autorização com vinculação de recursos

A solicitação a seguir adiciona um parâmetro resource para vincular o token de acesso a um servidor de recursos específico. O token de acesso resultante cria as condições para que a API de destino valide que é o público-alvo da solicitação do usuário autenticado.

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=solar-system-data-api.example.com/asteroids.add&
resource=https://solar-system-data-api.example.com

O servidor de autorização retorna um código de autorização que resulta em um token de acesso com uma declaração aud de https://solar-system-data-api.example.com.

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. Ela 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 à aplicação 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 de token (implícita) com escopo openid

Este fluxo de exemplo 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. Ela solicita escopos no token de acesso que autorizam o acesso a atributos do usuário e 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 à aplicação com token de acesso e token de ID (porque o escopo openid 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 ter 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