User pool 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 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, 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 designer for managed login, and hosted UI (classic) branding for the hosted UI.

The branding designer isn't available in all feature plans for user pools. For more information, see User pool feature plans.

For more information about constructing requests to managed login and hosted UI services, see User pool endpoints and managed login reference.

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://<your domain>/oauth2/authorize?lang=es&response_type=code&client_id=<your app client id>&redirect_uri=<your relying-party url>

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 and have assigned your domain to use managed login branding.

The selection that your user makes in managed login isn't available to custom email or SMS sender triggers. When you implement these triggers, you must use other mechanisms, for example the locale attribute, to determine a user's preferred language.

The following languages are available.

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.

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

The sign-in webpage uses the following URL format. This example requests an authorization code grant with the response_type=code parameter.

https://<your domain>/oauth2/authorize?response_type=code&client_id=<your app client id>&redirect_uri=<your relying-party url>

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.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://mydomain.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 designer. The branding designer 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.

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

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

AWS WAF web ACLs

You can configure your user pool to protect the domain that serves your login pages and authorization server with rules in AWS WAF web ACLs. Currently, the rules that you configure apply to these pages only when you managed login branding version is Hosted UI (classic). For more information, see Things to know about AWS WAF web ACLs and Amazon Cognito.

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.

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:

In iOS, you can block all cookies. 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.

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