Tanseer for AWS Community Builders

Posted on Jun 2

How to Add a Custom Domain to AWS Cognito Google Login (And the Errors Nobody Warns You About)

#aws #community #cloud #serverless

Who This Is For

If you are using AWS Cognito to handle user authentication in your app and you have added Google as a social login option, you may have noticed something uncomfortable. When a user clicks "Sign in with Google", the URL in the browser does not say your domain. It says something like:

https://yourapp.auth.us-east-1.amazoncognito.com

That is the default Cognito hosted UI URL. It works, but it looks like your users are leaving your app to sign in somewhere else. It does not look professional, and for security conscious users, it can feel suspicious.

The fix is to set up a custom domain so the login page shows your own URL, something like:

https://auth.yourdomain.com

This guide walks through the full setup step by step, and more importantly, it covers the three errors you will likely hit along the way.

Before You Start

Here is what you need to have in place before following this guide:

A Cognito User Pool already created with Google set up as a social identity provider. If you have not done that yet, set that up first and come back here.

A domain you own, managed in Route 53 (AWS's domain and DNS service). The subdomain you will be using for the login page, something like auth.yourdomain.com, should not be pointing anywhere yet.

Access to the Google Cloud Console where your OAuth app is configured.

Step 1: Create an ACM Certificate — But Only in us-east-1

This is the first place most developers go wrong, and it is the most confusing one because nothing in the Cognito console tells you about it until you are already stuck.

ACM stands for AWS Certificate Manager. It is the service AWS uses to create and manage SSL certificates. An SSL certificate is what makes your domain load over HTTPS (the secure version of HTTP) and shows the padlock icon in the browser.

You need to create a certificate for your custom domain, like auth.yourdomain.com. That part is straightforward. The gotcha is the region.

Even if your Cognito User Pool is in a different region, say ap-south-1 or eu-west-1, the ACM certificate must be created in us-east-1. No exceptions.

The reason is that Cognito uses CloudFront behind the scenes to serve the hosted UI. CloudFront is a global content delivery service, and it only accepts SSL certificates from the us-east-1 region. Your Cognito User Pool can be anywhere, but the certificate must always be in us-east-1.

Here is how to create it:

Go to the AWS Console and switch your region to US East (N. Virginia) which is us-east-1. You can change the region from the top right dropdown in the console.
Search for "Certificate Manager" and open ACM.
Click "Request a certificate".
Choose "Request a public certificate" and click Next.
Enter your domain name. Use the subdomain you want for login, for example auth.yourdomain.com.
Choose "DNS validation" as the validation method. This is the recommended option.
Click "Request". After requesting, ACM will give you a CNAME record that you need to add to your DNS to prove you own the domain. Go to Route 53, open your hosted zone, and add that CNAME record exactly as ACM shows it.

Once the record is in place, ACM will automatically verify it and mark the certificate as "Issued". This usually takes a few minutes but can take up to 30 minutes.

Do not move to the next step until the certificate status shows "Issued".

Step 2: Add the Custom Domain in Cognito

Now that the certificate is ready, go back to your Cognito User Pool. Make sure you are in the correct region where your User Pool lives, not us-east-1 unless that is where your pool is.

Open your User Pool in the Cognito console.
Go to the "App integration" tab.
Scroll down to "Domain" and click "Actions", then "Create custom domain".
Enter your custom domain, for example auth.yourdomain.com.
In the SSL certificate dropdown, select the ACM certificate you just created. It will only appear if the certificate is in us-east-1 and has a status of Issued.
Click "Create". After saving, Cognito will provision a CloudFront distribution for your domain. This can take anywhere from 15 to 40 minutes. You will see a CloudFront domain name appear once it is ready, something like d1234abcde.cloudfront.net. Copy this value. You will need it in the next step.

Step 3: Add the DNS Record in Route 53

This is the second place where things can go wrong.

Once Cognito gives you the CloudFront domain, you need to create a DNS record so that when someone visits auth.yourdomain.com, they are pointed to that CloudFront distribution.

The record type to use here is an Alias record, not a CNAME. Route 53 has a special Alias record type that is designed to point to AWS services like CloudFront. Using a regular CNAME at the root level of a subdomain can cause issues, so always use Alias when pointing to a CloudFront domain in Route 53.

Here is how to add it:

Open Route 53 in the AWS Console.
Go to "Hosted zones" and open your domain.
Click "Create record".
Set the record name to auth (Route 53 will append your domain automatically).
Set the record type to "A".
Toggle on "Alias".
In the "Route traffic to" dropdown, choose "Alias to CloudFront distribution".
Paste the CloudFront domain that Cognito gave you.
Click "Create records". DNS changes can take a few minutes to a few hours to fully propagate. You can check the status using a tool like MXToolbox or WhatsMyDNS by looking up your subdomain.

Step 4: Update the Redirect URI in Google Cloud Console

This is the third gotcha, and it is easy to miss because everything might look like it is working until a user actually tries to sign in with Google and gets an error.

When Google handles the OAuth login flow (OAuth is the protocol that lets users sign in with their Google account), it redirects the user back to a specific URL after they authenticate. That URL is called the redirect URI.

Before you set up the custom domain, Cognito's redirect URI was something like:

https://yourapp.auth.us-east-1.amazoncognito.com/oauth2/idpresponse

Now that you have a custom domain, the redirect URI has changed to:

https://auth.yourdomain.com/oauth2/idpresponse

Google will reject any redirect to a URI that is not explicitly listed as an authorized redirect URI in your OAuth app settings. If you do not update this, users will see a Google error page saying the redirect URI is not authorized.

Here is how to update it:

Go to the Google Cloud Console at console.cloud.google.com.
Open your project and navigate to "APIs and Services", then "Credentials".
Click on the OAuth 2.0 Client ID you created for Cognito.
Under "Authorized redirect URIs", click "Add URI".
Add your new redirect URI: https://auth.yourdomain.com/oauth2/idpresponse
Also update "Authorized JavaScript origins" if it was set to the old Cognito domain. Add https://auth.yourdomain.com.
Click "Save". You do not need to remove the old Cognito URI right away. Keep both for now while you test the new setup, and remove the old one once everything is confirmed working.

Step 5: Test the Full Flow

Once all the above steps are done and DNS has propagated, test the complete sign in flow from your app.

Open your app and trigger the Google login. The URL in the browser should now show auth.yourdomain.com instead of the Cognito domain. The user should be able to complete the Google sign in and land back in your app without any errors.

If you see a Google error about redirect URI mismatch, double check Step 4. If you see an SSL error, double check that the ACM certificate is in us-east-1 and is fully issued. If the DNS is not resolving, give it more time or check your Route 53 record.

Quick Summary of the Three Errors to Avoid

The ACM certificate must be in us-east-1 no matter what region your Cognito User Pool is in. Creating it in the wrong region means it will not appear in the Cognito domain setup and you will waste time wondering why.

The DNS record in Route 53 should be an Alias A record pointing to the CloudFront domain, not a plain CNAME. Using the wrong record type can cause resolution issues.

The redirect URI in Google Cloud Console must be updated to the new custom domain. Forgetting this means Google will block the login flow and your users will see an error.

Conclusion

Adding a custom domain to your Cognito login page is a small change that makes a big difference in how professional and trustworthy your app feels. The steps themselves are not complicated, but the three gotchas around the ACM region, DNS record type, and Google redirect URI are not obvious and not well documented in one place.

If you follow this guide in order and do not skip steps, you should have your custom domain up and running without the frustration of debugging silent failures.