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 avec 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 [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html) 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 d’une API REST dans API Gateway](how-to-deploy-api.md). **Pour créer un mécanisme d’autorisation `COGNITO_USER_POOLS` à l’aide de la console API Gateway** 1. Créez une API ou sélectionnez une API existante dans API Gateway. 1. Dans le panneau de navigation principal, choisissez **Mécanismes d'autorisation**. 1. Choisissez **Créer un mécanisme d'autorisation**. 1. Pour configurer le nouveau mécanisme d'autorisation afin d'utiliser un groupe d'utilisateurs, procédez comme suit : 1. Pour **Nom du mécanisme d’autorisation**, entrez un nom. 1. Pour **Type de mécanisme d'autorisation**, sélectionnez **Cognito**. 1. 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}`. 1. 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. 1. (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 champ `aud`. 1. Choisissez **Créer un mécanisme d'autorisation**. 1. Après avoir créé le mécanisme d’autorisation `COGNITO_USER_POOLS`, vous pouvez essayer de l’invoquer en fournissant un jeton d’identité alloué à partir du groupe d’utilisateurs. Vous ne pouvez pas utiliser de jeton d’accès pour essayer d’invoquer votre mécanisme d’autorisation. Vous pouvez obtenir ce jeton d’identité en appelant le [kit SDK d’identité Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html) afin de connecter l’utilisateur. Vous pouvez également utiliser l’action [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html). 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** 1. Sélectionnez **Ressources**. Choisissez une nouvelle méthode ou choisissez une méthode existante. Si nécessaire, créez une ressource. 1. Dans l'onglet **Demande de méthode**, sous **Paramètres de demande de méthode**, choisissez **Modifier**. 1. 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. 1. Pour utiliser un jeton d’identité, procédez comme suit : 1. Laissez l’option **Portées d’autorisation** vide. 1. Si nécessaire, dans **Demande d’intégration**, ajoutez les expressions `$context.authorizer.claims['property-name']` ou `$context.authorizer.claims.property-name` 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 que `sub` ou `custom-sub`, les deux notations sont identiques. Pour les noms de propriété complexes, tels que `custom:role`, vous ne pouvez pas utiliser la notation par points. Par exemple, les expressions de mappage suivantes transmettent les [champs standard](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) `sub` et `email` 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']" } } ``` 1. Pour utiliser un jeton d’accès, procédez comme suit : 1. 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](apigateway-create-cognito-user-pool.md), 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`. 1. Choisissez **Enregistrer**. 1. Répétez ces étapes pour les autres méthodes de votre choix. Avec l'`COGNITO_USER_POOLS`autorisateur, si l'option **OAuthScopes** n'est pas spécifiée, API Gateway traite le jeton fourni comme un jeton d'identité et vérifie l'identité revendiqué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\$1USER\$1POOLS avec un fichier de définition OpenAPI** 1. Créez (ou exportez) un fichier de définition OpenAPI pour votre API. 1. Spécifiez la définition JSON du mécanisme d’autorisation `COGNITO_USER_POOLS` (`MyUserPool`) dans la section `securitySchemes` dans OpenAPI 3.0 ou dans la section `securityDefinitions` dans OpenAPI 2.0 comme suit : ------ #### [ OpenAPI 3.0 ] ``` "securitySchemes": { "MyUserPool": { "type": "apiKey", "name": "Authorization", "in": "header", "x-amazon-apigateway-authtype": "cognito_user_pools", "x-amazon-apigateway-authorizer": { "type": "cognito_user_pools", "providerARNs": [ "arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}" ] } } ``` ------ #### [ OpenAPI 2.0 ] ``` "securityDefinitions": { "MyUserPool": { "type": "apiKey", "name": "Authorization", "in": "header", "x-amazon-apigateway-authtype": "cognito_user_pools", "x-amazon-apigateway-authorizer": { "type": "cognito_user_pools", "providerARNs": [ "arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}" ] } } ``` ------ 1. Pour utiliser le jeton d’identité pour l’autorisation de méthode, ajoutez `{ "MyUserPool": [] }` à la définition `security` 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" } }, ... } ``` 1. 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" } }, ... } ``` 1. 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 de plus amples informations, veuillez consulter [Extensions OpenAPI pour API Gateway](api-gateway-swagger-extensions.md).