Intégration d’une API REST avec un groupe d’utilisateurs Amazon Cognito

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 Groupe d’utilisateurs Cognito, choisissez la Région AWS 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é.

Choisissez 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 Save (Enregistrer).

Répétez ces étapes pour les autres méthodes de votre choix.

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 :

  "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}"
        ]
      }
    }

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 Extensions OpenAPI pour API Gateway.