Integrate a REST API with an Amazon Cognito user pool

Create a new API, or select an existing API in API Gateway.

In the main navigation pane, choose Authorizers.

Choose Create authorizer.

To configure the new authorizer to use a user pool, do the following:

1. For Authorizer name, enter a name.

2. For Authorizer type, select Cognito.

3. For Cognito user pool, choose the Amazon Web Services Region where you created your Amazon Cognito and select an available user pool.

4. For Token source, enter Authorization as the header name to pass the identity or access token that's returned by Amazon Cognito when a user signs in successfully.

5. (Optional) Enter a regular expression in the Token validation field to validate the aud (audience) field of the identity token before the request is authorized with Amazon Cognito. Note that when using an access token this validation rejects the request due to the access token not containing the aud field.

6. Choose Create authorizer.

After creating the COGNITO_USER_POOLS authorizer, you can optionally test invoke it by supplying an identity token that's provisioned from the user pool. You can obtain this identity token by calling the Amazon Cognito Identity SDK to perform user sign-in. You can also use the InitiateAuth action. If you do not configure any Authorization scopes, API Gateway treats the supplied token as an identity token.

Choose Resources. Choose a new method or choose an existing method. If necessary, create a resource.

On the Method request tab, under Method request settings, choose Edit.

For Authorizer, from the dropdown menu, select the Amazon Cognito user pool authorizers you just created.

To use an identity token, do the following:

1. Keep Authorization Scopes empty.

2. If needed, in the Integration request, add the $context.authorizer.claims['property-name'] or $context.authorizer.claims.property-name expressions in a body-mapping template to pass the specified identity claims property from the user pool to the backend. For simple property names, such as sub or custom-sub, the two notations are identical. For complex property names, such as custom:role, you can't use the dot notation. For example, the following mapping expressions pass the claim's standard fields of sub and email to the backend:

   {
   	"context" : {
   		"sub" : "$context.authorizer.claims.sub",
   		"email" : "$context.authorizer.claims.email"
   	}
   }

   If you declared a custom claim field when you configured a user pool, you can follow the same pattern to access the custom fields. The following example gets a custom role field of a claim:

   {
   	"context" : {
   		"role" : "$context.authorizer.claims.role"
       }
   }

   If the custom claim field is declared as custom:role, use the following example to get the claim's property:

   {
   	"context" : {
   		"role" : "$context.authorizer.claims['custom:role']"
       }
   }

To use an access token, do the following:

1. For Authorization Scopes, enter one or more full names of a scope that has been configured when the Amazon Cognito user pool was created. For example, following the example given in Create an Amazon Cognito user pool for a REST API, one of the scopes is https://my-petstore-api.example.com/cats.read.

   At runtime, the method call succeeds if any scope that's specified on the method in this step matches a scope that's claimed in the incoming token. Otherwise, the call fails with a 401 Unauthorized response.

2. Choose Save.

Repeat these steps for other methods that you choose.

Create (or export) an OpenAPI definition file for your API.

Specify the COGNITO_USER_POOLS authorizer (MyUserPool) JSON definition as part of the securitySchemes section in OpenAPI 3.0 or the securityDefinitions section in Open API 2.0 as follows:

To use the identity token for method authorization, add { "MyUserPool": [] } to the security definition of the method, as shown in the following GET method on the root resource.

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

To use the access token for method authorization, change the above security definition to { "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"
        }
      },
      ...
   }

If needed, you can set other API configuration settings by using the appropriate OpenAPI definitions or extensions. For more information, see Working with API Gateway extensions to OpenAPI.