Cognito - Configure User Pool Domain

In order to use a Cognito user pool for an SSO, one will need to configure the its domain. This tutorial will show you how to do this.

Steps

Navigate to the Cognito service and click on Manage User Pools (1).

Select User Pool

Select the user pool you are interested in configuring.

Domain Type Choice

You will then be presented with the following screen, and the choice between whether to use an AWS Cognito domain for your SSO, or to use your own custom domain, which requires an SSL certificate for that domain within the Amazon certificate manager (ACM). Click the relevant link in this paragraph to go to the relevant instructions.

Using AWS Cognito Domain

If you don't want to go to the effort of configuring SSL certificate files within AWS, and are content with using an AWS cognito domain for your webiste SSO, then this is the route for you.

Fill in a subdomain that you would like for your SSO (1), and then press the button to check availability (2).

Hopefully, you got a message stating that your choice was available (1). If not, try again with the previous step. Once you have received a success message, press the button to Save changes (2).

You should now see the domain name greyed out (1), and the option to delete the domain if you change your mind. (2).

Using Custom Domain

Going down this route requires you to already have an SSL certificate.

One can always use Lets Encrypt to generate free SSL certificates. My favorite way is through using my branch of Acme PHP with DigitalOcean DNS and a simple YAML configuration file.

Certificate Manager

Click on the link to go to the AWS Certificate Manager (ACM)

Import Certificate

Notice that the AWS console has opened to the certificate manager, but it has also changed the region to North Virginia (1). This will affect us later. Click on Import (2) to import a certificate.

Input Certificates

Input the contents of your SSL certificate files into the textboxes. The certificate body (1) is the file that might be called site.crt or cert.pem. The Certificate private key (2) is likely called something like private.pem or private.key. The certificate chain file (3) is likely to have a name like chain.pem or ca.crt. Then click next (4).

Tags

You are now given an opportunity to add tags to

Review and Import

You will now see a screen outputting the details AWS managed to derivce from the certificate files. Be sure to check the domains (1) is correct, and that the key is RSA of 2048 bits (2).

AWS won't allow you to use a certificate with a key larger than 2048 bits (2).

Success Message

You should get a confirmation message (1), but the certificate will not appear in the list just yet (2).

However if you refresh the page, and y ou will see your certificate in the listings:

Go Back To Cognito

Now if you navigate back to Cognito, and try to find your user pool, you may find that it is missing (1). This is because the region was changed earlier to North Virginia (2) for the ACM. Change this back to whatever region you are in.

User Pool - Use Domain

Click on Domain name (1) and then click on Use your domain (2).

Select Certificate

Click on the AWS managed certificate input field (1), and select your certificate from the list (2). If you do not see your certificate, it is likely because it is stronger than 2048 bits. I would suggest going back to the ACM and checking.

Enter Domain Name

Now enter the domain name (1). This should match your SSL certificate (unless the certificate is a wildcard). Then click Save changes (2)

Status - Creating

You should now see the following screen indicating that AWS is setting up and it should take about 15 minutes (1). However, you can see what the alias will be (2).

Status - Created

Eventually, the status should change to Active (1). Copy the alias target (2), which we will feed into our DNS settings.

DNS

Now we need to update our DNS records so that our desired domain name is an alias of the Alias target AWS gave us earlier.

I use DigitalOcean to manage my DNS records, and it doesn't support alias records, but that's fine. We can use a CNAME record instead. Both CNAME and alias records map from one name to another name, instead of an IP address. The difference is that CNAME should be used when there are no other records on that name, whereas alias records can coexist with other records on that name. Thus, since we will only have one record for this domain, we should be fine with a CNAME record.

Click on the CNAME tab (1), before filling in the subdomain name (2), and the Alias target we were given (3). I would suggest setting the TTL to something sort like 5 minutes (300 seconds) for now.
I set short TTLs when setting things up, in case I get something wrong. Once it is all set up and working, we can increase it. Then click Create Record (5).

You should then see the record appear in your records list.

Check Record

You can check that the DNS record has propagated for you by running the dig command against your domain name, as shown below:

Conclusion

That's it! You have successfully configured the domain name for your Cognito user pool.