How do I set up an Amazon Cognito user pool as an authorizer on an API Gateway REST API?

Last updated: 2021-03-30

There are two ways to set up an Amazon Cognito user pool as an authorizer on an API Gateway REST API:

• Create a COGNITO_USER_POOLS authorizer.
• Create an AWS Lambda authorizer.

For authorization, you can use either ID tokens or access tokens. For more information, see Using tokens with user pools.

Note: To validate the claims (and additional claims) in the access tokens and ID tokens issued by Amazon Cognito, use a Lambda authorizer. If you're using access tokens to authorize API method calls, make sure that you authorize access to your APIs using custom scopes in Amazon Cognito.

For more information, see Defining resource servers for your user pool and Create an Amazon Cognito user pool for a REST API.

The following procedure shows how to create a COGNITO_USER_POOLS authorizer. The example assumes you already created two things:

• An Amazon Cognito user pool with an app client.
• An API Gateway REST API resource.

For more information, see Integrate a REST API with an Amazon Cognito user pool.

After you create the COGNITO_USER_POOLS authorizer, do the following:

1.    In the API Gateway console, choose the Test button under the new authorizer.

2.    In the Test window, for Authorization, enter an ID token from the new Amazon Cognito user pool.

3.    Choose Test.

Note: If the ID token is correct, the test returns a 200 response code. Incorrect ID tokens return a 401 response code.

For more information, see the To configure a COGNITO_USER_POOLS authorizer on methods section of Integrate a REST API with an Amazon Cognito user pool.

There are four ways to get authorization tokens:

• The hosted web UI for Amazon Cognito.
• The AWS Command Line Interface (AWS CLI).
• One of the AWS SDKs.
• The Postman app.

Note: If you use the hosted web UI for Amazon Cognito and an authorization code grant type, you might need to exchange the obtained code with the token endpoint.

If you're using an implicit grant type, you can obtain the grant from the callback URL. The callback URL is appended with the access token and ID token parameter for implicit flow. Make sure that you use the correct token, based on the type of token that you chose to use.

To get authorization tokens using the hosted web UI for Amazon Cognito

To use the Authorization Code Grant flow, do the following:

Note: The response type parameter must be “code” when using the Authorization Code Grant flow.

1.    Send an HTTP GET request to the following URL:

Important: Replace <your_domain> with the domain name of your user pool. Replace <your_app_client_id> with the app client ID of your user pool. Replace <your_callback_url> with your callback URL.

https://<your_domain>/authorize?response_type=code&client_id=<your_app_client_id>&redirect_uri<your_callback_url>

Note: If you include the identity_provider parameter, the endpoint redirects to the federation identity provider. If the app client is configured for Amazon Cognito user pools only, then the following endpoint redirects to the /login endpoint:

https://<your_domain>/login?response_type=code&client_id=<your_app_client_id>&redirect_uri=<your_callback_url>

2.    Log in to your user pool or your federated identity provider. The UI redirects to the URL specified in the callback for the app client.

Important: The redirection URL includes the Authorization Code, which needs to be exchanged with the token endpoint to get valid tokens.

3.    Send an HTTP POST request to the /oauth2/token endpoint. For more information see Token endpoint.

Example HTTP POST request

Note: The following example HTTP Post request uses the following /oauth2/token endpoint: https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token&

Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic aSdxd892iujendek328uedj
grant_type=authorization_code&
client_id=djc98u3jiedmi283eu928&
code=AUTHORIZATION_CODE&
redirect_uri=com.myclientapp://myclient/redirect

Example HTTP Post request response

HTTP/1.1 200 OKContent-Type: application/json
{ 
"access_token":"eyJz9sdfsdfsdfsd", 
"refresh_token":"dn43ud8uj32nk2je", 
"id_token":"dmcxd329ujdmkemkd349r",
"token_type":"Bearer", 
"expires_in":3600
}

To use the Implicit Grant flow, do the following:

Note: The response type parameter must be "token" when using the Implicit Grant flow.

1.    Send an HTTP GET request to the following URL: 

Important: Replace <your_domain>  with the domain name of your user pool. Replace <your_app_client_id>  with the app client ID of your user pool. Replace <your_callback_url>  with your callback URL.

https://<your_domain>/authorize?response_type=token&client_id=<your_app_client_id> &redirect_uri=<your_callback_url>

Note: If you include the identity_provider parameter, the endpoint redirects to the federation identity provider. If the app client is configured for Amazon Cognito user pools only, the following endpoint redirects to the /login endpoint:

https://<your_domain>/login?response_type=token&client_id=<your_app_client_id> &redirect_uri=<your_callback_url>

2.    Log in to your user pool with the user name and password for an existing user or create a new user for logging in. The UI redirects to the URL specified in the callback for the app client.

Note: The redirection URL includes the ID token and access token.

Example redirection URL

https://www.example.com/#id_token=123456789idtoken123456789&access_token=123456789accesstoken123456789expires_in=3600&token_type=Bearer

To get authorization tokens using the AWS CLI

Note: If you receive errors when running AWS CLI commands, make sure that you’re using the most recent AWS CLI version.

Run the following initiate-auth AWS CLI command:

Important: Replace the following values with inputs you're using: auth-flow, --client-id, and --auth-parameters

aws cognito-idp initiate-auth --auth-flow USER_PASSWORD_AUTH --auth-parameters USERNAME=testuser,PASSWORD=P@ssw0rd --client-id <app client id>

Example initiate-auth AWS CLI command response

Response: {
"AuthenticationResult": {
"ExpiresIn": 3600,
"IdToken": "dmcxd329ujdmkemkd349r",
"RefreshToken": "dn43ud8uj32nk2je"",
"TokenType": "Bearer",
"AccessToken": "eyJz9sdfsdfsdfsd"
},
"ChallengeParameters":
            {} 
}

To get authorization tokens using one of the AWS SDKs

For more information see, Integrating Amazon Cognito with web and mobile apps.

To get authorization tokens using Postman

Use the Oauth 2.0 authorization mode in Postman to get authorization tokens. For more information, see How do I troubleshoot 401 Unauthorized errors from an API Gateway REST API endpoint after I've set up an Amazon Cognito user pool?