How do I authorize access to API Gateway APIs using custom scopes in Amazon Cognito?

Last updated: 2019-09-17

I want to authorize access to my Amazon API Gateway API resources using custom scopes in an Amazon Cognito user pool. How do I do that?

Short Description

Define a resource server with custom scopes in your Amazon Cognito user pool. Then, create and configure an Amazon Cognito authorizer for your API Gateway API to authenticate requests to your API resources.

If you have different app clients with varying levels of access to your API resources, you can provide differentiated access based on the custom scopes for the app clients. When creating the custom scopes, consider what levels of granular access the different app clients might need, and then design accordingly.


If you haven't done so already, create these prerequisites:

Add a resource server with custom scopes in your user pool

  1. Open the Amazon Cognito console.
  2. Define the resource server and custom scopes.
  3. After saving your changes, on the Resource servers tab, choose Configure app client settings.
  4. On the App client settings tab, under OAuth 2.0, do the following:
    Under Allowed OAuth Flows, select the Implicit grant check box.
    Under Allowed Custom Scopes, select the check box for the custom scope that you defined.
    Note: Observe that the format for a custom scope is resourceServerIdentifier/scopeName. When a client requests a custom scope in an OAuth 2.0 flow, the request must include the full identifier for the scope in this format.
  5. Choose Save changes.

Create an authorizer and integrate it with your API

For these steps, refer to the instructions in Integrate a REST API with an Amazon Cognito User Pool.

  1. To create the authorizer, follow the instructions under To create a COGNITO_USER_POOLS authorizer by using the API Gateway console.
    Note: After creation, there's an option in the console to Test your authorizer. This requires an identity token. To test your setup outside of the console using an access token, see Get a user pool access token for testing later in this article.
  2. To integrate the authorizer with your API, follow the instructions under To configure a COGNITO_USER_POOLS authorizer on methods.
    Note: For OAuth Scopes, enter the full identifier for a custom scope in the format resourceServerIdentifier/scopeName.
  3. Deploy your API.

Get a user pool access token for testing

Use the hosted web UI for your user pool to sign in and retrieve an access token from the Amazon Cognito authorization server.

Note: You can also retrieve an access token using the OAuth 2.0 endpoint implementations available in the mobile and web AWS SDKs.

  1. Enter this URL in your web browser:
    Replace yourDomainPrefix and region with the values for your user pool. Find them in the Amazon Cognito console on the Domain name tab for your user pool.
    Replace yourClientId with your app client's ID, and replace redirectUrl with your app client's callback URL. Find them in the console on the App client settings tab for your user pool. For more information, see LOGIN Endpoint.
  2. Sign in to your user pool as the user that you created.
  3. Copy the access token from the URL in the address bar. The token is a long string of characters following access_token=.

Make a request to your API as a test

Include the access token as the value of the authorization header in a request to your API Gateway API. Make the request using the Postman app or curl from a command line interface. For more information about curl, see the cURL project website.

To use curl, run this command:

curl -H "Authorization: accessToken"

Note: Replace restApiId with the API ID. Replace region with the AWS Region of your API. Replace stageName with the name of the stage where your API is deployed. Replace resourceName with the name of the API resource. Replace accessToken with the token you copied. For more information, see Invoking a REST API in Amazon API Gateway.

If everything is configured correctly, you get a 200 OK response code.