View a markdown version of this page

Le point de terminaison de redirection et d'autorisation - Amazon Cognito
OBTENIR/oauth2/authorizeExemple : attribution d'un code d'autorisationExemple : attribution d'un code d'autorisation avec PKCEExemple : exiger une nouvelle authentification avec prompt=loginExemple : authentification silencieuse avec prompt=noneExemple : attribution d'un code d'autorisation avec liaison de ressourcesExemple : octroi de jeton (implicite) sans étendue openidExemple : octroi de jeton (implicite) avec une portée openidRé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 la 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 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.

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

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 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 state paramètre sur une chaîne URL-encoded JSON. Pour transmettre une chaîne correspondant à ce format dans un state paramètre, codez la chaîne 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 valeurCOGNITO.

  • 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 les identifiants de votre SAML 2.0 et de votre OIDC dans le IdPs 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 challenge. 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 de PKCE dans l'attribution 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 pour l'utilisateur. Les pages de connexion gérées peuvent être localisées, mais pas les pages d'interface utilisateur hébergées (classiques). Pour de plus amples informations, veuillez consulter Localisation des connexions gérées.

login_hint

Facultatif.

Une invite 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 aucun idp_identifier identity_provider paramètre au oauth2/authorize terminal, la connexion gérée remplit le champ du nom d'utilisateur avec la valeur de votre indice. Vous pouvez également transmettre ce paramètre à la valeur du nom d'utilisateur 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, Amazon Cognito ajoute un login_hint paramètre à la demande adressée à cet autorisateur tiers. Vous ne pouvez pas transmettre les conseils de connexion à SAML, Apple, Login with Amazon, Google 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 la marque de connexion gérée, pas dans l'interface utilisateur hébergée classique. Pour plus d'informations sur la spécification OIDC, voir Demande https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest 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 à la vôtre 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 qu'ils sélectionnent un IdP parmi les boutons disponibles.

Valeurs de paramètres rapides
prompt=none

Amazon Cognito poursuit l'authentification en mode silencieux pour les utilisateurs qui disposent 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 disposent d'une session existante peuvent revenir à la connexion sans invalider cette session. Lorsqu'un utilisateur disposant d'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 qui redirigent vers IdPs. Lorsqu'il est inclus dans votre demande d'autorisation, ce paramètre s'ajoute prompt=select_account 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 qui redirigent vers IdPs. Lorsqu'il est inclus dans votre demande d'autorisation, ce paramètre s'ajoute prompt=consent au chemin URL de la destination de redirection IdP. Lorsque ce paramètre est pris en IdPs charge, ils demandent le consentement de l'utilisateur avant de rediriger vers votre groupe d'utilisateurs.

Lorsque vous omettez ce 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 espacés, par exemple. prompt=login consent

resource

Facultatif.

L'identifiant d'une ressource que vous souhaitez lier au jeton d'accès dans la aud réclamation. Lorsque vous incluez ce paramètre, Amazon Cognito confirme 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 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 la liaison de ressources, voir Liaison de ressources.

Exemple : attribution d'un code d'autorisation

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

La requête suivante lance une session pour récupérer un code d'autorisation que votre utilisateur transmet à votre application de redirect_uri destination. Cette session demande des étendues pour les attributs utilisateur et pour 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 : attribution d'un code d'autorisation avec PKCE

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

Cette requête 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 terminal.

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 requête 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 : attribution d'un code d'autorisation avec liaison de ressources

La requête 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 portant aud la mentionhttps://solar-system-data-api.example.com.

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

Exemple : octroi de jeton (implicite) sans étendue openid

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

La demande concerne une autorisation implicite de la part de votre serveur d'autorisation. Il demande des étendues dans le jeton d'accès 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 à l'aide d'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 : octroi de jeton (implicite) avec une portée openid

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 des étendues dans le jeton d'accès 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 scope était 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 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 mise en forme incorrecte.

    • 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 fait la demande code ou token y response_type entre, mais qu'il n'y a pas d'autorisation pour ces demandes, le serveur d'autorisation Amazon Cognito retourne unauthorized_client au serveur 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 revient server_error à celui du clientredirect_uri. L'erreur HTTP 500 n'étant 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 IdPs, Amazon 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

    • Si un délai de connexion survient lors de l'appel du jwks_uri terminal pour la validation du jeton d'identification, le serveur d'authentification redirige le client avec un message d'erreur 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 lors de la connexion à un IdP externe, le serveur d'authentification redirige le client avec un message d'erreur contenant l'redirect_uriun 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