O endpoint de redirecionamento e autorização - Amazon Cognito
GET /oauth2/authorizeExemplos de solicitações com respostas positivasExemplos de respostas negativas

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 idp_identifier parâmetro identity_provider ou noURL, ele redirecionará silenciosamente seu usuário para a página de login desse provedor de identidade (IdP). Caso contrário, ele redirecionará para o Endpoint de login com os mesmos URL parâmetros que você incluiu na sua solicitação.

O endpoint de autorização redireciona para a interface de usuário hospedada 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 retorno de chamada em URL que você deseja terminar.

  • 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 para o /oauth2/authorize endpoint overHTTPS.

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

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 code parâmetro que o Amazon Cognito anexa ao seu redirecionamento. URL 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 é uma ID e um token de acesso que o Amazon Cognito anexa ao seu redirecionamento. URL 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) URL Onde o servidor de autenticação redireciona o navegador após o Amazon Cognito autorizar o usuário.

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

  • Deve ser absolutoURI.

  • Você deve ter pré-registrado o URI com um cliente.

  • Não pode incluir um componente de fragmento.

Consulte OAuth2.0 - Endpoint de redirecionamento.

O Amazon Cognito exige que você redirecione URI o uso HTTPShttp://localhost, exceto aquele que você pode definir como retorno de chamada URL 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 seu aplicativo adiciona um parâmetro de estado a uma solicitação, o Amazon Cognito retorna seu valor ao seu aplicativo quando o /oauth2/authorize endpoint redireciona seu usuário.

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

Você não pode definir o valor de um state parâmetro como uma string URL codificada em JSON -. Para passar uma string que corresponda a esse formato em um state parâmetro, codifique a string em base64 e decodifique-a no seu aplicativo.

identity_provider

(Opcional) Adicione esse parâmetro para ignorar a interface hospedada 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 SignInWithApple

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

  • Para SAML 2.0 e OpenID Connect (OIDC) provedores de identidade (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 identity_provider. Você pode inserir identificadores para seu SAML 2.0 e na guia Experiência OIDC IdPs de login do console do Amazon Cognito.

scope

(Opcional) Pode ser uma combinação de qualquer escopo reservado pelo sistema ou escopo personalizado associado 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ê usou para gerar o desafio. Ele PKCERFCdefine dois métodos, S256 e plain; no entanto, o servidor de autenticação Amazon Cognito suporta somente S256.

code_challenge

(Opcional) O desafio de prova de troca de código chave (PKCE) que você gerou a partir docode_verifier. Para obter mais informações, consulte Usando 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).

login_hint

Um prompt de nome de usuário que você deseja passar para o 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, a interface do usuário hospedada 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 OIDC IdPs ou para o Google, o Amazon Cognito adiciona um login_hint parâmetro à solicitação para esse autorizador terceirizado. Você não pode encaminhar dicas de login para AppleSAML, Login With Amazon ou Facebook (Meta) IdPs.

Exemplos de solicitações com respostas positivas

Os exemplos a seguir ilustram o formato das HTTP solicitações para o /oauth2/authorize endpoint.

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

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

Exemplo — GET solicitação

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

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
Exemplo — resposta

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

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

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

Exemplo — GET solicitação

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

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...
Exemplo — resposta

O servidor de autenticação redireciona de volta para seu aplicativo com o código e o estado da autorização. O código e o estado devem ser retornados nos parâmetros da string de consulta e não no fragmento:

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

Concessão de token sem escopo openid

Esse é um exemplo de solicitação que gera uma concessão implícita e retorna JWTs diretamente para a sessão do usuário.

Exemplo — GET solicitação

A solicitação a seguir é para uma concessão implícita do seu servidor de autorização. O token de acesso do Amazon Cognito autoriza operações de autoatendimento. API

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
Exemplo — resposta

O servidor de autorização do Amazon Cognito faz o redirecionamento de volta à aplicação com 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. O Amazon Cognito retorna o token de acesso e o estado no fragmento e não na string de consulta:

HTTP/1.1 302 Found
Location: https://YOUR_APP/redirect_uri#access_token=ACCESS_TOKEN&token_type=bearer&expires_in=3600&state=STATE

Concessão de token com escopo openid

Esse é um exemplo de solicitação que gera uma concessão implícita e retorna JWTs diretamente para a sessão do usuário.

Exemplo — GET solicitação

A solicitação a seguir é para uma concessão implícita do seu servidor de autorização. O token de acesso do Amazon Cognito autoriza o acesso aos atributos do usuário e às operações de autoatendimento. API

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
Exemplo — resposta

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 HTTP erro 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 do cliente redirect_uri e anexará uma mensagem de erro em um parâmetro. URL Veja a seguir exemplos de formatação incorreta.

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

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

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

    Veja a seguir a resposta a um exemplo de solicitação com formatação incorreta.

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

  • Se o cliente solicitar code ou entrar tokenresponse_type, mas não tiver permissão para essas solicitações, o servidor de autorização do Amazon Cognito retornará unauthorized_client ao do clienteredirect_uri, 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 houver algum erro inesperado no servidor, o servidor de autenticação retornará server_error ao servidor do clienteredirect_uri. Como o erro HTTP 500 não é enviado ao cliente, o erro não é exibido no navegador do usuário. O servidor de autorização retorna o seguinte erro.

    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 ao chamar o jwks_uri endpoint para validação do token de ID, o servidor de autenticação redirecionará com um erro para o cliente da seguinte forma: redirect_uri

      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 ser devido a 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 ao se conectar a um IdP externo, o servidor de autenticação redireciona com um erro para o cliente com uma das seguintes mensagens: redirect_uri

    • 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