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.
Intégration d'une API REST à un groupe d'utilisateurs Amazon Cognito
Après avoir créé un groupe d'utilisateurs Amazon Cognito, dans API Gateway, vous devez ensuite créer un mécanisme d'autorisation COGNITO_USER_POOLS
qui utilise le groupe d'utilisateurs. La procédure suivante montre comment procéder à l'aide de la console API Gateway.
Note
Vous pouvez utiliser l'action CreateAuthorizer
pour créer un mécanisme d'autorisation COGNITO_USER_POOLS
qui utilise plusieurs groupes d'utilisateurs. Vous pouvez utiliser jusqu'à 1 000 groupes d'utilisateurs pour un mécanisme d'autorisation COGNITO_USER_POOLS
. Cette limite ne peut pas être augmentée.
Important
Après avoir effectué l'une des procédures ci-dessous, vous devez déployer ou redéployer votre API pour propager les modifications. Pour plus d'informations sur le déploiement de votre API, consultez Déploiement REST APIs dans API Gateway.
Pour créer un mécanisme d'autorisation COGNITO_USER_POOLS
à l'aide de la console API Gateway
-
Créez une API ou sélectionnez une API existante dans API Gateway.
-
Dans le panneau de navigation principal, choisissez Mécanismes d'autorisation.
-
Choisissez Créer un mécanisme d'autorisation.
-
Pour configurer le nouveau mécanisme d'autorisation afin d'utiliser un groupe d'utilisateurs, procédez comme suit :
-
Pour Nom du mécanisme d’autorisation, entrez un nom.
-
Pour Type de mécanisme d'autorisation, sélectionnez Cognito.
-
Pour le groupe d'utilisateurs Cognito, choisissez l' Région AWS endroit où vous avez créé votre Amazon Cognito et sélectionnez un groupe d'utilisateurs disponible.
Vous pouvez utiliser une variable d'étape pour définir votre groupe d'utilisateurs. Utilisez le format suivant pour votre groupe d'utilisateurs :
arn:aws:cognito-idp:
.us-east-2
:111122223333
:userpool/${stageVariables.MyUserPool
} -
Pour Source du jeton, entrez
Authorization
comme nom d'en-tête pour transmettre le jeton d'identité ou le jeton d'accès renvoyé par Amazon Cognito lorsqu'un utilisateur se connecte avec succès. -
(Facultatif) Entrez une expression régulière dans le champ Validation du jeton pour valider le champ
aud
(public) du jeton d'identité avant que la demande soit autorisée avec Amazon Cognito.. Notez que lors de l'utilisation d'un jeton d'accès, cette validation rejette la demande en raison du jeton d'accès ne contenant pas le champaud
. -
Choisissez Créer un mécanisme d'autorisation.
-
-
Après avoir créé le mécanisme d'autorisation
COGNITO_USER_POOLS
, vous pouvez éventuellement tester son appel en fournissant un jeton d'identité alloué à partir du groupe d'utilisateurs. Vous pouvez obtenir ce jeton d'identité en appelant le kit SDK d'identité Amazon Cognito afin de connecter l'utilisateur. Vous pouvez également utiliser l'actionInitiateAuth
. Si vous ne configurez pas de Portées d'autorisation, API Gateway traite le jeton fourni comme un jeton d'identité.
La procédure précédente crée un mécanisme d'autorisation COGNITO_USER_POOLS
qui utilise le groupe d'utilisateurs Amazon Cognito que vous venez de créer. En fonction de la façon dont vous activez le mécanisme d'autorisation sur une méthode d'API, vous pouvez utiliser un jeton d'identité ou un jeton d'accès qui est alloué à partir du groupe d'utilisateurs intégré.
Pour configurer un mécanisme d'autorisation COGNITO_USER_POOLS
sur les méthodes
-
Sélectionnez Ressources. Choisissez une nouvelle méthode ou choisissez une méthode existante. Si nécessaire, créez une ressource.
-
Dans l'onglet Demande de méthode, sous Paramètres de demande de méthode, choisissez Modifier.
-
Pour Mécanisme d'autorisation, dans le menu déroulant, sélectionnez les mécanismes d'autorisation de groupe d'utilisateurs Amazon Cognito que vous venez de créer.
-
Pour utiliser un jeton d'identité, procédez comme suit :
-
Laissez l'option Portées d'autorisation vide.
-
Si nécessaire, dans Demande d'intégration, ajoutez les expressions
$context.authorizer.claims['
ouproperty-name
']$context.authorizer.claims.
dans un modèle de mappage de corps pour transmettre la propriété des champs standard d'identité spécifiée du groupe d'utilisateurs au backend. Pour les noms de propriété simples, tels queproperty-name
sub
oucustom-sub
, les deux notations sont identiques. Pour les noms de propriété complexes, tels quecustom:role
, vous ne pouvez pas utiliser la notation par points. Par exemple, les expressions de mappage suivantes transmettent les champs standardsub
etemail
de la requête au backend :{ "context" : { "sub" : "$context.authorizer.claims.sub", "email" : "$context.authorizer.claims.email" } }
Si vous avez déclaré un champ de requête personnalisé lors de la configuration d'un groupe d'utilisateurs, vous pouvez respecter le même modèle pour accéder aux champs personnalisés. L'exemple suivant permet d'obtenir un champ
role
personnalisé d'une requête :{ "context" : { "role" : "$context.authorizer.claims.role" } }
Si le champ de requête personnalisé est déclaré en tant que
custom:role
, utilisez l'exemple suivant pour obtenir la propriété de la requête :{ "context" : { "role" : "$context.authorizer.claims['custom:role']" } }
-
-
Pour utiliser un jeton d'accès, procédez comme suit :
-
Pour Portées d'autorisation, entrez un ou plusieurs noms complets d'une portée qui a été configurée lorsque le groupe d'utilisateurs Amazon Cognito a été créé. Par exemple, en suivant l'exemple fourni dans Création d'un groupe d'utilisateurs Amazon Cognito pour une API REST, l'une des portées est
https://my-petstore-api.example.com/cats.read
.Lors de l'exécution, l'appel de méthode réussit si une portée indiquée sur la méthode de cette étape correspond à une portée demandée dans le jeton entrant. Dans le cas contraire, l'appel échoue en renvoyant une réponse
401 Unauthorized
. -
Choisissez Enregistrer.
-
-
Répétez ces étapes pour les autres méthodes de votre choix.
Avec le mécanisme d'autorisation COGNITO_USER_POOLS
, si l'option OAuth Scopes n'est pas spécifiée, API Gateway traite le jeton fourni comme un jeton d'identité et vérifie l'identité demandée par rapport à celle du groupe d'utilisateurs. Sinon, API Gateway traite le jeton fourni comme un jeton d'accès et vérifie les portées d'accès qui sont demandées dans le jeton par rapport aux portées d'autorisation déclarées sur la méthode.
Au lieu d'utiliser la console API Gateway, vous pouvez également activer un groupe d'utilisateurs Amazon Cognito sur une méthode en spécifiant un fichier de définition OpenAPI et en important la définition d'API dans API Gateway.
Pour importer un mécanisme d'autorisation COGNITO_USER_POOLS avec un fichier de définition OpenAPI
-
Créez (ou exportez) un fichier de définition OpenAPI pour votre API.
-
Spécifiez la définition JSON du mécanisme d'autorisation
COGNITO_USER_POOLS
(MyUserPool
) dans la sectionsecuritySchemes
dans OpenAPI 3.0 ou dans la sectionsecurityDefinitions
dans OpenAPI 2.0 comme suit : -
Pour utiliser le jeton d'identité pour l'autorisation de méthode, ajoutez
{ "MyUserPool": [] }
à la définitionsecurity
de la méthode, comme indiqué dans la méthode GET suivante sur la ressource racine."paths": { "/": { "get": { "consumes": [ "application/json" ], "produces": [ "text/html" ], "responses": { "200": { "description": "200 response", "headers": { "Content-Type": { "type": "string" } } } }, "security": [ { "MyUserPool": [] } ], "x-amazon-apigateway-integration": { "type": "mock", "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "'text/html'" }, } }, "requestTemplates": { "application/json": "{\"statusCode\": 200}" }, "passthroughBehavior": "when_no_match" } }, ... }
-
Pour utiliser le jeton d'accès pour l'autorisation de méthode, modifiez la définition de sécurité ci-dessus pour
{ "MyUserPool": [resource-server/scope, ...] }
:"paths": { "/": { "get": { "consumes": [ "application/json" ], "produces": [ "text/html" ], "responses": { "200": { "description": "200 response", "headers": { "Content-Type": { "type": "string" } } } }, "security": [ { "MyUserPool": ["https://my-petstore-api.example.com/cats.read", "http://my.resource.com/file.read"] } ], "x-amazon-apigateway-integration": { "type": "mock", "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "'text/html'" }, } }, "requestTemplates": { "application/json": "{\"statusCode\": 200}" }, "passthroughBehavior": "when_no_match" } }, ... }
-
Si nécessaire, vous pouvez définir d'autres paramètres de configuration d'API à l'aide des définitions ou des extensions OpenAPI appropriées. Pour plus d’informations, consultez APIExtensions ouvertes pour API Gateway.