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

5 minute read

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

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 that need varying levels of access to your API resources, then you can define differentiated scopes of access. Consider what levels of granular access that the different app clients might need, and then design accordingly.


Create the following 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 you create the resource server, choose the App Integration tab.

4.    From the App clients and analytics section, select your app client.

5.    From the Hosted UI section, choose Edit. Then, complete the following steps:
For the OAuth 2.0 grant types dropdown list, choose Implicit grant.
For the Custom scopes dropdown list, choose the custom scope that you defined.
Note: 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.

6.    Choose Save changes.

If your mobile applications have a server side component, then use the Authorization code grant flow and Proof Key for Code Exchange (PKCE). With the Authorization code grant flow, the tokens are more secure and never exposed directly to an end user.

If your setup doesn't contain any server-side logic, then you can use the implicit grant flow. The implicit grant doesn't generate refresh tokens. This prevents refresh tokens from exposure to the client. Refresh tokens have a longer validity and retrieve newer ID and access tokens.

Important: Don't store the refresh tokens in a client-side environment.

For more information, see App client settings terminology. For more information on Amazon Cognito user pool OAuth 2.0 grants, see Understanding Amazon Cognito user pool OAuth 2.0 grants.

Create an authorizer and integrate it with your API

To complete the following steps, follow the instructions to 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, an option appears in the console to Test your authorizer. This requires an identity token. To use an access token to test your setup outside the console, see the Get a user pool access token for testing section 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. Or, use the OAuth 2.0 endpoint implementations that are available in the mobile and web AWS SDKs to retrieve an access token.

Note: When an app client requests authentication through the hosted web UI, the request can include any combination of system-reserved scopes, or custom scopes. If the client doesn't request any scopes, then the authentication server returns an access token that contains all scopes that are associated with the client. When you design your app client, be sure that the client includes the intended scopes in the request to avoid granting unnecessary permissions.

1.    Enter the following URL in your web browser:
Note: 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=.

Call your API as a test

As a test, use the access token as the value of the authorization header to call your API using the access token. You can use the Postman app (on the Postman website) or curl command from a command line interface. For more information about curl, see the curl project website.

To use curl, run the following 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 that you copied. For more information, see Invoking a REST API in Amazon API Gateway.

When you correctly configure everything, you get a 200 OK response code.

Related information

Configuring a user pool app client

Access token scope (The OAuth 2.0 Authorization Framework)

AWS OFFICIALUpdated a year ago