A step by step procedure to create an Amazon Cognito user pool. All available options are explained.

One of the best features of AWS application load Balancers (ALB) is authentication! You can offload authentication to ALB that leverages Amazon Cognito in the backend. Amazon Cognito offers identity management through user pools or federated identities. This article will walk you through creating a user pool in Amazon Cognito that is used for ALB authentication. Without further delay, let’s get into it.

• Login to Amazon Cognito console
• Click on Manage User Pools
• On the User pools page, click on Create a user pool button on top right hand corner of the page.
• That should start user pool creation wizard. Lets go through it one by one –

Name

Enter the Pool name and click on the Step through settings button.

Attributes

Settings on this page can not be edited later so choose wisely!

The first thing you need to choose is the end user’s sign-in method. They should use a username or email address/phone number to signup/sign in. I am choosing a username and also, allowing them to use email addresses while logging in later once they sign up. I am also selecting case sensitive usernames because that makes more sense.

The next section of attributes, let you choose through the list of attributes you want the end user to provide when they sign up in Cognito. You can also choose to add a custom attribute here if one is not listed in the standard list.

Policies

End-user password policies and controls are defined in this section. All the fields are pretty self-explanatory.

MFA and verifications

An extra layer of account security can be defined here. MFA and related configurations. Please note that if you are enabling MFA for end-users then you should be enabling phone number attributes in earlier settings and text messages (verification and subsequent messaging) will incur extra charges. Amazon pretty much explained each option here.

If you are opting for adding and managing phone number attributes then you need to create a role that provides access to Cognito for sending text messages on your behalf.

Messages customizations

In this section, you should be customizing the email or SMS messages being sent out by Amazon Cognito on your behalf. It’s a place if you want to have company branding in the communications! Make sure you have a verified email address in Amazon SES to set it as From email address.

In the later part of the page, you can configure how you want verification to be done using codes or clickable links. Also, you can customize the text of the message here.

Tags

A place that is crucial but mostly ignored by everyone! Tagging for the user pool.

Devices

Choose if Cognito should remember the user’s device. This will enhance the user experience. But, to use this feature you should have MFA enabled for end-users. Since we did not opt for it, we will simply say No and move forward.

App clients

In this section, you should create an app client which will access this user pool. On the creation of the app client, you will receive the app ID and secret key that you can configure in your applications to access this user pool.

Click on Add an app client

• App client name: Add unique name
• Refresh token expiration: Refresh tokens are used to retrieve new ID and access token. Control their expiration here. Read more about refresh tokens
• Access token expiration: Used for autorizing the API operation. Control expiration here. Read more about access tokens
• ID token expiration: It used to claim the authenticated user’s identity. Define its expiration limits here. Read more about ID tokens.
• Auth Flows Configuration: Enable depends on your integration requirements. I selected ALLOW_USER_PASSWORD_AUTH and left others untouched.

• Security Configuration: It allows to send back generic error. Select recommened unless you have any other reason not to!
• Advanced token settings: Enable or disable token revocations.
• Attributes read and write permissions: Select list of attributes which this app client can read or write.

Click on Create app client. It will be created along with the user pool when you completes the whole wizard.

Click on the Next step to move forward in the user pool creation wizard.

Triggers

On this page, you can configure lambda functions to be triggered on specific actions or workflow. You need to create Lambda functions in advance to select here from the dropdown. List of triggers available here –

1. Pre sign up
2. Pre authentication
3. Custom message
4. Post authentication
5. Post confirmation
6. Define Auth Challenge
7. Create auth challlenge
8. Verify authc challenge response
9. User migration
10. Pre token generation

All triggers are listed with descriptions for easy understanding of when they will be activated and execute related Lambda functions. For the simplicity of this article, we are not adding any.

Review

Review all the details you supplied throughout the wizard. You can make edits if necessary and then lastly click on Create pool

You should be greeted with a success message and the user pool management page. You can note the user pool ID generated for this user pool.

Amazon app clients settings

Now, that you created a user pool and app client for it. Let’s look at some of the settings those needs to be checked or changed to make sure your app client is ready to be consumed.

Configure Amazon Cognito app client’s IDP settings

Navigate to App integration > App client settings on the left sidebar menu on the user pool page.

• Enable Cognito user pool under Enabled identity providers.
• You should be having Callback URLs handy to fill in here. Those are URLs where app will be navigated once successful authentication happens. Your application developers should be able to help you with these details.
• Sign out URLs are those where user will be redirected once its signed out from IDP session
• OAuth 2.0 settings should be discussed with developer and configured as the app requirement

What is Amazon Cognito domain and how to configure it?

It’s a domain prefix with FQDN https://<prefix>.auth.<region>.amazoncognito.com where,

• prefix : unique identifier of your choice
• region: AWS region where user pool is hosted.

This domain is used to host sign-up and sign-in pages by Amazon Cognito. You can edit those pages for your company branding as well as explained in the next step.

Navigate to App integration > Domain name on the left sidebar menu on the user pool page.

Enter the prefix in the given text box and click Check availability. It will make sure you chose a unique prefix. Click on Save changes

You can opt to choose your own domain as well. You need to have an associated SSL certificate in ACM and permission to add the ALIAS record in the DNS hosted zone.

Once done, Cognito will create Amazon Cloudfront distribution for that domain in the backend and supply you with the alias target value to be configured in the hosted zone.

Add ALIAS record (CNAME for non-Route53) for Domain name and Alias target mentioned above. Once done and CloudFront distribution is created, your domain status will be set to ACTIVE.

How to change login UI of Amazon Cognito?

Navigate to App integration > App client settings on the left sidebar menu on the user pool page.

On the last part of the page, you can find Hosted UI settings. There you will be able to play around with CSS, logo files to create a new custom login page.

Make sure you have Amazon Cognito domain name defined and at least one OAuth scope defined (above step)

How to retrieve Amazon app client secret?

Navigate to General settings > App clients on the left sidebar menu on the user pool page. And there you can retrieve app client secret.