AWS Cognito User Pool
AWS Cognito offers the ability to manage a set of users in its user pool capability. I was looking for a way of controlling access to a web site, and Cognito seemed an ideal way of achieving this. This articles shows how to set up a user pool, how to add users to it, and how to display a login screen for your users.
Setting up the User Pool
The first step is to go to the User Pool screen in your AWS Console, and click on the Create a user pool button:
This then gives you the opportunity to name your user pool. Note that this may appear in some URLs and messages, so don’t choose anything rude here.
Once you have entered the user pool name, you can either choose to step through each setting, or to review the defaults (which sets everything to default values, and lets you update them). I chose the review option:
You can set up many different options here, for example you can set factors around the complexity of passwords your users can choose, or you can set options around multi-factor authentication (MFA). Here is an example screen, which lets you set whether users can choose an e-mail address as their username:
The important option we want to modify, is to associate an app client with our user pool. This will allow us to set up the login screen, and choose where the user is taken to after login. To do this, we click on the App clients link, and get the following screen:
Then we can save our settings and go back to the user pool review screen, where we can create the pool:
And we should get a success message, a summary of our pool details, and additional options relating to the pool:
Adding Details for the App
Now we have our user pool created, and associated with an app client, we can move on to configure the app. The first thing we need to do is specify a domain. This is actually a sub-domain under our AWS region, and therefore needs to be unique across the region. We can get there by clicking the Domain name link:
Once we have our domain name, we can configure other options. The UI Customization link gives us the ability to change the look and feel of the login page which AWS Cognito gives us. It gives us a set of CSS elements which we can change certain values for. You don’t have to edit actual CSS code, but I think that some familiarity with CSS makes this simpler:
An important set of options we need to set are the App client settings. The top half lets us choose the identity providers we will work with (I’ve selected Cognito User Pool), and URLs for login and logout. I’ve set Google as my post-login page. I’ll change it to what I actually want in a later article (when I glue this all together):
Scrolling down, we get to choose our OAuth options. If you’re not familiar with OAuth, that’s not important to understand this example. I’ll just comment that it’s an open standard for authentication, which allows us to use different authentication options, if we wish to.
So, I’m going to choose both Authorization and Implicit grant, since that gives me two options to use. I’ve also selected openid as my scope, since that gives me flexible information to use when I come to validating a user’s login:
After clicking Go to summary on the previous screen, I get the summary of my application, which reflects the changes I’ve made:
Our user pool and application are all set up, but they aren’t much use without any users. Fortunately, adding users is simple too. We can just click on the Users and groups link, which gives us the opportunity to either import or create users.
Clicking on Create user gives us a simple dialogue to add the basic details for a user:
Once we have provided a username and password, we can see our list of defined usernames:
The Login Screen
Now we’ve created the user pool, added our app, and created a user, we can test our login screen. This just needs a url of specific format:
https://[domain].auth.[region].amazoncognito.com/login ?response_type=token &client_id=[application id] &redirect_uri=[post-login URL]
The domain is the domain you set up when you created the application, the
application id you can see on your App client settings screen, and the
post-login URL is where you want to go after a successful login. Note that
the post-login URL must match the value (or one of the values) supplied in
the App client settings earlier. If this is not the case, you will get a
If you put the appropriate values in the above URL, you should see a screen like this:
We can see how this form can be modified by Cognito settings, by looking at the Sign up link on that page (you can see it at the bottom of the login box). Suppose that in my example, I don’t want to allow users to sign themselves up, I want to add them all myself. I can go back to the Policies screen for my user pool, select Only allow administrators to create users, and save:
Now if you go back to your login screen, you will see that the Sign up link is no longer there:
Try to log in using an incorrect password, and you should remain on the login screen, with a warning displayed:
Now log in with the correct details, and you will be taken to a Change Password screen. This will only happen the first time, and is because your original password was set by an administrator for you:
Once you have changed your password (or directly after login for subsequent attempts), you will be taken to your redirect URL:
Note that appended on to our URL is a an id token. This is a Json Web Token (JWT) which contains information about the logged in user, and any rights they have. In the next article, we look at the structure of the JWT, and what we need to do to parse it.
What this article has shown, is how simple it is to set up a Cognito User Pool in AWS, and use that to set up, authenticate, and authorise users. It does this whilst providing an extensive set of features (such as setting password security levels, automatic password invalidation, 2FA, etc).