How do I troubleshoot "401 Unauthorized" errors from an API Gateway REST API endpoint after I've set up an Amazon Cognito user pool?

Resolution

Note: API Gateway can return 401 Unauthorized errors for a variety of reasons. The following procedure shows how to troubleshoot only 401 errors related to COGNITO_USER_POOLS authorizers.

Check the authorizer's configuration on the API method

Complete the following steps:

1. Open the API Gateway console.
2. In the navigation pane, choose APIs, and then choose your API.
3. In the navigation pane, under your API, choose Authorizers.
4. Review the authorizer's configuration and confirm that the following is true:
   The user pool ID matches the issuer of the token.
   You deployed the API.
   The authorizer works in test mode for id tokens.
   Note: You can't use this feature to test access tokens.

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

Note: If you can't invoke your API after you confirm the authorizer's configuration, then check the validity of the security token.

Check the validity of the security token

To check the validity of the security token, confirm that the following is true:

• The security token isn't expired.
• The issuer in the security token matches the Amazon Cognito user pool configured on the API.
• The ID token and access token string values are valid.
  Note: If the string values are valid, then you can decode the tokens. If the tokens aren't valid, then review your tokens. Make sure that the tokens don't have any additional spaces from passing through the request header.

Important: If you didn't configure any scopes on the API Gateway method, then make sure that you use a valid ID token. If you configure additional scopes on the API Gateway method, then make sure that you use a valid access token. For more information, see How do I authorize access to API Gateway APIs using custom scopes in Amazon Cognito?

Example security token payload:

Id token payload: {
 "sub": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
 "aud": "xxxxxxxxxxxxexample",
 "email_verified": true,
 "token_use": "id",
 "auth_time": 1500009400,
 "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example",
 "cognito:username": "janedoe",
 "exp": 1500013000,
 "given_name": "Jane",
 "iat": 1500009400,
 "email": "janedoe@example.com"
 }
Access token payload:
{
    "auth_time": 1500009400,
    "exp": 1500013000,
    "iat": 1500009400,
    "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example",
    "scope": "aws.cognito.signin.user.admin",
    "sub": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "token_use": "access",
    "username": "janedoe@example.com"
}

Note the following claim names in the example security token payload:

• token_use indicates the type of token (ID or access token).
• exp indicates the token's expiration time.
  Note: The exp claim is represented as seconds since the Unix epoch (1970-01-01T0:0:0Z) until the date and time the token expires in Coordinated Universal Time (UTC).
• auth_time indicates when the token was issued.
• iss indicates the domain of the user pool that issued the tokens.

Important: The token that you use must match the user pool that you configure on the API Gateway method. If you can't invoke the API, then confirm that you correctly use the authorization header. If you receive 401 errors, then make sure that your resource policies don't block the request.

If you use Postman to invoke the API

To directly use Amazon Cognito tokens, use OAuth 2.0 authorization mode. For more information, see API authentication and authorization in Postman on the Postman website.

When you set up OAuth 2.0 authorization mode, confirm that the following is true:

• The Grant type option is set to Authorization code or Authorization implicit.
• The Callback URL matches the Redirected URL configured on the user pool's app client.
• The Auth URL is in the following format: https://mydomain.auth.us-east-1.amazoncognito.com/login
  Note: Replace mydomain with the domain name that you use to configure your user pool. Make sure that you enter the correct AWS Region that you host your API in.
• The Client ID is the user pool's app client ID.
  Note: If you associate a client secret with the user pool's app client, then specify the secret in the Authorization tab. If no client secret is associated with the user pool's app client, then leave the Client secret field blank.
• The Scope is configured as Openid.
  Note: You must allow the Openid scope on the user pool's app client.
• For Authorization code flow, enter the correct Amazon Cognito user pool token endpoint.
  Example Amazon Cognito user pool token endpoint:
  https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token

Note: If the token endpoint doesn't support the content type, then Postman can't pass the required content and results in a 405 error. To avoid this issue, use the implicit flow. For more information, see OAuth 2.0 grants.

Related information

Secure API access with Amazon Cognito federated identities, Amazon Cognito user pools, and API Gateway

How do I decode and verify the signature of an Amazon Cognito JSON Web Token?

Control access to REST APIs using Amazon Cognito user pools as an authorizer