Point de terminaison d’autorisation

Le point de terminaison /oauth2/authorize est un point de terminaison de redirection qui prend en charge deux destinations de redirection Si vous incluez un paramètre identity_provider ou idp_identifier dans l’URL, il redirige en mode silencieux votre utilisateur vers la page de connexion de ce fournisseur d’identité (IdP). Sinon, il redirige vers le Point de terminaison de connexion avec les mêmes paramètres d’URL que ceux que vous avez inclus dans votre demande.

Le point de terminaison d’autorisation redirige vers l’interface utilisateur hébergée ou vers la page de connexion de l’IdP. La destination d’une session utilisateur sur ce point de terminaison est une page Web avec laquelle votre utilisateur doit interagir directement dans son navigateur.

Pour utiliser le point de terminaison d’autorisation, appelez le navigateur de votre utilisateur à l’adresse /oauth2/authorize avec des paramètres qui fournissent à votre groupe d’utilisateurs des informations sur les détails suivants du groupe d’utilisateurs.

• Client d’application auquel vous souhaitez vous connecter.

• URL de rappel à laquelle vous souhaitez accéder.

• Les portées OAuth 2.0 que vous souhaitez demander dans le jeton d’accès de votre utilisateur.

• IdP tiers (facultatif) que vous souhaitez utiliser pour vous connecter.

Vous pouvez également fournir les paramètres state et nonce utilisés par Amazon Cognito pour valider les demandes entrantes.

GET /oauth2/authorize

Le point de terminaison /oauth2/authorize prend uniquement en charge HTTPS GET. Votre application lance généralement cette demande dans le navigateur de votre utilisateur. Vous pouvez adresser vos demandes au point de terminaison /oauth2/authorize uniquement via HTTPS.

Pour en savoir plus sur la définition du point de terminaison d’autorisation dans la norme OpenID Connect (OIDC), veuillez consulter Authorization Endpoint (français non disponible).

Paramètres de demande

response_type

(Obligatoire) Type de réponse. Doit être code ou token.

Une demande réussie avec un response_type égal à code renvoie un octroi de code d’autorisation. L’octroi de code d’autorisation est un paramètre code ajouté par Amazon Cognito à votre URL de redirection. Votre application peut échanger ce code avec le Point de terminaison de jeton pour obtenir les jetons d’accès, d’identification et d’actualisation. À titre de bonne pratique en matière de sécurité et pour recevoir des jetons d’actualisation pour vos utilisateurs, utilisez un octroi de code d’autorisation dans votre application.

Une demande réussie avec un response_type égal à token renvoie un octroi implicite. Un octroi implicite est un jeton d’identifiant et d’accès ajouté par Amazon Cognito à votre URL de redirection. Un octroi implicite est moins sûr car il expose les jetons et les informations d’identification potentielles aux utilisateurs. Vous pouvez désactiver la prise en charge des octrois implicites dans la configuration de votre client d’application.

client_id

(Obligatoire) L'ID du client de l'application.

La valeur de client_id doit être l’ID d’un client d’application du groupe d’utilisateurs dans lequel vous effectuez la demande. Votre client d’application doit prendre en charge la connexion par des utilisateurs locaux Amazon Cognito ou par au moins un fournisseur d’identité tiers.

redirect_uri

(Obligatoire) URL vers laquelle le serveur d'authentification redirige le navigateur une fois qu'Amazon Cognito a autorisé l'utilisateur.

Un identificateur de ressource uniforme (URI) de redirection doit avoir les attributs suivants :

• Il doit s’agir d’un URI absolu.

• Vous devez avoir préalablement enregistré l’URI avec un client.

• Il ne peut pas inclure un composant de fragment.

Veuillez consulter OAuth 2.0 - Redirection Endpoint.

Amazon Cognito exige que votre URI de redirection utilise HTTPS, à l’exception de http://localhost, que vous pouvez définir comme URL de rappel à des fins de test.

Amazon Cognito prend également en charge les URL de rappel d’application comme myapp://example.

state

(Facultatif, recommandé) Lorsque votre application ajoute un paramètre d'état à une demande, Amazon Cognito renvoie sa valeur à votre application lorsque le /oauth2/authorize point de terminaison redirige votre utilisateur.

Ajoutez cette valeur à vos demandes afin de protéger votre système contre les attaques CSRF (cross-site request forgery, falsification de requête intersites).

Vous ne pouvez pas définir la valeur d’un paramètre state sur une chaîne JSON encodée par URL. Pour transmettre une chaîne correspondant à ce format dans un state paramètre, encodez-la en base64, puis décodez-la dans votre application.

identity_provider

(Facultatif) Ajoutez ce paramètre pour contourner l'interface utilisateur hébergée et rediriger votre utilisateur vers la page de connexion d'un fournisseur. La valeur du paramètre identity_provider est le nom du fournisseur d’identité, tel qu’il apparaît dans votre groupe d’utilisateurs.

• Pour les fournisseurs sociaux, vous pouvez utiliser les valeurs identity_providerFacebook,Google, LoginWithAmazon et. SignInWithApple

• Pour les groupes d'utilisateurs Amazon Cognito, utilisez la valeur. COGNITO

• Pour les fournisseurs d'identité SAML 2.0 et OpenID Connect (OIDC) (IdPs), utilisez le nom que vous avez attribué à l'IdP dans votre groupe d'utilisateurs.

idp_identifier

(Facultatif) Ajoutez ce paramètre pour rediriger vers un fournisseur avec un autre nom pour le nom identity_provider. Vous pouvez saisir des identifiants pour vos fichiers SAML 2.0 et OIDC IdPs depuis l'onglet Expérience de connexion de la console Amazon Cognito.

scope

(Facultatif) Il peut s'agir d'une combinaison d'étendues réservées au système ou de portées personnalisées associées à un client. Les périmètres doivent être séparés par des espaces. Les périmètres dédiés à un système sont openid, email, phone, profile et aws.cognito.signin.user.admin. Tout périmètre utilisé doit être associé au client. Dans le cas contraire, il sera ignoré lors de l’exécution.

Si le client ne demande pas de périmètre, le serveur d’authentification utilise tous les périmètres associés au client.

Un jeton d’identification est renvoyé uniquement si le paramètre openid est demandé. Le jeton d’accès peut être utilisé pour des groupes d’utilisateurs Amazon Cognito que si le périmètre aws.cognito.signin.user.admin est demandé. Les paramètres scope phone, email et profile peuvent uniquement être demandés si le paramètre scope openid est également demandé. Ces paramètres scope régissent les revendications qui font partie du jeton d’identification.

code_challenge_method

(Facultatif) Le protocole de hachage que vous avez utilisé pour générer le défi. Le PKCE RFC définit deux méthodes, S256 et « plain » . Cependant, le serveur d’authentification Amazon Cognito ne prend en charge que la méthode S256.

code_challenge

(Facultatif) Le défi que vous avez généré à partir ducode_verifier.

Obligatoire uniquement lorsque vous spécifiez un paramètre code_challenge_method.

nonce

(Facultatif) Une valeur aléatoire que vous pouvez ajouter à la demande. La valeur nonce que vous fournissez est incluse dans le jeton d’identification émis par Amazon Cognito. Pour se prémunir contre les attaques par rejeu, votre application peut inspecter la revendication nonce dans le jeton d’identification et la comparer à celle que vous avez générée. Pour de plus amples informations sur la revendication nonce, veuillez consulter ID token validation (français non disponible) dans la norme OpenID Connect.

Exemples de demandes avec réponses positives

Les exemples suivants illustrent le format des requêtes HTTP adressées au /oauth2/authorize point de terminaison.

Octroi de code d’autorisation

Il s'agit d'un exemple de demande d'octroi de code d'autorisation.

Exemple — requête GET

La demande suivante lance une session pour récupérer un code d'autorisation que votre utilisateur transmet à votre application à redirect_uri destination. Cette session demande les champs d'application des attributs utilisateur et l'accès aux opérations de l'API en libre-service 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

Exemple — réponse

Le serveur d’authentification Amazon Cognito effectue une redirection vers votre application avec le code d’autorisation et l’état. Le code d'autorisation est valide pendant cinq minutes.

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

Octroi de code d’autorisation avec PKCE

Il s'agit d'un exemple de demande d'octroi de code d'autorisation avec PKCE.

Exemple — requête GET

La demande suivante ajoute un code_challenge paramètre à la demande précédente. Pour terminer l'échange d'un code contre un jeton, vous devez inclure le code_verifier paramètre dans votre demande au /oauth2/token point de terminaison.

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

Exemple — réponse

Le serveur d'authentification redirige vers votre application avec le code d'autorisation et l'état. Le code et l'état doivent être renvoyés dans les paramètres de la chaîne de requête et non dans le fragment :

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

Octroi de jeton sans paramètre de périmètre openid

Il s'agit d'un exemple de demande qui génère une autorisation implicite et renvoie les JWT directement à la session de l'utilisateur.

Exemple — requête GET

La demande suivante concerne une autorisation implicite de la part de votre serveur d'autorisation. Le jeton d'accès d'Amazon Cognito autorise les opérations d'API en libre-service.

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

Exemple — réponse

Le serveur d’autorisation Amazon Cognito effectue une redirection vers votre application avec un jeton d’accès. Comme la portée openid n’a pas été demandée, Amazon Cognito ne renvoie pas de jeton d’identification. De plus, Amazon Cognito ne renvoie pas de jeton d’actualisation dans ce flux. Amazon Cognito renvoie le jeton d'accès et l'état dans le fragment et non dans la chaîne de requête :

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

Octroi de jeton avec paramètre de portée openid

Il s'agit d'un exemple de demande qui génère une autorisation implicite et renvoie les JWT directement à la session de l'utilisateur.

Exemple — requête GET

La demande suivante concerne une autorisation implicite de la part de votre serveur d'autorisation. Le jeton d'accès d'Amazon Cognito autorise l'accès aux attributs utilisateur et aux opérations d'API en libre-service.

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
                    

Exemple — réponse

Le serveur d'autorisation redirige vers votre application avec un jeton d'accès et un jeton d'identification (car le openid champ d'application a été inclus) :

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

Exemples de réponses négatives

Amazon Cognito peut refuser votre demande. Les demandes négatives sont accompagnées d'un code d'erreur HTTP et d'une description que vous pouvez utiliser pour corriger les paramètres de votre demande. Voici des exemples de réponses négatives.

• Si client_id et redirect_uri sont valides, mais que les paramètres de la demande ne sont pas correctement formatés, le serveur d'authentification redirige l'erreur vers celle du client redirect_uri et ajoute un message d'erreur dans un paramètre d'URL. Voici des exemples de formatage incorrect.

  • La demande n'inclut aucun response_type paramètre.

  • La demande d'autorisation a fourni un code_challenge paramètre, mais pas un code_challenge_method paramètre.

  • La valeur du code_challenge_method paramètre ne l'est pasS256.

  Voici la réponse à un exemple de demande dont le formatage est incorrect.

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

• Si le client demande code ou reçoit token ces demandesresponse_type, mais qu'il n'est pas autorisé à les traiter, le serveur d'autorisation Amazon Cognito retourne unauthorized_client vers celui du clientredirect_uri, comme suit :

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

• Si le client demande une portée inconnue, incorrecte ou non valide, le serveur d’autorisation Amazon Cognito renvoie invalid_scope à l’URI redirect_uri du client, comme suit :

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

• En cas d'erreur inattendue sur le serveur, le serveur d'authentification server_error revient sur celui du clientredirect_uri. Comme l'erreur HTTP 500 n'est pas envoyée au client, elle ne s'affiche pas dans le navigateur de l'utilisateur. Le serveur d'autorisation renvoie l'erreur suivante.

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

• Lorsqu'Amazon Cognito s'authentifie par le biais d'une fédération auprès d'un tiers, Amazon IdPs Cognito peut rencontrer des problèmes de connexion, tels que les suivants :

  • Si un délai de connexion se produit lors de la demande d’un jeton auprès du fournisseur d’identité, le serveur d’authentification redirige l’erreur vers l’URI redirect_uri du client de la façon suivante :

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

  • En cas d'expiration du délai de connexion lors de l'appel du jwks_uri point de terminaison pour la validation du jeton d'identification, le serveur d'authentification redirige avec une erreur vers celui du client redirect_uri comme suit :

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

• Lors de l'authentification par fédération auprès d'un tiers IdPs, les fournisseurs peuvent renvoyer des réponses d'erreur. Cela peut être dû à des erreurs de configuration ou à d'autres raisons, telles que les suivantes :

  • Si une réponse d’erreur est reçue de la part d’autres fournisseurs, le serveur d’authentification redirige l’erreur vers le redirect_uri du client de la façon suivante :

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

  • Si une réponse d'erreur est reçue de Google, le serveur d'authentification redirige l'erreur vers le redirect_uri du client de la façon suivante :

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

• Lorsqu'Amazon Cognito rencontre une exception de communication lorsqu'il se connecte à un IdP externe, le serveur d'authentification redirige avec une erreur vers le client avec l'un redirect_uri des messages suivants :

  • 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