Le point de terminaison de redirection et d'autorisation - Amazon Cognito
GET /oauth2/authorizeExemple : octroi d'un code d'autorisationExemple : octroi de code d'autorisation avec PKCEExemple : exiger une nouvelle authentification avec prompt=loginExemple : authentification silencieuse avec prompt=noneExemple : octroi de code d'autorisation avec liaison de ressourcesExemple : octroi de jetons (implicite) sans openid portéeExemple : subvention symbolique (implicite) avec openid portéeRéponses d'erreur

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Le point de terminaison de redirection et 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 autorisé redirige soit vers une connexion gérée, soit vers une page de connexion 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 étendues 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.

ID du client d'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.

Voir OAuth 2.0 - Point de terminaison de redirection.

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 le rappel d'applications telles URLs que. myapp://example

state

Facultatif, recommandé.

Lorsque votre application ajoute un paramètre state à une demande, Amazon Cognito renvoie sa valeur à votre application quand le point de terminaison /oauth2/authorize 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 la connexion géré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 votre SAML 2.0 et votre OIDC IdPs depuis le menu Réseaux sociaux et fournisseurs externes de la console Amazon Cognito.

scope

Facultatif.

Peut être une combinaison de tous les périmètres réservés au système ou personnalisées qui sont 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 de preuve d'échange de code clé (PKCE) que vous avez généré à partir ducode_verifier. Pour de plus amples informations, veuillez consulter Utilisation du PKCE dans l'octroi de codes d'autorisation.

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

nonce

Facultatif.

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.

lang

Facultatif.

Langue dans laquelle vous souhaitez afficher les pages interactives avec l'utilisateur. Les pages de connexion gérées peuvent être localisées, mais pas les pages d'interface utilisateur hébergée (classiques). Pour de plus amples informations, veuillez consulter Localisation des connexions gérées.

login_hint

Facultatif.

Une demande de nom d'utilisateur que vous souhaitez transmettre au serveur d'autorisation. Vous pouvez collecter un nom d'utilisateur, une adresse e-mail ou un numéro de téléphone auprès de votre utilisateur et autoriser le fournisseur de destination à prérenseigner le nom de connexion de l'utilisateur. Lorsque vous soumettez un login_hint paramètre et un numéro idp_identifier ou des identity_provider paramètres au point de oauth2/authorize terminaison, la connexion gérée remplit le champ du nom d'utilisateur avec votre valeur d'indice. Vous pouvez également transmettre ce paramètre au Point de terminaison de connexion et remplir automatiquement la valeur du nom d'utilisateur.

Lorsque votre demande d'autorisation appelle une redirection vers OIDC IdPs ou Google, Amazon Cognito ajoute login_hint un paramètre à la demande à cet autorisateur tiers. Vous ne pouvez pas transférer les indications de connexion vers SAML, Apple, Login With Amazon ou Facebook (Meta). IdPs

prompt

Facultatif.

Paramètre OIDC qui contrôle le comportement d'authentification pour les sessions existantes. Disponible uniquement dans la version de marque de connexion gérée, et non dans l'interface utilisateur hébergée classique. Pour plus d'informations sur la spécification OIDC, consultez la section Demande d'authentification. Les valeurs none login ont un effet sur le comportement d'authentification du groupe d'utilisateurs.

Amazon Cognito transmet toutes les valeurs de prompt sauf none à vous IdPs lorsque les utilisateurs sélectionnent l'authentification auprès de fournisseurs tiers. Cela est vrai lorsque l'URL à laquelle les utilisateurs accèdent inclut un idp_identifier paramètre identity_provider ou, ou lorsque le serveur d'autorisation les redirige vers le Point de terminaison de connexion et ils sélectionnent un IdP parmi les boutons disponibles.

Valeurs de paramètres rapides
prompt=none

Amazon Cognito poursuit silencieusement l'authentification pour les utilisateurs disposant d'une session authentifiée valide. Grâce à cette invite, les utilisateurs peuvent s'authentifier silencieusement entre les différents clients d'applications de votre groupe d'utilisateurs. Si l'utilisateur n'est pas déjà authentifié, le serveur d'autorisation renvoie une login_required erreur.

prompt=login

Amazon Cognito demande aux utilisateurs de s'authentifier à nouveau même s'ils ont déjà une session. Envoyez cette valeur lorsque vous souhaitez vérifier à nouveau l'identité de l'utilisateur. Les utilisateurs authentifiés qui ont une session existante peuvent revenir à la connexion sans invalider cette session. Lorsqu'un utilisateur ayant une session existante se reconnecte, Amazon Cognito lui attribue un nouveau cookie de session. Ce paramètre peut également être transmis à votre IdPs. IdPsqui acceptent ce paramètre demandent également une nouvelle tentative d'authentification à l'utilisateur.

prompt=select_account

Cette valeur n'a aucun effet sur la connexion locale et doit être soumise dans les demandes redirigées vers IdPs. Lorsqu'il est inclus dans votre demande d'autorisation, ce paramètre prompt=select_account s'ajoute au chemin URL de la destination de redirection IdP. Lorsque ce paramètre est pris en IdPs charge, ils demandent aux utilisateurs de sélectionner le compte avec lequel ils souhaitent se connecter.

prompt=consent

Cette valeur n'a aucun effet sur la connexion locale et doit être soumise dans les demandes redirigées vers IdPs. Lorsqu'il est inclus dans votre demande d'autorisation, ce paramètre prompt=consent s'ajoute au chemin URL de la destination de redirection IdP. Lorsqu'ils IdPs prennent en charge ce paramètre, ils demandent le consentement de l'utilisateur avant de rediriger vers votre groupe d'utilisateurs.

Lorsque vous omettez le prompt paramètre dans votre demande, la connexion gérée suit le comportement par défaut : les utilisateurs doivent se connecter à moins que leur navigateur ne dispose d'un cookie de session de connexion gérée valide. Vous pouvez combiner plusieurs valeurs pour prompt avec un séparateur de caractères d'espace, par exemple. prompt=login consent

resource

Facultatif.

Identifiant d'une ressource que vous souhaitez associer au jeton d'accès dans la aud réclamation. Lorsque vous incluez ce paramètre, Amazon Cognito vérifie que la valeur est une URL et définit l'audience du jeton d'accès obtenu pour la ressource demandée. Vous pouvez demander un serveur de ressources de pool d'utilisateurs avec un identifiant au format URL ou une URL de votre choix. Les valeurs de ce paramètre doivent commencer par https://http://localhost, ou par un schéma d'URL personnalisé tel quemyapp://.

La liaison de ressources est définie dans la RFC 8707. Pour plus d'informations sur les serveurs de ressources et les liaisons de ressources, consultez la section Liaison de ressources.

Exemple : octroi d'un code d'autorisation

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

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

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

Exemple : octroi de code d'autorisation avec PKCE

Cet exemple de flux effectue l'octroi d'un code d'autorisation avec PKCE.

Cette demande ajoute un code_challenge paramètre. 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...

Le serveur d'autorisation redirige vers votre application avec le code et l'état d'autorisation. Votre application traite le code d'autorisation et l'échange contre des jetons.

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

Exemple : exiger une nouvelle authentification avec prompt=login

La demande suivante ajoute un prompt=login paramètre qui oblige l'utilisateur à s'authentifier à nouveau, même s'il possède déjà une session.

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

Le serveur d'autorisation redirige vers le point de terminaison de connexion, ce qui nécessite une nouvelle authentification.

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

Exemple : authentification silencieuse avec prompt=none

La requête suivante ajoute un prompt=none paramètre qui vérifie silencieusement si la session de l'utilisateur est valide.

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

Lorsqu'aucune session valide n'existe, le serveur d'autorisation renvoie une erreur à l'URI de redirection

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

Lorsqu'une session valide existe, le serveur d'autorisation renvoie un code d'autorisation.

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

Exemple : octroi de code d'autorisation avec liaison de ressources

La demande suivante ajoute un resource paramètre pour lier le jeton d'accès à un serveur de ressources spécifique. Le jeton d'accès qui en résulte crée les conditions permettant à l'API cible de valider qu'il s'agit du public cible de la demande de l'utilisateur authentifié.

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

Le serveur d'autorisation renvoie un code d'autorisation qui se traduit par un jeton d'accès avec une aud réclamation dehttps://solar-system-data-api.example.com.

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

Exemple : octroi de jetons (implicite) sans openid portée

Cet exemple de flux génère une autorisation implicite et retourne JWTs directement à la session de l'utilisateur.

La demande concerne une autorisation implicite de la part de votre serveur d'autorisation. Il demande dans le jeton d'accès des étendues qui autorisent les opérations en libre-service du profil utilisateur.

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

Le serveur d'autorisation redirige vers votre application avec un jeton d'accès uniquement. 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.

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

Exemple : subvention symbolique (implicite) avec openid portée

Cet exemple de flux génère une autorisation implicite et renvoie des jetons au navigateur de l'utilisateur.

La demande concerne une autorisation implicite de la part de votre serveur d'autorisation. Il demande dans le jeton d'accès des étendues qui autorisent l'accès aux attributs utilisateur et aux opérations 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

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