Connecting Postman to Amazon Cognito User Pools for API Access Tokens

Photo by Khwanchai Phanthong on Pexels.com

Majority of the time in my recent projects, I use Amazon Cognito for user authentication (sign in, sign up, login with identity providers etc) in front of an Amazon API Gateway. Usually the API endpoints control access using Amazon Cognito user pools as authorizer

In these type of APIs, testing the API using Postman is a good practice. Use of Postman helps distributing the API contracts easily while helping you as a developer to run different types of tests without a full-blown client implementation.

The expected way to connect and consume these APIs are providing an id token from Amazon Cognito authorization in the headers. This token is auto-validated by Amazon API Gateway by leveraging Cognito Authorizers. A typical request to these endpoints would look like below:

curl --location --request GET 'https://{API-ID}.execute-api.eu-west-2.amazonaws.com/v1/profiles/123' \
--header 'Authorization: eyJraWQiOiJOZjB0clFHanRG.....'

To add this token in every request, Postman supports Collection based Authorization setting. (I assume you follow putting all requests under a collection in Postman). As you can see, Postman supports variety of authorization techniques.

What we are going to use from these alternatives is OAuth 2.0 which Amazon Cognito supports out of box. There is a detailed deep dive on different grant types available on AWS Blog.

As part of your Amazon Cognito setup, you are expected to create an App Client which has access to this user pool. Using this App Client, we will be able to sign in using an existing user and grab an id token that will be used for API calls.

[Step 1] – App Client Id and Callback URL(s)

In order to setup this, go to App Client Settings section of the Cognito pool.

You will use the App Client Id and Callback URL(s) from this page in your OAuth 2.0 setup in Postman.

[Step 2] OAuth 2.0 Flows

Also make sure the following OAuth 2.0 flows are enabled on the same App Client Settings page.

The way to sign in with an existing user account is via Hosted UI feature of Amazon Cognito. This UI is a very basic sign in/sign up screen that conforms the User Pool settings. It is actually a nice way of testing your Cognito setup out of box

(nice as in available and working, not as in with a slick UI 🙂)

[Step 3] Hosted UI Domain

As you may realise from above screenshot, Hosted UI needs to be setup. In order to do that, go to App Integration section and click Add Domain

In Add Domain screen, you can set a domain name for your Hosted UI. This URL will be used for OAuth 2.0 settings in Postman. Also, this URL will be used for the sign-up and sign-in pages that are hosted by Amazon Cognito. The prefix must be unique across the selected AWS Region. Domain names can only contain lower-case letters, numbers, and hyphens. Learn more about domain prefixes.

[Step 4] Collection Authorization Settings

Next part is setting up Postman Collection in order to sign in / sign up and get an id token for making authenticated API calls. Fill in the following details by editing the Collection Authorization settings:

• Grant Type: Implicit
  • Uncheck Authorise using browser option
• Callback URL: https://example.com
• Auth URL: {Hosted UI URL}/login
• Client ID: {App Client Id}
• Scope: phone email openid profile aws.cognito.signin.user.admin
• Client Authentication: Send client credentials in the body

[Step 5] Generate Access Token

When you enter these details and click Get New Access Token button, Postman will open the Hosted UI URL for you to sign in or sign up.

What is nice about this setup is, you can just create a test user and use it for all API calls accordingly using the above UI. Above UI is enabled by setting Cognito Pool setting called User sign ups allowed? Users can sign themselves up

As you can see, this UI complies with the user pool settings and gives you a nice way to test your setup. Here is the screenshot of signup screen and look at the password policy in place….

Hosted UI even provides the email and/or phone validation during setup. In my user pool setup, I require users to have validated emails. So, in this below screenshot I can see that Hosted UI shows related information and input. As Cognito sends real emails for verification code, I suggest to use a real email here to avoid any confusion…

When you finish a successful sign in or sign up, Postman confirms this and grabs the token.

Following screen is shown with the token details. You will see that this screen has an Access Token and an id_token.

For API Gateway Cognito Authorizer workflow, you will need to use id_token.

!!! IMPORTANT DETAIL !!!

Simply copy the value of id_token and put it in Access Token value of the Current Token setting. This will make the id_token available for all requests in that collection.

[Step 6] Setup Collection Authorization Settings

Last step is updating API requests to use the Collection Authorization settings. Setting the Authorization setting of requests as Inherit auth from parent will let Postman inject Access Token in the Authorization header value.

Conclusion

I hope you will be able to easily test your APIs behind Cognito using this setup via Postman. You can export the Collection as .json and even make part of your codebase so you will be embracing API Contract Testing as Code – ACTaC (I made this up now…)