Configuring a user pool 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 the hosted UI, 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, userInfo, and token, for machine-to-machine (M2M) authorization and other OIDC and OAuth 2.0 authentication and authorization flows.

Users sign in to the hosted UI 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.

Understanding how to configure and manage the domain for your Amazon Cognito 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 Using the user pools API and authorization server.

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 .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.

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 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.

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 hosted UI session cookie is valid for a custom domain and all subdomains, for example *.auth.example.com. Because of this, no user of your applications should access the hosted UI 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 *.auth.example.com. They then try to sign in to uk.auth.example.com.. They pass an invalid cookie to the hosted UI and receive an error instead of a sign-in prompt. By contrast, a user with a cookie for *.auth.example.com has no issues starting a sign-in session at auth2.example.com.