Creating An Amazon Cognito User Pool In order to Implement An SSO
In my quest for setting up an SSO (signle-sign-on) for a web platform I'm building, I discovered Amazon Cognito, which provides authentication, authorization, and user management for your web and mobile apps.
Once you have created a user pool, you can then create user groups within that pool and assign users to those groups. Applications that integrate with the user pool will be able to see the groups a user is part of. If you are implementing this integration, you can use that information to grant user permissions within the application. E.g. users that are members of the billing group should be able to create invoices etc.
In another tutorial, I will show you how you can integrate with Amazon Cognito in your PHP-based web applications in order to authenticate users, and achieve this SSO functionality whereby users only have to log in and log out once from a single location across all of your web applications (a shared authentication session).
It will likely help if you have set up SES outside of sandbox mode with a verified email address so that Cognito can use this for performing email verification and account recovery.
- Create User Pool
- Set Pool Name
- User Sign In
- Required User Attributes
- Password Strength, User Registration, and Temporary Passwords
- Account Recovery
- Attribute Verfication
- SMS Permissions
- Email Settings
- Configure Cognito To Send Through SES
- Customize Email Verification
- Customize Invitation Message
- Remember Devices
- Add Application Clients
- Choose Authentication Flows
- Enable/Disable User Existence Errors
- Set Attribute read and Write Permissions 1. Submit Client Creation
- Review App Clients
- Review Pool Details
- Success Message
Create User Pool
Once you open the Cognito service for the first time, y ou will see the following message. Click on Manage User Pools.
Click the button in the top-right corner to to create a user pool.
Set Pool Name
GIve a name for your user pool (1). Then click the button to Step through settings (2).
User Sign In (Username, Email, Phone)
For my application, I wish to uniquely identify user's by their email address, so I chose the following options (1). It is also a good idea to ignore case (2) with login details, as users make mistakes and/or have poor memories.
Required User Attributes
For my application, I just care about having the user's email address and name. However, if you need the other details, select them too.
Password Strength, User Registration, and Temporary Passwords
Now select the options for your users minimum required password strength (1). I would recommend either selecting all of the options and having an 8 character minimum.
I am building some internal services, rather than a public facing application, so I only allow administrators to create users (2). You are likely to want users to wish to sign up themselves though.
Finally, it's a good idea to have a short number of days for temporary passwords to expire (3). The default of 7 is okay. You may wish to reduce it to something like one.
Next, choose whether you wish to enable multi-factor authentication (1). I would recommend having this at least as optional, if not required. You can have AWS send SMS text messages (2) for MFA, but this will cost money and is slightly less secure than one-time passwords. However it is more convenient for non-tech-savvy users.
Now we need to choose how users will recover their account. Since my platform is email-based, I chose the Email only option. If you selected phone-based options earlier, you may wish for users to be able to recover their account through their phone.
Select the attributes you wish to verify. Due to the fact that my platform is email-based, I chose Email only.
If you are using the phone options before, then you will need to give Amazon cognito your aknowledgement to continue and set up a role (1). Due to the fact that I am email-only, I do not need to do this and can just skip to Next step (2).
Fill in the emailing settings, such as which region you wish for emails to originate from, as well as what address the email should be from and the reply-to address. I would recommend having set up a verified email address in the SES service before doing this.
Configure Cognito To Send Through SES
Now you can choose whether to use AWS SES to send your emails, or whether you are happy for Cognito to handle this. I would recommend setting up SES to do this, although that is a little more effort.
Customize Email Verification
Now choose whether you wish to verify emails by sending your users a link that they click on in the email that gets sent to them, or if you wish for them to be sent a code, which they then manually enter into a Cognito webpage. The link method is probably going to be the most convenient for your users.
Customize Invitation Message
You now have the opportunity to customize the invitation message that gets sent to users upon their registration (either by themselves or an admin creation).
As with all resources, you can tag this user pool. This can be particularly useful if you wish to isolate/identify different projects of yours that share the same account. These can then also be cost allocation tags, to help identify where money is being spent.
Now you need to choose whether you wish to remember user's devices.
By enabling device remembering, you can set sign-in restrictions. This is most commonly enabled to allow users to skip repeatedly having to repeatedly sign-in on the same device, but also allows limiting sign-in to only be allowed from a single device.
More information can be found in the AWS documentation for remembered devices.
Add Application Clients
Now we need to configure which "clients" will have access to this user pool. Each of our web services that form the platform will be it's own "client".
Click Add an app client
You should now see the following menu for creating a new client.
- Give a name to remember the client by. This is self-explanatory.
- Set how long the refresh tokens should live for. These are used for refreshing the ID and access tokens.
- Set how long the access token should live for. These tokens can be used to authorizing the updating of the user profile, or signing them out on their behalf.
- Configure how long the ID token lives for. This token contains details about the user attributes.
- Choose whether to generate a client secret.
Choose Authentication Flows
Now we need to pick the authentication flows we wish to allow. This will vary based on whether one has a backend app, or if it is purely frontend. Also, one may wish to implement one's own authentication flow.
Since I am developing these services on services that have a secure PHP-based backend, I just need to tick option 3 for allowing the username and password authentication flow.
Enable/Disable User Existence Errors
Now you can chose whether to enable or disable user existence errors. I would recommend that you leave this as the default of being prevented (1) Thus a malicious user would not know if they failed to login because that user doesn't exist, or whether they got the incorrect password.
Then I would also choose to keep the option of allowing tokens to be revoked (2). This will allow us to revoke tokens for implementing user logout.
Set Attribute read and Write Permissions
Next, we can click on the link Set attribute read and write permissions (1) in order to set what the client can read/update using the authorization tokens. For me, I'm going to leave this as the default with everything enabled.
Submit Client Creation
Finally, click the button to Create app client to create the client with the configuration you just stepped through (1) Repeat those steps for each client/service you have that needs to implement the SSO. Then, once you have created all of your clients, click the Next step button (2).
Review App Clients
You should now see the name of your client appear in a white box (1). You can change its name here if you like. If you need to create more clients, click Add an app client (2) and repeat the steps. However, if you are done with creating your clients, click Return to pool details (3) instead.
Review Pool Details
You will now be given a summary of the pool you are about to create, and the opportunity to edit any of the sections by clicking on the pencil icons. If you are happy with the details, click the Create pool button.
You should now get a confirmation message stating that the user pool was created, and be provided with the ID for your pool (1), and the AWS ARN (2) to uniquely identify it by for things like Terraform.
That's it! You have now created your user pool. You can now move onto configuring its domain, and integrating with it in your applications.
- Medium.com - How to refresh AWS Cognito user pool tokens for SSO
- AWS Docs - What is Amazon Cognito?
- AWS - How do I use remembered devices in my Amazon Cognito user pool?
- AWS Docs - Adding Groups to a User Pool
- medium.com - OpenID Connect Authorization Code Flow with AWS Cognito
First published: 11th November 2021