# User pool managed login Managed login You can choose a web domain to host services for your user pool. An Amazon Cognito user pool gains the following functions when you add a domain, collectively referred to as *managed login*. + An [authorization server](https://datatracker.ietf.org/doc/html/rfc6749#section-1.1) that acts as an identity provider (IdP) to applications that work with OAuth 2.0 and OpenID Connect (OIDC). The authorization server [routes requests](authorization-endpoint.md), [issues and manages JSON web tokens (JWTs)](token-endpoint.md), and [delivers user attribute information](userinfo-endpoint.md). + A ready-to-use user interface (UI) for authentication operations like sign-in, sign-out and password management. The *managed login pages* act as a web front end for authentication services. + A service provider (SP), or relying party (RP), to SAML 2.0 IdPs, OIDC IdPs, Facebook, Login with Amazon, Sign in with Apple, and Google. An additional option that shares some features with managed login is the classic *hosted UI*. The classic hosted UI is a first-generation version of the managed login services. Hosted UI IdP and RP services generally have the same characteristics as managed login, but the login pages have a simpler design and fewer features. For example, passkey sign-in isn't available in the classic hosted UI. In the Lite [feature plan](cognito-sign-in-feature-plans.md), the classic hosted UI is your only option for user pool domain services. The managed login pages are a collection of web interfaces for basic sign-up, sign-in, multi-factor authentication and password-reset activities in your user pool. They also connect users to one or more third-party identity providers (IdPs) when you want to give users a choice of sign-in option. Your app can invoke your managed login pages in users' browsers when you want to authenticate and authorize users. You can make the managed login user experience fit your brand with custom logos, backgrounds and styles. You have two options for the branding that you might apply to your managed login UI: the *branding editor* for managed login, and *hosted UI (classic) branding* for the hosted UI. **Branding editor** An updated user experience with the most up-to-date authentication options and a visual editor in the Amazon Cognito console. **Hosted UI branding** A familiar user experience for previous adopters of Amazon Cognito user pools. Branding for the hosted UI is a file-based system. To apply branding to hosted UI pages, you upload a logo image file and a file that sets values for several predetermined CSS style options. The branding editor isn't available in all feature plans for user pools. For more information, see [User pool feature plans](cognito-sign-in-feature-plans.md). For more information about constructing requests to managed login and hosted UI services, see [User pool endpoints and managed login reference](cognito-userpools-server-contract-reference.md). **Note** Amazon Cognito managed login doesn't support custom authentication with [custom authentication challenge Lambda triggers](user-pool-lambda-challenge.md). **Topics** + [ ## Managed login localization ](#managed-login-localization) + [ ## Terms documents ](#managed-login-terms-documents) + [ ## Setting up managed login with AWS Amplify ](#cognito-user-pools-app-integration-amplify) + [ ## Setting up managed login with the Amazon Cognito console ](#set-up-managed-login) + [ ## Viewing your sign-in page ](#view-login-pages) + [ ## Customizing your authentication pages ](#cognito-user-pools-app-integration-customize-hosted-ui) + [ ## Things to know about managed login and the hosted UI ](#managed-login-things-to-know) + [ # Configuring a user pool domain ](cognito-user-pools-assign-domain.md) + [ # Apply branding to managed login pages ](managed-login-branding.md) ## Managed login localization Managed login defaults to the English language in user-interactive pages. You can display your managed login pages localized for the language of your choice. The available languages are those available in the AWS Management Console. In the link that you distribute to users, add a `lang` query parameter, as shown in the following example. ``` https:///oauth2/authorize?lang=es&response_type=code&client_id=&redirect_uri= ``` Amazon Cognito sets a cookie in users' browser with their language preference after the initial request with a `lang` parameter. After the cookie is set, the language selection persists without displaying or requiring you to include the parameter in requests. For example, after a user makes a sign-in request with a `lang=de` parameter, their managed login pages render in German until they clear their cookies or make a new request with a new localization parameter like `lang=en`. Localization is only available for managed login. You must be on the Essentials or Plus [feature plan](cognito-sign-in-feature-plans.md) and have assigned your domain to use [managed login branding](managed-login-branding.md). The selection that your user makes in managed login isn't available to [custom email or SMS sender triggers](user-pool-lambda-custom-sender-triggers.md). When you implement these triggers, you must use other mechanisms to determine a user's preferred language. In sign-in flows, the `locale` attribute might indicate the user's preferred language based on location. In sign-up flows, the region or app client ID of your user pool might indicate a language preference. The following languages are available. **Managed login languages** | Language | Code | | --- | --- | | German | de | | English | en | | Spanish | es | | French | fr | | Bahasa Indonesia | id | | Italian | it | | Japanese | ja | | Korean | ko | | Portuguese (Brazil) | pt-BR | | Chinese (Simplified) | zh-CN | | Chinese (Traditional) | zh-TW | ## Terms documents You can configure your managed login pages to display links to your **Terms of use** and **Privacy policy** documents when users sign up. When you set up both terms documents in your app client, users see the following text during sign-up: **By signing up, you agree to our Terms of use and Privacy policy.** The phrases **Terms of use** and **Privacy policy** appear in your managed login page, hyperlinked to your documents. Terms documents support language-specific URLs that align with managed login localization. When users select a language with the `lang` query parameter, Amazon Cognito displays links to your terms documents in that language. If you haven't configured a URL for a specific language, Amazon Cognito uses the default URL that you configured for the app client. To configure terms documents for your app client, navigate to the **Managed login** menu in your user pool. Under **Terms documents**, choose **Create terms document**. ------ #### [ Amazon Cognito console ] **To create a terms document** 1. Navigate to your user pool and choose the **Managed login** menu. Locate **Terms documents**. 1. Choose **Create terms document**. 1. Select the app client that you want to assign the terms document to. 1. Enter a **Terms name**. This identifies your document in the console. 1. Under **Links**, choose a **Language** and enter the **URL** where you host your terms document in that language. 1. To add URLs for additional languages, choose **Add another**. 1. Choose **Create**. ------ #### [ Amazon Cognito user pools API ] The following is an example [CreateTerms](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateTerms.html) request body. It causes the sign-up page for app client `1example23456789` to render links for a french-language and a portuguese-language (Brazil) version of the privacy policy when managed login is localized to that language. A separate request is required to set URLs for `terms-of-use` before managed login will render links at the sign-up page. ``` { "ClientId": "1example23456789", "Enforcement": "NONE", "Links": { "cognito:default" : "https://example.com/privacy/", "cognito:french" : "https://example.com/fr/privacy/", "cognito:portuguese-brazil" : "https://example.com/pt/privacy/" }, "TermsName": "privacy-policy", "TermsSource": "LINK", "UserPoolId": "us-east-1_EXAMPLE" } ``` ------ **Note** You must create both a terms of use and a privacy policy document for your app client before Amazon Cognito will display terms documents in your managed login pages. ## Setting up managed login with AWS Amplify If you use AWS Amplify to add authentication to your web or mobile app, you can set up your managed login pages in the Amplify command line interface (CLI) and libraries in the Amplify framework. To add authentication to your app, add the `Auth` category to your project. Then, in your application, authenticate user pool users with Amplify client libraries. You can invoke managed login pages for authentication or you can federate users through an authorization endpoint that redirects to an IdP. After a user successfully authenticates with the provider, Amplify creates a new user in your user pool and passes the user's tokens to your app. The following examples show how to use AWS Amplify to set up managed login with social providers in your app. + [React](https://docs.amplify.aws/react/build-a-backend/auth/concepts/external-identity-providers/) + [Swift](https://docs.amplify.aws/swift/build-a-backend/auth/concepts/external-identity-providers/) + [Flutter](https://docs.amplify.aws/flutter/build-a-backend/auth/concepts/external-identity-providers/) + [Android](https://docs.amplify.aws/android/build-a-backend/auth/concepts/external-identity-providers/) ## Setting up managed login with the Amazon Cognito console The first requirement for managed login and hosted UI is a user pool domain. In the user pools console, navigate to the **Domain** tab of your user pool and add a **Cognito domain** or a **custom domain**. You can also choose a domain during the process of creating a new user pool. For more information, see [Configuring a user pool domain](cognito-user-pools-assign-domain.md). When a domain is active in your user pool, all app clients serve public authentication pages on that domain. When you create or modify a user pool domain, you set the **Branding version** for your domain. This branding version is a choice of **Managed login** or **Hosted UI (classic)**. Your choice of branding version applies to all app clients that use the sign-in services at your domain. The next step is to create an [app client](user-pool-settings-client-apps.md) from the **App clients** tab of your user pool. In the process of creating an app client, Amazon Cognito will ask you for information about your application, then prompt you to select a **Return URL**. The return URL is also called the relying party (RP) URL, the redirect URI, and the callback URL. This is the URL that your application runs from, for example `https://www.example.com` or `myapp://example`. After you configure a domain and app client with a branding style in your user pool, your managed login pages become available on the internet. ## Viewing your sign-in page In the Amazon Cognito console, choose the **View login pages** button in the **Login pages** tab for your app client under the **App clients** menu. This button takes you to a sign-in page in your user pool domain with the following basic parameters. + The app client id + An authorization code grant request + A request for all scopes that you have activated for the current app client + The first callback URL in the list for the current app client The **View login page** button is useful when you want to test the basic functions of your managed login pages. Your login pages will match the **Branding version** that you assigned to your [user pool domain](cognito-user-pools-assign-domain.md). You can customize your sign-in URL with additional and modified parameters. In most cases, the automatically-generated parameters of the **View login page** link don’t fully match the needs of your app. In these cases, you must customize the URL that your app invokes when it signs in your users. For more information about sign-in parameter keys and values, see [User pool endpoints and managed login reference](cognito-userpools-server-contract-reference.md). The sign-in webpage uses the following URL format. This example requests an authorization code grant with the `response_type=code` parameter. ``` https:///oauth2/authorize?response_type=code&client_id=&redirect_uri= ``` You can look up your user pool domain string from the **Domain** menu in your user pool. In the **App clients** menu, you can identify app client IDs, their callback URLs, their allowed scopes, and other configuration. When you navigate to the `/oauth2/authorize` endpoint with your custom parameters, Amazon Cognito either redirects you to the `/oauth2/login` endpoint or, if you have an `identity_provider` or `idp_identifier` parameter, silently redirects you to your IdP sign-in page. **Example request for an implicit grant** You can view your sign-in webpage with the following URL for the implicit code grant where `response_type=token`. After a successful sign-in, Amazon Cognito returns user pool tokens to your web browser's address bar. ``` https://mydomain.auth.us-east-1.amazoncognito.com/authorize?response_type=token&client_id=1example23456789&redirect_uri=https://mydomain.example.com ``` The identity and access tokens appear as parameters appended to your redirect URL. The following is an example response from an implicit grant request. ``` https://auth.example.com/#id_token=eyJraaBcDeF1234567890&access_token=eyJraGhIjKlM1112131415&expires_in=3600&token_type=Bearer ``` ## Customizing your authentication pages In the past, Amazon Cognito only hosted login pages with the classic *hosted UI*, a simple design that grants a universal look to authentication webpages. You could customize Amazon Cognito user pools with a logo image and tweak some styles with a file that specified some CSS style values. Later, Amazon Cognito introduced *managed login*, an updated hosted authentication service. Managed login is an updated look-and-feel with the *branding editor*. The branding editor is a no-code visual editor and a larger suite of options than the hosted UI customization experience. Managed login also introduced custom background images and a dark mode theme. You can switch between the managed login and hosted UI branding experiences in user pools. To learn more about customizing your managed login pages, see [Apply branding to managed login pages](managed-login-branding.md). ## Things to know about managed login and the hosted UI **The one-hour managed login and hosted UI session cookie** When a user signs in with your login pages or a third-party provider, Amazon Cognito sets a cookie in their browser. With this cookie, users can sign in again with the same authentication method for one hour. When they sign in with their browser cookie, they get fresh tokens that last the duration specified in your app client configuration. Changes to user attributes or authentication factors have no effect on their ability to sign in again with their browser cookie. Authentication with the session cookie doesn't reset the cookie duration to an additional hour. Users must sign in again if they attempt to access your sign-in pages more than an hour after their most recent successful interactive authentication. **Confirming user accounts and verifying user attributes** For user pool [local users](cognito-terms.md#terms-localuser), managed login and the hosted UI work best when you configure your user pool to **Allow Cognito to automatically send messages to verify and confirm**. When you enable this setting, Amazon Cognito sends a message with a confirmation code to users who sign up. When you instead confirm users as a user pool administrator, your login pages display an error message after sign-up. In this state, Amazon Cognito has created the new user, but hasn't been able to send a verification message. You can still confirm users as an administrator, but they might contact your support desk after they encounter an error. For more information about administrative confirmation, see [Allowing users to sign up in your app but confirming them as a user pool administrator](signing-up-users-in-your-app.md#signing-up-users-in-your-app-and-confirming-them-as-admin). **Managed login scope of operations** Managed login and the classic hosted UI support sign-up, sign-in, and password management. This includes completing sign-in with multi-factor authentication (MFA) and registration of webAuthn authenticators. Managed login doesn't support user self-service profile management like attribute changes and setting of MFA preference. You must implement profile management in your own application code. Managed login also doesn't provide the capacity to confirm attribute changes when you update email addresses and phone numbers as an administrator with the [AdminUpdateUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateUserAttributes.html) API operation. **Viewing your changes to configuration** If you make style changes to your pages and they do not immediately appear, wait a few minutes and then refresh the page. **Decoding user pool tokens** Amazon Cognito user pool tokens are signed using an RS256 algorithm. You can decode and verify user pool tokens using AWS Lambda. See [Decode and verify Amazon Cognito JWT tokens](https://github.com/awslabs/aws-support-tools/tree/master/Cognito/decode-verify-jwt) on GitHub. **TLS version** Managed login and hosted UI pages require encryption in transit. User pool domains that are provided by Amazon Cognito require that users' browsers negotiate a minimum TLS version of 1.2. Custom domains support browser connections with TLS version 1.2. The hosted UI (classic) **doesn't require** TLS 1.2 for custom domains, but the newer managed login **requires** TLS version 1.2 both for custom and prefix domains. Because Amazon Cognito manages the configuration of your domain services, you can't modify the TLS requirements of your user pool domain. **CORS policies** Neither managed login nor the hosted UI support custom cross-origin resource sharing (CORS) origin policies. A CORS policy would prevent users from passing authentication parameters in their requests. Instead, implement a CORS policy in your application front end. Amazon Cognito returns an `Access-Control-Allow-Origin: *` response header to requests to the following endpoints. 1. [Token endpoint](token-endpoint.md) 1. [Revoke endpoint](revocation-endpoint.md) 1. [userInfo endpoint](userinfo-endpoint.md) **Cookies** Managed login and the hosted UI set cookies in users' browsers. The cookies conform to the requirements of some browsers that sites not set third-party cookies. They are scoped only to your user pool endpoints and include the following: + An `XSRF-TOKEN` cookie for each request. + A `csrf-state` cookie for session consistency when a user is redirected. + A `csrf-state-legacy` cookie for session consistency, read by Amazon Cognito as a fallback when your browser doesn't have support for the `SameSite` attribute. + A `cognito` session cookie that preserves successful sign-in attempts for an hour. + A `lang` cookie that preserves a user's choice of [language localization](#managed-login-localization) in managed login. + A `page-data` cookie that persists required data as a user navigates between managed login pages. In iOS, you can [block all cookies](https://support.apple.com/en-us/105082). This setting isn't compatible with managed login or the hosted UI. To work with users who might enable this setting, build user pool authentication into a native iOS app with an AWS SDK. In this scenario, you can build your own session storage that isn't cookie-based. **Effects of managed login version change** Consider the following effects of adding domains and setting the managed login version. + When you add a prefix domain, either with managed login or hosted UI (classic) branding, it can take up to 60 seconds before your login pages are available. + When you add a custom domain, either with managed login or hosted UI (classic) branding, it can take up to five minutes before your login pages are available. + When you change the branding version for your domain, it can take up to four minutes before your login pages are available in the new branding version. + When you switch between managed login and hosted UI (classic) branding, Amazon Cognito doesn't maintain user sessions. They must sign in again with the new interface. **Default style** When you create an app client in the AWS Management Console, Amazon Cognito automatically assigns a branding style to your app client. When you programmatically create an app client with the [CreateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html) operation, no branding style is created. Managed login isn't available for an app client created with an AWS SDK until you create one with a [CreateManagedLoginBranding](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateManagedLoginBranding.html) request. **Managed login authentication prompt times out** Amazon Cognito cancels authentication requests that do not complete within five minutes, and redirects the user to managed login. The page displays a `Something went wrong` error message. # 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. ------ # Apply branding to managed login pages Branding and customization You might want to provide a consistent user experience between your authentication service and your application. You can accomplish this goal either with custom forms and back-end API operations in an AWS SDK, or with managed login. Managed login and the classic hosted UI are web front ends for the component of your application that serves authentication with user pools. To synchronize your managed authentication services with your application UX, you have two customization options: the branding editor and hosted UI branding. You can choose your preferred experience in the Amazon Cognito console and with user pool API operations. **The branding editor** The [branding editor](managed-login-brandingeditor.md) is the newest customization option for the newest user pools UI experience, [managed login](cognito-user-pools-managed-login.md). The branding editor is a no-code visual editor for managed login assets and style, and a set of API operations for programmatic configuration of a large number of configuration options. User pools that you configure with a [domain](cognito-user-pools-assign-domain.md) and managed login automatically render the branding-designer version of your login pages. **Hosted UI (classic) branding** The [hosted UI (classic) branding experience](hosted-ui-classic-branding.md) has two options: to modify a cascading stylesheets (CSS) file with a fixed set of style options, and to add a custom logo image. You can set these options in the Amazon Cognito console or with the [SetUICustomization](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetUICustomization.html) API operation. At the time that the service launched, Amazon Cognito had only this option. User pools that you configure with a [domain](cognito-user-pools-assign-domain.md) and the hosted UI branding version automatically render the classic version of your login pages. Your [feature plan](cognito-sign-in-feature-plans.md) might also support only the hosted UI. **Note** The branding editor and the classic branding experience modify the visual properties of your hosted authentication service. Currently, you can't modify the text that's displayed on your managed login pages, except to apply localization into one of several languages. For more information about localization, see [Managed login localization](cognito-user-pools-managed-login.md#managed-login-localization). ## Choose a branding experience and assign styles In the Amazon Cognito console, new user pools default to the **Managed login** branding experience. User pools that you set up before managed login was available will have **Hosted UI (classic)** branding. You can switch between managed login and hosted UI branding. When you change your **Branding version**, Amazon Cognito immediately applies the change to the user-interactive pages of your user pool domain. With managed login and the hosted UI, your user pool can have a style for each app client. Each app client can have a distinct branding *style*, but a user pool domain serves either managed login or the hosted UI. A style is the set of customization settings applied to an app client. You can set up one [custom domain](cognito-user-pools-add-custom-domain.md) and one [prefix domain](cognito-user-pools-assign-domain-prefix.md) per user pool. You can assign different branding versions to your custom and prefix domains. However, a prefix domain isn't fully functional when you also have a custom domain—the `.well-known` OIDC discovery endpoints *only* present custom-domain paths. You can only use the prefix domain for operations that don't require endpoint discovery (`openid-configuration`) in a user pool with this configuration. Because of these properties of user pools, you can effectively choose one branding version per user pool. You can assign styles to the app clients in a user pool where a domain is set to the managed login branding version. Styles are a set of visual settings made up of image files, display options, CSS values. When you assign a style to an app client, Amazon Cognito immediately pushes your updates to your user-interactive login pages. Amazon Cognito renders your user-interactive pages with your chosen branding version and the customization that you have applied to it. ### Update and delete styles When you create a style, you link it to an app client. To change a style assignment for an app client, you must first delete the original style. Currently, you can't copy settings between styles. You must do this programmatically. To replicate settings between styles and app clients, get the settings for a style with the [DescribeManagedLoginBranding](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeManagedLoginBranding.html) API operation and apply them with [CreateManagedLoginBranding](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateManagedLoginBranding.html) or [UpdateManagedLoginBranding](https://docs.aws.amazon.com/). You can't change the assigned styles of an app client—you can only delete the original and set a new one. For more information about managing styles with API and SDK operations, see [API and SDK operations for managed login branding](managed-login-brandingeditor.md#branding-designer-api). **Note** Programmatic requests that create or update branding style must have a request size of no more than 2 MB. If your request is larger than this limit, break your request up into multiple `UpdateManagedLoginBranding` requests for groups of parameters that don't exceed the maximum request size. These requests don't result in unspecified parameters being set to default, so you can send partial requests without any effect on existing settings. You delete a style in the Amazon Cognito console from the **Managed login** menu. Under **Styles**, choose the style that you want to delete and choose **Delete style**. At a high level, the process of assigning branding to a domain consists of the following steps. 1. [Create a domain and set the branding version](cognito-user-pools-assign-domain.md). 1. Create a branding style and assign it to an app client. **To assign a style to an app client** 1. In the **Domain** menu of your user pool, create a domain and set the **Branding version** to **Managed login**. 1. Navigate to the **Managed login** menu. Under **Styles**, choose **Create a style**. 1. Choose the app client that you want to assign your style to, or create a new [app client](user-pool-settings-client-apps.md). 1. To start configuring your branding settings, choose **Launch branding editor**. **Topics** + [ ## Choose a branding experience and assign styles ](#managed-login-branding-choose) + [ # The branding editor and customizing managed login ](managed-login-brandingeditor.md) + [ # Customizing hosted UI (classic) branding ](hosted-ui-classic-branding.md) # The branding editor and customizing managed login Managed login branding The branding editor is a visual design and editing tool for your managed login webpages. It's built in to the Amazon Cognito console. In the branding editor, you start with a preview of your login pages and can proceed into a quick-setup option or a detailed view with advanced options. You can modify and preview style parameters or add a custom background image and logo. You can configure light mode and dark mode. ![\[A preview of the branding editor visual editor for Amazon Cognito user pools.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/hosted-ui-customization-editor-preview.png) To begin, create a style that you can apply to your user pool or an app client. **To get started with the branding editor** 1. [Create a domain](cognito-user-pools-assign-domain.md) from the **Domain** tab, or update your existing domain. Under **Branding version**, set your domain to use **Managed login**. 1. Delete the existing app client style, if any. 1. In the **App clients** menu, select your app client. 1. Under **Managed login style**, select the syle assigned to your app client. 1. Choose **Delete style**. Confirm your selection. 1. Navigate to the **Managed login** menu in your user pool. If you haven't already, follow the prompt to select a [feature plan](cognito-sign-in-feature-plans.md) that includes managed login. You can also select **Preview this feature** if you want to check out the branding editor without making changes. 1. Under **Styles**, choose **Create a style**. 1. Choose the app client that you want to assign your style to and select **Create**. You can also create a new app client. 1. The Amazon Cognito console launches the branding editor. 1. Choose a tab where you want to start editing, or select **Launch editor** and enter [quick setup](#branding-designer-quick-setup). The following tabs are available: **Preview** See how your current selections look in your managed login pages. **Foundation** Set an overall theme, configure links to external identity providers, and style form fields. **Components** Configure styles for headers, footers, and individual UI elements. 1. To make choices about initial settings, enter quick setup. Select **Change settings category** and choose **Quick setup**. When you select **Proceed**, the branding editor launches with a set of basic options for you to configure. ## Text and localization You can't modify or localize text in the branding editor. Instead, add a `lang` query parameter to the URL that you distribute to users. This parameters causes your managed login pages to be localized into one of several available languages. For more information, see [Managed login localization](cognito-user-pools-managed-login.md#managed-login-localization). ## Quick setup The **Launch branding editor** button loads a visual editor for your managed login configuration where you can select from a variety of primary customization options. As you make selections, Amazon Cognito renders your managed login changes in a preview window. To return to the detailed settings menu, select the **Change settings category** button. **What should be the overall look and feel?** Configure basic theme settings for managed login. **Display mode** Choose a light-mode, dark-mode, or adaptive experience for your managed login. The adaptive settings defers to the user's browser preference when Amazon Cognito renders managed login. When you choose a browser-adaptive mode, you can choose different colors and logo images for light and dark mode. **Spacing** Set the default spacing between elements in the page. **Border radius** Set the rounding depth of the outer border of elements. **How should the page background look?** **Background type** The **Show image** checkbox indicates whether you want a background image or to set a solid background color. 1. To use an image, select **Show image** and choose a background image for light and dark modes. You can also set a dark-mode and light-mode **Page background color** for areas of the background that aren't covered by the image. 1. To use only a color for the background, deselect **Show image** and choose a light-mode and dark-mode **Page background color**. **How should forms look?** Configure settings for the form elements of managed login. Examples of form items are login and code prompts. **Horizontal alignment** Set the horizontal alignment of form fields. **Form logo** Set the positioning of your logo image. **Logo image** Choose a logo image file to include in the form element for light and dark modes. To upload an image, select the **Logo image** dropdown, choose **Add new asset**, and add a logo file. **Primary branding color** Set a theme color for light and dark modes. This color will be applied as the background color to all elements classified as primary. **How should headers look?** Choose whether you want to include a header in your managed login pages. The header can contain a logo image. **Header logo** Set the position of the logo image in your header. **Logo image** Choose a logo position and a logo image file to include in the header. To upload an image, select the **Logo image** dropdown, choose **Add new asset**, and add a logo file. **Header background color** Set the light and dark mode colors for the background of the header. ## Detailed settings In the detailed settings view, you can modify individual components in the **Foundation** and **Components**. The **Preview** tab displays a preview of managed login in the current context with your customizations. ![\[An AWS Management Console screenshot of detailed configuration of managed login components.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/hosted-ui-customization-console-preview.png) To enter the visual editor for a component, choose the edit icon in the tile for the component. From the theme studio editor, you can switch between components with the **Change setting category** button. ### Foundation **App style** Configure the basics of your managed login configuration. This category has settings for the overall theme, text spacing, and the page header and footer. **Display mode** Choose a light-mode, dark-mode, or adaptive experience for your managed login pages. When you choose a browser-adaptive mode, you can choose different colors and logo images for light and dark mode. **Spacing** Set the default spacing between elements in the page. **Authentication behavior** Configure styles for the buttons that connect your users to external identity providers (IdPs). This section includes the option **Domain search input** to have managed login prompt users for an email address and match them with their [SAML identity provider identifier](cognito-user-pools-managing-saml-idp-naming.md). **Form behavior** Configure styles for input forms: the positioning of inputs, colors, and alignment of elements. ### Components **Buttons** Styles for buttons that Amazon Cognito renders on managed login pages. **Divider** Styles for divider lines and boundaries between managed login elements like the input form and the external-provider sign-in selector. **Dropdown** Styles for dropdown menus. **Favicon** Styles for the image that Amazon Cognito provides for the tab and bookmark icon. **Focus rings** Styles for the highlights that indicate a currently-selected input. **Form container** Styles for the elements that bound a form. **Global footer** Styles for the footer that Amazon Cognito displays at the bottom of managed login pages. **Global header** Styles for the header that Amazon Cognito displays at the top of managed login pages. **Indications** Styles for error and success messages. **Option controls** Styles for checkboxes, multi-selects, and other input prompts. **Page background** Styles for the overall background of managed login. **Inputs** Styles for form-field input prompts. **Link** Styles for hyperlinks in managed login pages. **Text for page** Styles for in-page text. **Text for field** Styles for the text around form inputs. ## API and SDK operations for managed login branding API operations You can also apply branding to a managed login style with the API operations [CreateManagedLoginBranding](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateManagedLoginBranding.html) and [UpdateManagedLoginBranding](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateManagedLoginBranding.html). These operations are ideal for creating identical or slightly-modified versions of a branding style for another app client or user pool. Query the managed login branding of an existing style with the API operation [DescribeManagedLoginBranding](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeManagedLoginBranding.html), then modify the output as needed and apply it to another resource. The `UpdateManagedLoginBranding` operation doesn't change the app client that your style is applied to. It only updates the existing style that's assigned to an app client. To completely replace the style for an app client, delete the existing style with [DeleteManagedLoginBranding](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DeleteManagedLoginBranding.html) and assign a new style with `CreateManagedLoginBranding`. In the Amazon Cognito console, the same is true: you must delete the existing style and create a new one. Setting up managed login branding in an API or SDK request requires that your settings be embedded in a JSON file that's converted to a `Document` datatype. The following is guidance for images that you can add and for generating programmatic requests to configure a branding style. ### Image assets [CreateManagedLoginBranding](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateManagedLoginBranding.html) and [UpdateManagedLoginBranding](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateManagedLoginBranding.html) include an `Assets` parameter. This parameter is an array of image files in base64-encoded binary format. **Note** Programmatic requests that create or update branding style must have a request size of no more than 2 MB. The assets in your request might make it exceed this limit. If this is the case, break your request up into multiple `UpdateManagedLoginBranding` requests for groups of parameters that don't exceed the maximum request size. These requests don't result in unspecified parameters being set to default, so you can send partial requests without any effect on existing settings. Some assets have limitations on the filetypes that you can submit. **** | Asset | Accepted file extensions | | --- | --- | | FAVICON\$1ICO | ico | | FAVICON\$1SVG | svg | | EMAIL\$1GRAPHIC | png, svg, jpeg | | SMS\$1GRAPHIC | png, svg, jpeg | | AUTH\$1APP\$1GRAPHIC | png, svg, jpeg | | PASSWORD\$1GRAPHIC | png, svg, jpeg | | PASSKEY\$1GRAPHIC | png, svg, jpeg | | PAGE\$1HEADER\$1LOGO | png, svg, jpeg | | PAGE\$1HEADER\$1BACKGROUND | png, svg, jpeg | | PAGE\$1FOOTER\$1LOGO | png, svg, jpeg | | PAGE\$1FOOTER\$1BACKGROUND | png, svg, jpeg | | PAGE\$1BACKGROUND | png, svg, jpeg | | FORM\$1BACKGROUND | png, svg, jpeg | | FORM\$1LOGO | png, svg, jpeg | | IDP\$1BUTTON\$1ICON | ico, svg | Files of the SVG type support the following attributes and elements. ------ #### [ Attributes ] ``` accent-height, accumulate, additivive, alignment-baseline, ascent, attributename, attributetype, azimuth, basefrequency, baseline-shift, begin, bias, by, class, clip, clip-path, clip-rule, color, color-interpolation, color-interpolation-filters, color-profile, color-rendering, cx, cy, d, dx, dy, diffuseconstant, direction, display, divisor, dur, edgemode, elevation, end, fill, fill-opacity, fill-rule, filter, filterunits, flood-color, flood-opacity, font-family, font-size, font-size-adjust, font-stretch, font-style, font-variant, font-weight, fx, fy, g1, g2, glyph-name, glyphref, gradientunits, gradienttransform, height, href, id, image-rendering, in, in2, k, k1, k2, k3, k4, kerning, keypoints, keysplines, keytimes, lang, lengthadjust, letter-spacing, kernelmatrix, kernelunitlength, lighting-color, local, marker-end, marker-mid, marker-start, markerheight, markerunits, markerwidth, maskcontentunits, maskunits, max, mask, media, method, mode, min, name, numoctaves, offset, operator, opacity, order, orient, orientation, origin, overflow, paint-order, path, pathlength, patterncontentunits, patterntransform, patternunits, points, preservealpha, preserveaspectratio, r, rx, ry, radius, refx, refy, repeatcount, repeatdur, restart, result, rotate, scale, seed, shape-rendering, specularconstant, specularexponent, spreadmethod, stddeviation, stitchtiles, stop-color, stop-opacity, stroke-dasharray, stroke-dashoffset, stroke-linecap, stroke-linejoin, stroke-miterlimit, stroke-opacity, stroke, stroke-width, style, surfacescale, tabindex, targetx, targety, transform, text-anchor, text-decoration, text-rendering, textlength, type, u1, u2, unicode, values, viewbox, visibility, vert-adv-y, vert-origin-x, vert-origin-y, width, word-spacing, wrap, writing-mode, xchannelselector, ychannelselector, x, x1, x2, xmlns, y, y1, y2, z, zoomandpan ``` ------ #### [ Elements ] ``` svg, a, altglyph, altglyphdef, altglyphitem, animatecolor, animatemotion, animatetransform, audio, canvas, circle, clippath, defs, desc, ellipse, filter, font, g, glyph, glyphref, hkern, image, line, lineargradient, marker, mask, metadata, mpath, path, pattern, polygon, polyline, radialgradient, rect, stop, style, switch, symbol, text, textpath, title, tref, tspan, video, view, vkern, feBlend, feColorMatrix, feComponentTransfer, feComposite, feConvolveMatrix, feDiffuseLighting, feDisplacementMap, feDistantLight, feFlood, feFuncA, feFuncB, feFuncG, feFuncR, feGaussianBlur, feMerge, feMergeNode, feMorphology, feOffset, fePointLight, feSpecularLighting, feSpotLight, feTile, feTurbulence ``` ------ ### Tools for managed login branding operations Amazon Cognito manages a file in the [JSON-Schema format](https://json-schema.org/docs) for the managed-login branding settings object. The following is how to programmatically update your branding style. **To update branding in the user pools API** 1. In the Amazon Cognito console, create a default managed login branding style from the **Managed login** menu of your user pool. Assign it to an app client. 1. Record the ID of the app client that you created the style for, for example `1example23456789`. 1. Retrieve the settings for the branding style with a [DescribeManagedLoginBrandingByClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeManagedLoginBrandingByClient.html) API request with `ReturnMergedResources` set to `true`. The following is an example request body. ``` { "ClientId": "1example23456789", "ReturnMergedResources": true, "UserPoolId": "us-east-1_EXAMPLE" } ``` 1. Modify the output of `DescribeManagedLoginBrandingByClient` with your customizations. 1. The response body is wrapped in a `ManagedLoginBranding` element that isn't part of the syntax for create and update operations. Remove this top level of the JSON object. 1. To replace images, replace the `Bytes` value with the Base64-encoded binary data of each image file. 1. To update settings, modify the output of the `Settings` object and include it in your next request. Amazon Cognito ignores any values in your `Settings` object that aren't in the schema that you receive in your API response. 1. Use the updated response body in a [CreateManagedLoginBranding](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateManagedLoginBranding.html) or [UpdateManagedLoginBranding](https://docs.aws.amazon.com/) request. If this request exceeds 2 MB in size, separate it out into multiple requests. These operations work in a `PATCH` model where original settings remain unchanged unless you specify otherwise. # Customizing hosted UI (classic) branding Hosted UI (classic) branding You can use the AWS Management Console, or the AWS CLI or API, to specify classic customization settings for the hosted UI. You can upload a custom logo image to be displayed in the app. You can also apply some cascading style sheets (CSS) options to the look and feel of the UI. You can customize the UI defaults and override individual [app clients](cognito-terms.md#term-appclient) with specific settings. Amazon Cognito applies the default configuration to every app client that doesn't have client-level settings. In the Amazon Cognito console and in API requests, the request that sets your UI customization must not exceed 135 KB in size. In rare cases, the sum of request headers, your CSS file, and your logo might exceed 135KB. Amazon Cognito encodes the image file to Base64. This increases the size of a 100 KB image to 130 KB, keeping five KB for request headers and your CSS. If the request is too large, the AWS Management Console or your `SetUICustomization` API request returns a `request parameters too large` error. Adjust your logo image to be no greater than 100KB and your CSS file to be no larger than 3 KB. You can't set CSS and logo customization separately. **Note** To customize your UI, you must set up a domain for your user pool. ## Specifying a custom logo in classic branding Amazon Cognito centers your custom logo above the input fields at the [Login endpoint](login-endpoint.md). Choose a PNG, JPG, or JPEG file that can scale to 350 by 178 pixels for your custom hosted UI logo. Your logo file can be no larger than 100 KB in size, or 130 KB after Amazon Cognito encodes to Base64. To set an `ImageFile` in [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetUICustomization.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetUICustomization.html) in the API, convert your file to a Base64-encoded text string or, in the AWS CLI, provide a file path and let Amazon Cognito encode it for you. ## Specifying CSS customizations in classic branding You can customize the CSS for the hosted app pages, with the following restrictions: + You can use any of the following CSS class names: + `background-customizable` + `banner-customizable` + `errorMessage-customizable` + `idpButton-customizable` + `idpButton-customizable:hover` + `idpDescription-customizable` + `inputField-customizable` + `inputField-customizable:focus` + `label-customizable` + `legalText-customizable` + `logo-customizable` + `passwordCheck-valid-customizable` + `passwordCheck-notValid-customizable` + `redirect-customizable` + `socialButton-customizable` + `submitButton-customizable` + `submitButton-customizable:hover` + `textDescription-customizable` + Property values can contain HTML, except for the following values: `@import`, `@supports`, `@page`, or `@media` statements, or Javascript. You can customize the following CSS properties. **Labels** + **font-weight** is a multiple of 100 from 100 to 900. + **color** is the text color. Must be a [legal CSS color value](https://www.w3schools.com/cssref/css_colors_legal.php). **Input fields** + **width** is the width of the containing block as a percentage. + **height** is the height of the input field in pixels (px). + **color** is the text color. It can be any standard CSS color value. + **background-color** is the background color of the input field. It can be any standard CSS color value. + **border** is a standard CSS border value that specifies the width, transparency, and color of the border of your app window. Width can be any value from 1px to 100px. Transparency can be solid or none. Color can be any standard color value. **Text descriptions** + **padding-top** is the amount of padding above the text description. + **padding-bottom** is the amount of padding below the text description. + **display** can be `block` or `inline`. + **font-size** is the font size for text descriptions. + **color** is the text color. Must be a [legal CSS color value](https://www.w3schools.com/cssref/css_colors_legal.php). **Submit button** + **font-size** is the font size of the button text. + **font-weight** is the font weight of the button text: `bold`, `italic`, or `normal`. + **margin** is a string of four values indicating the top, right, bottom, and left margin sizes for the button. + **font-size** is the font size for text descriptions. + **width** is the width of the button text in percent of the containing block. + **height** is the height of the button in pixels (px). + **color** is the button text color. It can be any standard CSS color value. + **background-color** is the background color of the button. It can be any standard color value. **Banner** + **padding** is a string of four values indicating the top, right, bottom, and left padding sizes for the banner. + **background-color** is the banner's background color. It can be any standard CSS color value. **Submit button hover** + **color** is the foreground color of the button when you hover over it. It can be any standard CSS color value. + **background-color** is the background color of the button when you hover over it. It can be any standard CSS color value. **Identity provider button hover** + **color** is the foreground color of the button when you hover over it. It can be any standard CSS color value. + **background-color** is the background color of the button when you hover over it. It can be any standard CSS color value. **Password check not valid** + **color** is the text color of the `"Password check not valid"` message. It can be any standard CSS color value. **Background** + **background-color** is the background color of the app window. It can be any standard CSS color value. **Error messages** + **margin** is a string of four values indicating the top, right, bottom, and left margin sizes. + **padding** is the padding size. + **font-size** is the font size. + **width** is the width of the error message as a percentage of the containing block. + **background** is the background color of the error message. It can be any standard CSS color value. + **border** is a string of three values specifying the width, transparency, and color of the border. + **color** is the error message text color. It can be any standard CSS color value. + **box-sizing** is used to indicate to the browser what the sizing properties (width and height) should include. **Identity provider buttons** + **height** is the height of the button in pixels (px). + **width** is the width of the button text as a percentage of the containing block. + **text-align** is the text alignment setting. It can be `left`, `right`, or `center`. + **margin-bottom** is the bottom margin setting. + **color** is the button text color. It can be any standard CSS color value. + **background-color** is the background color of the button. It can be any standard CSS color value. + **border-color** is the color of the button border. It can be any standard CSS color value. **Identity provider descriptions** + **padding-top** is the amount of padding above the description. + **padding-bottom** is the amount of padding below the description. + **display** can be `block` or `inline`. + **font-size** is the font size for descriptions. + **color** is the text color for IdP section headers for example **Sign in with your corporate ID**. Must be a [legal CSS color value](https://www.w3schools.com/cssref/css_colors_legal.php). **Legal text** + **color** is the text color. It can be any standard CSS color value. + **font-size** is the font size. When you customize **Legal text**, you are customizing the message **We won't post to any of your accounts without asking first** that is displayed under social identity providers in the sign-in page. **Logo** + **max-width** is the maximum width as a percentage of the containing block. + **max-height** is the maximum height as a percentage of the containing block. + **background-color** is the color of the background for logs with transparent sections. Must be a [legal CSS color value](https://www.w3schools.com/cssref/css_colors_legal.php). **Input field focus** + **border-color** is the color of the input field. It can be any standard CSS color value. + **outline** is the border width of the input field, in pixels. **Social button** + **height** is the height of the button in pixels (px). + **text-align** is the text alignment setting. It can be `left`, `right`, or `center`. + **width** is the width of the button text as a percentage of the containing block. + **margin-bottom** is the bottom margin setting. **Password check valid** + **color** is the text color of the `"Password check valid"` message. It can be any standard CSS color value. ## Customizing the hosted UI with classic branding in the AWS Management Console You can use the AWS Management Console to specify UI customization settings for your app. **Note** You can view the hosted UI with your customizations by constructing the following URL, with the specifics for your user pool, and typing it into a browser: ` https:///login?response_type=code&client_id=&redirect_uri=` You may have to wait up to one minute to refresh your browser before changes made in the console appear. Your domain is shown on the **App integration** tab under **Domain**. Your app client ID and callback URL are shown under **App clients**. **To specify app UI customization settings** 1. Sign in to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). 1. In the navigation pane, choose **User Pools**, and choose the user pool you want to edit. 1. [Create a domain](cognito-user-pools-assign-domain.md) from the **Domain** tab, or update your existing domain. Under **Branding version**, set your domain to use **Hosted UI (classic)**. 1. Choose the **Managed login** menu. 1. To customize UI settings for all app clients, locate **Style** under **Hosted UI settings** and select **Edit**. 1. To customize UI settings for one app client, go to the **App clients** menu and select the app client you want to modify, then locate **Hosted UI (classic) style** and select **Override**. Select **Edit**. 1. To upload your own logo image file, choose **Choose file** or **Replace current file**. 1. To customize hosted UI CSS, download **CSS template.css** and modify the template with the values you want to customize. Only the keys that are included in the template can be used with the hosted UI. Added CSS keys will not be reflected in your UI. After you have customized the CSS file, choose **Choose file** or **Replace current file** to upload your custom CSS file. ## Customizing the hosted UI with classic branding in the user pools API and with the AWS CLI Use the following commands to specify app UI customization settings for your user pool. **To get the UI customization settings for a user pool's built-in app UI, use the following API operations.** + AWS CLI: `aws cognito-idp get-ui-customization` + AWS API: [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUICustomization.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUICustomization.html) **To set the UI customization settings for a user pool's built-in app UI, use the following API operations.** + AWS CLI from image file: `aws cognito-idp set-ui-customization --user-pool-id --client-id --image-file fileb://"" --css ".label-customizable{ color: ;}"` + AWS CLI with image encoded as Base64 binary text: `aws cognito-idp set-ui-customization --user-pool-id --client-id --image-file --css ".label-customizable{ color: ;}"` + AWS API: [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetUICustomization.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetUICustomization.html)