Integrate a REST API with an Amazon Cognito user pool
After creating an Amazon Cognito user pool, in API Gateway, you must then create a
COGNITO_USER_POOLS
authorizer that uses the user pool. The following
procedure walks you through the steps to do this using the API Gateway console.
After performing any of the procedures below, you'll need to deploy or redeploy your API to propagate the changes. For more information about deploying your API, see Deploying a REST API in Amazon API Gateway.
To create a COGNITO_USER_POOLS
authorizer by using the API Gateway
console
-
Create a new API, or select an existing API in API Gateway.
-
From the main navigation pane, choose Authorizers under the specified API.
-
Under Authorizers, choose Create New Authorizer.
-
To configure the new authorizer to use a user pool, do the following:
-
Type an authorizer name in Name.
-
Select the Cognito option.
-
Choose a region under Cognito User Pool.
-
Select an available user pool. You must have created a user pool for the selected region in Amazon Cognito for it to show up in the drop-down list.
-
For Token source, type
Authorization
as the header name to pass the identity or access token that's returned by Amazon Cognito when a user signs in successfully. -
Optionally, 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 theaud
field. -
To finish integrating the user pool with the API, choose Create.
-
-
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. Make sure to use the returned identity token, not the access token.
The preceding procedure creates a COGNITO_USER_POOLS
authorizer that uses
the newly created Amazon Cognito user pool. Depending on how you enable the authorizer
on an API
method, you can use either an identity token or an access token that's provisioned
from
the integrated user pool. The next procedure walks you through the steps to configure
the authorizer on an API method.
To configure a COGNITO_USER_POOLS
authorizer on methods
-
Choose (or create) a method on your API.
-
Choose Method Request.
-
Under Settings, choose the pencil icon next to Authorization.
-
Choose one of the available Amazon Cognito user pool authorizers from the drop-down list.
-
To save the settings, choose the check mark icon.
-
To use an identity token, do the following:
-
Leave the OAuth Scopes option unspecified (as
NONE
). -
If needed, choose Integration Request to add the
$context.authorizer.claims['
orproperty-name
']$context.authorizer.claims.
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 asproperty-name
sub
orcustom-sub
, the two notations are identical. For complex property names, such ascustom:role
, you can't use the dot notation. For example, the following mapping expressions pass the claim's standard fieldsof sub
andemail
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:
-
Choose the pencil icon next to OAuth Scopes.
-
Type 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
com.hamuta.movies/drama.view
. Use a single space to separate multiple scopes.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. -
To save the setting, choose the check mark icon.
-
-
Repeat these steps for other methods that you choose.
With the COGNITO_USER_POOLS
authorizer, if the OAuth
Scopes option isn't specified, API Gateway treats the supplied token as an
identity token and verifies the claimed identity against the one from the user pool.
Otherwise, API Gateway treats the supplied token as an access token and verifies the
access
scopes that are claimed in the token against the authorization scopes declared on
the
method.
Instead of using the API Gateway console, you can also enable an Amazon Cognito user pool on a method by specifying an OpenAPI definition file and importing the API definition into API Gateway.
To import a COGNITO_USER_POOLS authorizer with an OpenAPI definition file
-
Create (or export) an OpenAPI definition file for your API.
-
Specify the
COGNITO_USER_POOLS
authorizer (MyUserPool
) JSON definition as part of thesecuritySchemes
section in OpenAPI 3.0 or thesecurityDefinitions
section in Open API 2.0 as follows: -
To use the identity token for method authorization, add
{ "MyUserPool": [] }
to thesecurity
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": ["com.hamuta.movies/drama.view", "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.