Amazon Cognito
Developer Guide

Adding a Custom Domain to a User Pool

After setting up an app client, you can configure the address of your sign-up and sign-in webpages. With a custom user pool domain, you can enable your users to sign in to Amazon Cognito using your own web address.

Prerequisites

Before you begin, you need:

  • A user pool with an app client. For more information, see Getting Started with User Pools.

  • A web domain that you own. Its root must have a valid A record in DNS. For more information see Domain Names.

  • A subdomain for your custom domain. We recommend using auth as the subdomain. For example: auth.example.com.

    Note

    You might need to obtain a new certificate for your custom domain's subdomain if you don't have a wildcard certificate.

  • A Secure Sockets Layer (SSL) certificate managed by AWS Certificate Manager. You must change the AWS region to US East (N. Virginia) in the ACM console before you request or import a certificate.

  • To set up a custom domain name or to update its certificate, you must have permission to update Amazon CloudFront distributions. You can do so by attaching the following IAM policy statement to an IAM user, group, or role in your AWS account:

    { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowCloudFrontUpdateDistribution", "Effect": "Allow", "Action": [ "cloudfront:updateDistribution" ], "Resource": [ "*" ] } ] }

    See Using Identity-Based Policies (IAM Policies) for CloudFront.

Step 1: Choose a Custom Domain Name

To choose your custom domain name from AWS Certificate Manager

  1. Sign in to the Amazon Cognito console. You might be prompted for your AWS credentials.

  2. In the navigation pane, choose Manage your User Pools, and choose the user pool you want to edit.

  3. On the navigation bar on the left-side of the page, choose Domain name.

  4. Choose Use your domain.

  5. Type your custom domain name. You can form domain names from the set of alphanumeric ASCII characters (a-z, A-Z, 0-9). The hyphen (U+002D) is also permitted, but not as the first or last character of a domain name.

  6. Choose AWS-managed certificate from Amazon Certificate Manager. This certificate is managed by AWS, including its creation and renewal for a given custom domain.

    If your certificate doesn't appear in the list, you can get one by choosing Provision certificates from https://console.aws.amazon.com/acm/.

  7. Choose Save changes.

  8. Note the Alias target. Instead of an IP address or a domain name, the Alias target is an alias resource record set that points to an Amazon CloudFront distribution.

Step 2: Add an Alias Target and Subdomain

In this step, you set up an alias through your Domain Name Server (DNS) service provider that points back to the alias target from the previous step. If you are using Amazon Route 53 for DNS address resolution, choose the section To add an alias target and subdomain using Route 53.

To add an alias target and subdomain to your current DNS configuration
  • If you aren't using Route 53 for DNS address resolution, then you need to have your DNS service provider add the alias target from the previous step as an alias for your user pool custom domain. Your DNS provider will also need to set up the subdomain for your custom domain.

To add an alias target and subdomain using Route 53
  1. Sign in to the Route 53 console. You might be prompted for your AWS credentials.

  2. If you don't have a hosted zone in Route 53, set one up. Otherwise, skip this step.

    1. Choose Create Hosted Zone.

    2. Choose your custom domain from the Domain Name list.

    3. For Comment, type an optional comment about the hosted zone.

    4. Choose Create.

  3. On the Hosted Zones page, choose the name of your hosted zone.

  4. Choose Create Record Set.

  5. Select Yes for the Alias option.

  6. Type the alias target name that you noted in a previous step into Alias Target.

  7. Choose Create.

    Note

    Your new records take time to propagate to the Route 53 DNS servers. Currently, the only way to verify that changes have propagated is to use the Route 53 GetChange API method. Changes generally propagate to all Route 53 name servers within 60 seconds.

  8. Add a subdomain in Route 53 by using the alias target.

    1. On the Hosted Zones page, choose the name of your hosted zone.

    2. Choose Create Record Set and enter the following values:

      1. For Name, type your preferred subdomain name. For example, if the subdomain you’re attempting to create is auth.example.com, type auth.

      2. For Type, choose A - IPv4 address.

      3. Select Yes for the Alias option.

      4. Type the alias target name that you noted in a previous step in Alias Target.

    3. Choose Create.

      Note

      Alternatively, you can create a new hosted zone to hold the records that are associated with your subdomain. You can also createa delegation set in the parent hosted zone that refers clients to the subdomain hosted zone. This method offers more flexibility when you're managing the hosted zones (for example, restricting who can edit the zones). You can only use this method for public hosted zones, because adding NS records to private hosted zones isn't currently supported. For more information, see Creating a subdomain for a domain hosted through Amazon Route 53.

Step 3: Verify Your Sign-in Page

  • Verify that the sign-in page is available from your custom domain.

    Sign in with your custom domain and subdomain by entering this address into your browser. This is an example URL of a custom domain example.com with the subdomain auth:

    https://auth.example.com/login?response_type=code&client_id=<your_app_client_id>&redirect_uri=<your_callback_url>