Information


Blog Posts


Collections



Contact


Things Ian Says

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:

Picture

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.

Picture

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:

Picture

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:

Picture

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:

Picture

We can then click on Add an app client, which allows us to start adding details. I have chosen a name for the app client (the same as my user pool, but it doesn’t have to be). Note that the Javascript SDK does not support use of a client secret, so you will need to uncheck that option if you want to use Javascript to handle your login process.

Picture

Then we can save our settings and go back to the user pool review screen, where we can create the pool:

Picture

And we should get a success message, a summary of our pool details, and additional options relating to the pool:

Picture

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:

Picture

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:

Picture

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):

Picture

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:

Picture

After clicking Go to summary on the previous screen, I get the summary of my application, which reflects the changes I’ve made:

Picture

Adding Users

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.

Picture

Clicking on Create user gives us a simple dialogue to add the basic details for a user:

Picture

Once we have provided a username and password, we can see our list of defined usernames:

Picture

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 redirect_mismatch error.

If you put the appropriate values in the above URL, you should see a screen like this:

Picture

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:

Picture

Now if you go back to your login screen, you will see that the Sign up link is no longer there:

Picture

Try to log in using an incorrect password, and you should remain on the login screen, with a warning displayed:

Picture

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:

Picture

Once you have changed your password (or directly after login for subsequent attempts), you will be taken to your redirect URL:

Picture

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.

Summary

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).