# Configuring a user pool domain Configuring a domain Configuring a domain is an optional part of setting up a user pool. A user pool domain hosts features for user authentication, federation with third-party providers, and OpenID Connect (OIDC) flows. It has *managed login*, a prebuilt interface for key operations like signing up, signing in, and password recovery. It also hosts the standard OpenID Connect (OIDC) endpoints like [authorize](authorization-endpoint.md), [userInfo](userinfo-endpoint.md), and [token](token-endpoint.md), for machine-to-machine (M2M) authorization and other OIDC and OAuth 2.0 authentication and authorization flows. Users authenticate with managed login pages at the domain associated with your user pool. You have two options for configuring this domain: you can either use the default Amazon Cognito hosted domain, or you can configure a custom domain that you own. The custom domain option has more options for flexibility, security and control. For example, a familiar, organization-owned domain can encourage user trust and make the sign-in process more intuitive. However, the custom domain approach requires some additional overhead, like managing the SSL certificate and DNS configuration. The OIDC discovery endpoints, `/.well-known/openid-configuration` for endpoint URLs and `/.well-known/jwks.json` for token signing keys, aren't hosted on your domain. For more information, see [Identity provider and relying party endpoints](federation-endpoints.md). Understanding how to configure and manage the domain for your user pool is an important step in integrating authentication into your application. Sign-in with the user pools API and an AWS SDK can be an alternative to configuring a domain. The API-based model delivers tokens directly in an API response, but for implementations that use the extended capabilities of user pools as an OIDC IdP, you must configure a domain. For more information about the authentication models that are available in user pools, see [Understanding API, OIDC, and managed login pages authentication](authentication-flows-public-server-side.md#user-pools-API-operations). **Topics** + [ ## Things to know about user pool domains ](#cognito-user-pools-assign-domain-things-to-know) + [ # Using the Amazon Cognito prefix domain for managed login ](cognito-user-pools-assign-domain-prefix.md) + [ # Using your own domain for managed login ](cognito-user-pools-add-custom-domain.md) ## Things to know about user pool domains User pool domains are a point of service for OIDC relying parties in your applications and for UI elements. Consider the following details when you're planning your implementation of a domain for your user pool. **Reserved terms** You can't use the text `aws`, `amazon`, or `cognito` in the name of an Amazon Cognito prefix domain. **Discovery endpoints are on a different domain** The user pool [discovery endpoints](federation-endpoints.md) `.well-known/openid-configuration` and `.well-known/jwks.json` aren't on your user pool custom or prefix domain. The path to these endpoints is as follows. + `https://cognito-idp.Region.amazonaws.com/your user pool ID/.well-known/openid-configuration` + `https://cognito-idp.Region.amazonaws.com/your user pool ID/.well-known/jwks.json` **Effective time of domain changes** It can take Amazon Cognito up to a minute to launch or update the branding version of a prefix domain. Changes to a custom domain can take up to five minutes to propagate. New custom domains can take up to one hour to propagate. **Custom and prefix domains at the same time** You can set up a user pool with both a custom domain and a prefix domain that's owned by AWS. Because the user pool [discovery endpoints](federation-endpoints.md) are hosted at a different domain, they only serve the *custom domain*. For example, your `openid-configuration` will provide a single value for `"authorization_endpoint"` of `"https://auth.example.com/oauth2/authorize"`. When you have both custom and prefix domains in a user pool, you can use the custom domain with the full features of an OIDC provider. The prefix domain in a user pool with this configuration doesn't have discovery or token-signing-key endpoints and should be used accordingly. **Custom domains preferred as relying party ID for passkey** When you set up user pool authentication with [passkeys](amazon-cognito-user-pools-authentication-flow-methods.md#amazon-cognito-user-pools-authentication-flow-methods-passkey), you must set a relying party (RP) ID. When you have a custom domain and a prefix domain, you can set the RP ID only as your custom domain. To set a prefix domain as the RP ID in the Amazon Cognito console, delete your custom domain or enter the fully-qualified domain name (FQDN) of the prefix domain as a **Third-party domain**. **Don't use custom domains at different levels of your domain hierarchy** You can configure separate user pools to have custom domains in the same top-level domain (TLD), for example *auth.example.com* and *auth2.example.com*. The managed login session cookie is valid for a custom domain and all subdomains, for example *\$1.auth.example.com*. Because of this, no user of your applications should access managed login for any parent domain *and* subdomain. Where custom domains use the same TLD, keep them at the same subdomain level. Say you have a user pool with the custom domain *auth.example.com*. Then you create another user pool and assign the custom domain *uk.auth.example.com.*. A user signs in with *auth.example.com.* and gets a cookie that their browser presents to any website in the wildcard path *\$1.auth.example.com*. They then try to sign in to *uk.auth.example.com.*. They pass an invalid cookie to your user pool domain and receive an error instead of a sign-in prompt. By contrast, a user with a cookie for *\$1.auth.example.com* has no issues starting a sign-in session at *auth2.example.com*. **Branding version** When you create a domain, you set a **Branding version**. Your options are the newer managed-login experience and the classic hosted UI experience. This choice applies to all app clients that host services at your domain. # Using the Amazon Cognito prefix domain for managed login Add a prefix domain The default experience for managed login is hosted on a domain that AWS owns. This approach has a low barrier to entry—choose a prefix name and it's active—but doesn't have the trust-inspiring features of a custom domain. There isn't a cost difference between the Amazon Cognito domain option and the custom domain option. The only difference is the domain in the web address that you direct your users to. For cases of third-party IdP redirects and client-credentials flows, the hosted domain has little visible effect. A custom domain is better for cases where your users sign in with managed login and would interact with a authentication domain that doesn't match the application domain. The hosted Amazon Cognito domain has a prefix of your choosing, but is hosted at the root domain `amazoncognito.com`. The following is an example: ``` https://cognitoexample.auth.ap-south-1.amazoncognito.com ``` All prefix domains follow this format: `prefix`.`auth`.*`AWS Region code`*.`amazoncognito`.`com`. [Custom domain](cognito-user-pools-add-custom-domain.md) user pools can host the managed login or hosted UI pages on any domain that you own. **Note** To augment the security of your Amazon Cognito applications, the parent domains of user pool endpoints are registered in the [Public Suffix List (PSL)](https://publicsuffix.org/). The PSL helps your users' web browsers establish a consistent understanding of your user pool endpoints and the cookies they set. User pool parent domains take the following formats. ``` auth.Region.amazoncognito.com auth-fips.Region.amazoncognito.com ``` To add an app client and a user pool domain with the AWS Management Console, see [Creating an app client](user-pool-settings-client-apps.md#cognito-user-pools-app-idp-settings-console-create). **Topics** + [ ## Prerequisites ](#cognito-user-pools-assign-domain-prefix-prereq) + [ ## Configure an Amazon Cognito domain prefix ](#cognito-user-pools-assign-domain-prefix-step-1) + [ ## Verify your sign-in page ](#cognito-user-pools-assign-domain-prefix-verify) ## Prerequisites Before you begin, you need: + A user pool with an app client. For more information, see [Getting started with user pools](getting-started-user-pools.md). ## Configure an Amazon Cognito domain prefix You can use either the AWS Management Console or the AWS CLI or API to configure a user pool domain. ------ #### [ Amazon Cognito console ] **Configure a domain** 1. Navigate to the **Domain** menu under **Branding**. 1. Next to **Domain**, choose **Actions** and select **Create Cognito domain**. If you have already configured a user pool prefix domain, choose **Delete Cognito domain** before creating your new custom domain. 1. Enter an available domain prefix to use with a **Amazon Cognito domain**. For information on setting up a **Custom domain**, see [Using your own domain for managed login](cognito-user-pools-add-custom-domain.md). 1. Choose a **Branding version**. Your branding version applies to all user-interactive pages at that domain. Your user pool can host either managed login or hosted UI branding for all app clients. **Note** You can have a custom domain and a prefix domain, but Amazon Cognito only serves the `/.well-known/openid-configuration` endpoint for the *custom* domain. 1. Choose **Create**. ------ #### [ CLI/API ] Use the following commands to create a domain prefix and assign it to your user pool. **To configure a user pool domain** + AWS CLI: `aws cognito-idp create-user-pool-domain` **Example:** `aws cognito-idp create-user-pool-domain --user-pool-id --domain --managed-login-version 2` + User pools API operation: [CreateUserPoolDomain](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolDomain.html) **To get information about a domain** + AWS CLI: `aws cognito-idp describe-user-pool-domain` **Example:** `aws cognito-idp describe-user-pool-domain --domain ` + User pools API operation: [DescribeUserPoolDomain](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeUserPoolDomain.html) **To delete a domain** + AWS CLI: `aws cognito-idp delete-user-pool-domain` **Example:** `aws cognito-idp delete-user-pool-domain --domain ` + User pools API operation: [DeleteUserPoolDomain](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DeleteUserPoolDomain.html) ------ ## Verify your sign-in page + Verify that the sign-in page is available from your Amazon Cognito hosted domain. ``` https:///login?response_type=code&client_id=&redirect_uri= ``` Your domain is shown on the **Domain name** page of the Amazon Cognito console. Your app client ID and callback URL are shown on the **App client settings** page. # Using your own domain for managed login Using your own domain After you set up an app client, you can configure your user pool with a custom domain for the domain services of [managed login](cognito-user-pools-managed-login.md). With a custom domain, users can sign in to your application using your own web address instead the default `amazoncognito.com` [prefix domain](cognito-user-pools-assign-domain-prefix.md). Custom domains improve user trust in your application with a familiar domain name, especially when the root domain matches the domain that hosts your application. Custom domains can improve compliance with organizational security requirements. A custom domain has some prerequisites, including a user pool, an app client, and a web domain that you own. Custom domains also require an SSL certificate for the custom domain, managed with AWS Certificate Manager (ACM) in US East (N. Virginia). Amazon Cognito creates a Amazon CloudFront distribution, secured in transit with your ACM certificate. Because you own the domain, you must create a DNS record that directs traffic to the CloudFront distribution for your custom domain. After these elements are ready, you can add the custom domain to your user pool through the Amazon Cognito console or API. This involves specifying the domain name and SSL certificate, and then updating your DNS configuration with the provided alias target. After making these changes, you can verify that the sign-in page is accessible at your custom domain. The lowest-effort way to create a custom domain is with a public hosted zone in Amazon Route 53. The Amazon Cognito console can create the right DNS records in a few steps. Before you begin, consider [creating a Route 53 hosted zone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingHostedZone.html) for a domain or subdomain that you own. **Topics** + [ ## Adding a custom domain to a user pool ](#cognito-user-pools-add-custom-domain-adding) + [ ## Prerequisites ](#cognito-user-pools-add-custom-domain-prereq) + [ ## Step 1: Enter your custom domain name ](#cognito-user-pools-add-custom-domain-console-step-1) + [ ## Step 2: Add an alias target and subdomain ](#cognito-user-pools-add-custom-domain-console-step-2) + [ ## Step 3: Verify your sign-in page ](#cognito-user-pools-add-custom-domain-console-step-3) + [ ## Changing the SSL certificate for your custom domain ](#cognito-user-pools-add-custom-domain-changing-certificate) ## Adding a custom domain to a user pool Adding a custom domain To add a custom domain to your user pool, you specify the domain name in the Amazon Cognito console, and you provide a certificate you manage with [AWS Certificate Manager](https://docs.aws.amazon.com/acm/latest/userguide/) (ACM). After you add your domain, Amazon Cognito provides an alias target, which you add to your DNS configuration. ## Prerequisites Before you begin, you need: + A user pool with an app client. For more information, see [Getting started with user pools](getting-started-user-pools.md). + A web domain that you own. Its *parent domain* must have a valid DNS **A record**. You can assign any value to this record. The parent may be the root of the domain, or a child domain that is one step up in the domain hierarchy. For example, if your custom domain is *auth.xyz.example.com*, Amazon Cognito must be able to resolve *xyz.example.com* to an IP address. To prevent accidental impact on customer infrastructure, Amazon Cognito doesn't support the use of top-level domains (TLDs) for custom domains. For more information see [Domain Names](https://tools.ietf.org/html/rfc1035). + The ability to create a subdomain for your custom domain. We recommend **auth** for your subdomain name. 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](https://en.wikipedia.org/wiki/Wildcard_certificate). + A public SSL/TLS certificate managed by ACM in US East (N. Virginia). The certificate must be in us-east-1 because the certificate will be associated with a distribution in CloudFront, a global service. + Browser clients that support Server Name Indication (SNI). The CloudFront distribution that Amazon Cognito assigns to custom domains requires SNI. You can't change this setting. For more information about SNI in CloudFront distributions, see [Use SNI to serve HTTPS requests](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cnames-https-dedicated-ip-or-sni.html#cnames-https-sni) in the *Amazon CloudFront Developer Guide*. + An application that permits your user pool authorization server to add cookies to user sessions. Amazon Cognito sets several required cookies for managed login pages. These include `cognito`, `cognito-fl`, and `XSRF-TOKEN`. Although each individual cookie conforms to browser size limits, changes to your user pool configuration might cause managed login cookies to grow in size. An intermediate service like an Application Load Balancer (ALB) in front of your custom domain might enforce a maximum header size or total cookie size. If your application also sets its own cookies, your users' sessions might exceed these limits. We recommend that, to avoid size limit conflicts, your application not set cookies on the subdomain that hosts your user pool domain services. + Permission to update Amazon CloudFront distributions. You can do so by attaching the following IAM policy statement to a user in your AWS account: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowCloudFrontUpdateDistribution", "Effect": "Allow", "Action": [ "cloudfront:updateDistribution" ], "Resource": [ "*" ] } ] } ``` ------ For more information about authorizing actions in CloudFront, see [Using Identity-Based Policies (IAM Policies) for CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/access-control-managing-permissions.html). Amazon Cognito initially uses your IAM permissions to configure the CloudFront distribution, but the distribution is managed by AWS. You can't change the configuration of the CloudFront distribution that Amazon Cognito associated with your user pool. For example, you can't update the supported TLS versions in the security policy. ## Step 1: Enter your custom domain name You can add your domain to your user pool by using the Amazon Cognito console or API. ------ #### [ Amazon Cognito console ] **To add your domain to your user pool from the Amazon Cognito console:** 1. Navigate to the **Domain** menu under **Branding**. 1. Next to **Domain**, choose **Actions** and select **Create custom domain** or **Create Amazon Cognito domain**. If you have already configured a user pool custom domain, choose **Delete custom domain** before creating your new custom domain. 1. Next to **Domain**, choose **Actions** and select **Create custom domain**. If you have already configured a custom domain, choose **Delete custom domain** to delete the existing domain before creating your new custom domain. 1. For **Custom domain**, enter the URL of the domain you want to use with Amazon Cognito. Your domain name can include only lowercase letters, numbers, and hyphens. Do not use a hyphen for the first or last character. Use periods to separate subdomain names. 1. For **ACM certificate**, choose the SSL certificate that you want to use for your domain. Only ACM certificates in US East (N. Virginia) are eligible to use with an Amazon Cognito custom domain, regardless of the AWS Region of your user pool. If you don't have an available certificate, you can use ACM to provision one in US East (N. Virginia). For more information, see [Getting Started](https://docs.aws.amazon.com/acm/latest/userguide/gs.html) in the *AWS Certificate Manager User Guide*. 1. Choose a **Branding version**. Your branding version applies to all user-interactive pages at that domain. Your user pool can host either managed login or hosted UI branding for all app clients. **Note** You can have a custom domain and a prefix domain, but Amazon Cognito only serves the `/.well-known/openid-configuration` endpoint for the *custom* domain. 1. Choose **Create**. 1. Amazon Cognito returns you to the **Domain** menu. A message titled **Create an alias record in your domain's DNS** is displayed. Note down the **Domain** and **Alias target** displayed in the console. They will be used in the next step to direct traffic to your custom domain. ------ #### [ API ] The following [CreateUserPoolDomain](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolDomain.html) request body creates a custom domain. ``` { "Domain": "auth.example.com", "UserPoolId": "us-east-1_EXAMPLE", "ManagedLoginVersion": 2, "CustomDomainConfig": { "CertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111" } } ``` ------ ## 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 must use your DNS service provider's configuration tools to add the alias target from the previous step to your domain's DNS record. 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](https://console.aws.amazon.com/route53/). If prompted, enter your AWS credentials. 1. If you don't have a public hosted zone in Route 53, create one with a root that is a parent of your custom domain. For more information, see [Creating a public hosted zone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingHostedZone.html) in the *Amazon Route 53 Developer Guide*. 1. Choose **Create Hosted Zone**. 1. Enter the parent domain, for example *auth.example.com*, of your custom domain, for example *myapp.auth.example.com*, from the **Domain Name** list. 1. Enter a **Description** for your hosted zone. 1. Choose a hosted zone **Type** of **Public hosted zone** to allow public clients to resolve your custom domain. Choosing **Private hosted zone** is not supported. 1. Apply **Tags** as desired. 1. Choose **Create hosted zone**. **Note** You can also create a new hosted zone for your custom domain with a delegation set in the parent hosted zone that directs queries to the subdomain hosted zone. Otherwise, create an A record. This method offers more flexibility and security with your hosted zones.For more information, see [Creating a subdomain for a domain hosted through Amazon Route 53](https://aws.amazon.com/premiumsupport/knowledge-center/create-subdomain-route-53/). 1. On the **Hosted Zones** page, choose the name of your hosted zone. 1. Add a DNS record for the parent domain of your custom domain, if you don’t already have one. Create a DNS record for the parent domain with the following properties: + **Record name**: Leave blank. + **Record type**: `A`. + **Alias**: Don't enable. + **Value**: Enter a target of your choosing. This record must resolve to *something*, but the value of the record doesn't matter to Amazon Cognito. + **TTL**: Set to your preferred TTL or leave as default. + **Routing policy**: Choose **Simple routing**. 1. Choose **Create records**. The following is an example record for the domain *example.com*: `example.com. 60 IN A 198.51.100.1` **Note** Amazon Cognito verifies that there is a DNS record for the parent domain of your custom domain to protect against accidental hijacking of production domains. If you do not have a DNS record for the parent domain, Amazon Cognito will return an error when you attempt to set the custom domain. A Start of Authority (SOA) record isn't a sufficient DNS record for the purposes of parent-domain verification. 1. Add another DNS record for your custom domain with the following properties: + **Record name**: Your custom domain prefix, for example `auth` to create a record for `auth.example.com`. + **Record type**: `A`. + **Alias**: Enable. + **Route traffic to**: Choose **Alias to Cloudfront distribution**. Enter the **Alias target** you recorded earlier, for example `123example.cloudfront.net`. + **Routing policy**: Choose **Simple routing**. 1. Choose **Create records**. **Note** Your new records can take around 60 seconds to propagate to all Route 53 DNS servers. You can use the Route 53 [GetChange](https://docs.aws.amazon.com/Route53/latest/APIReference/API_GetChange.html) API method to verify that your changes have propagated. ## 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://myapp.auth.example.com/login?response_type=code&client_id=&redirect_uri= ``` ## Changing the SSL certificate for your custom domain Changing the certificate When necessary, you can use Amazon Cognito to change the certificate that you applied to your custom domain. Usually, this is unnecessary following routine certificate renewal with ACM. When you renew your existing certificate in ACM, the ARN for your certificate remains the same, and your custom domain uses the new certificate automatically. However, if you replace your existing certificate with a new one, ACM gives the new certificate a new ARN. To apply the new certificate to your custom domain, you must provide this ARN to Amazon Cognito. After you provide your new certificate, Amazon Cognito requires up to 1 hour to distribute it to your custom domain. **Before you begin** Before you can change your certificate in Amazon Cognito, you must add your certificate to ACM. For more information, see [Getting Started](https://docs.aws.amazon.com/acm/latest/userguide/gs.html) in the *AWS Certificate Manager User Guide*. When you add your certificate to ACM, you must choose US East (N. Virginia) as the AWS Region. You can change your certificate by using the Amazon Cognito console or API. ------ #### [ AWS Management Console ] **To renew a certificate from the Amazon Cognito console:** 1. Sign in to the AWS Management Console and open the Amazon Cognito console at [https://console.aws.amazon.com/cognito/home](https://console.aws.amazon.com/cognito/home). 1. Choose **User Pools**. 1. Choose the user pool for which you want to update the certificate. 1. Choose the **Domain** menu. 1. Choose **Actions**, **Edit ACM certificate**. 1. Select the new certificate you want to associate with your custom domain. 1. Choose **Save changes**. ------ #### [ API ] **To renew a certificate (Amazon Cognito API)** + Use the [UpdateUserPoolDomain](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPoolDomain.html) action. ------