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 :
1. Pour Nom du mécanisme d’autorisation, entrez un nom.
2. Pour Type de mécanisme d'autorisation, sélectionnez Cognito.
3. 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}.
4. 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.
5. (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.
6. 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'action InitiateAuth. 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 :
1. Laissez l'option Portées d'autorisation vide.
2. 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 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']"
    }
}
```
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, 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.
2. 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 section securitySchemes dans OpenAPI 3.0 ou dans la section securityDefinitions dans OpenAPI 2.0 comme suit :

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"
        }
      },
      ...
   }

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.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Création d'un groupe d'utilisateurs Amazon Cognito pour une API REST

Appeler une API REST intégrée à un groupe d'utilisateurs