Setting up and using the Amazon Cognito hosted UI and federation endpoints

An Amazon Cognito user pool with a domain is an OAuth-2.0-compliant authorization server and a ready-to-use hosted user interface (UI) for authentication. The authorization server routes authentication requests, issues and manages JSON web tokens (JWTs), and delivers user attribute information. The hosted UI is a collection of web interfaces for basic sign-up, sign-in, multi-factor authentication and password-reset activities in your user pool. It's also a central hub for authentication with the third-party identity providers (IdPs) that you associate with your app. Your app can invoke the hosted UI and authorization endpoints when you want to authenticate and authorize users. You can make the hosted UI user experience fit your brand with your own logo and CSS customization. For more information about the components of the hosted UI and authorization server, see User pool federation endpoints and hosted UI reference.

Note

The Amazon Cognito hosted UI doesn't support custom authentication with Customizing user pool workflows with Lambda triggers.

Topics

• Setting up the hosted UI with AWS Amplify
• Setting up the hosted UI with the Amazon Cognito console
• Viewing your sign-in page
• Things to know about the Amazon Cognito user pools hosted UI
• Configuring a user pool domain
• Customizing the built-in sign-in and sign-up webpages
• Signing up and signing in with the hosted UI

Setting up the hosted UI with AWS Amplify

If you use AWS Amplify to add authentication to your web or mobile app, you can set up your hosted UI by using the command line interface (CLI) and libraries in the AWS Amplify framework. To add authentication to your app, you use the AWS Amplify CLI to add the Auth category to your project. Then, in your client code, you use the AWS Amplify libraries to authenticate users with your Amazon Cognito user pool.

You can display a pre-built hosted UI, or you can federate users through an OAuth 2.0 endpoint that redirects to a social sign-in provider, such as Facebook, Google, Amazon, or Apple. After a user successfully authenticates with the social provider, AWS Amplify creates a new user in your user pool if needed, and then provides the user's OIDC token to your app.

For more information, see the AWS Amplify framework documentation for your app platform:

• AWS Amplify authentication for JavaScript.

• AWS Amplify authentication for iOS.

• AWS Amplify authentication for Android.

Setting up the hosted UI with the Amazon Cognito console

Create an app client

1. Go to the Amazon Cognito console. If prompted, enter your AWS credentials.

2. Choose User Pools.

3. Choose an existing user pool from the list, or create a user pool.

4. Select the App integration tab.

5. Under App clients, select Create an app client.

6. Select an App type: Public client, Confidential client, or Other. A Public client typically operates from your users' devices and uses unauthenticated and token-authenticated APIs. A Confidential client typically operates from an app on a central server that you trust with client secrets and API credentials, and uses authorization headers and AWS Identity and Access Management credentials to sign requests. If your use case is different from the preconfigured app client settings for a Public client or a Confidential client, select Other.

7. Enter an App client name.

8. Select the Authentication flows you want to allow in your app client.

9. Configure the Authentication flow session duration. This is the amount of time your users have to complete each authentication challenge before their session token expires.

10. (Optional) Configure token expiration.

    1. Specify the Refresh token expiration for the app client. The default value is 30 days. You can change it to any value between 1 hour and 10 years.

    2. Specify the Access token expiration for the app client. The default value is 1 hour. You can change it to any value between 5 minutes and 24 hours.

    3. Specify the ID token expiration for the app client. The default value is 1 hour. You can change it to any value between 5 minutes and 24 hours.

       Important

       If you use the hosted UI and configure a token lifetime of less than an hour, your user will be able to use tokens based on their session cookie duration, which is currently fixed at one hour.

11. Choose Generate client secret to have Amazon Cognito generate a client secret for you. Client secrets are typically associated with confidential clients.

12. Choose whether you will Enable token revocation for this app client. This will increase the size of tokens. For more information, see Revoking Tokens.

13. Choose whether you will Prevent error messages that reveal user existence for this app client. Amazon Cognito will respond to sign-in requests for nonexistent users with a generic message stating that either the user name or password was incorrect.

14. (Optional) Configure Attribute read and write permissions for this app client. Your app client can have permission to read and write a limited subset of your user pool's attribute schema.

15. Choose Create.

16. Note the Client id. This will identify the app client in sign-up and sign-in requests.

Configure the app

1. In the App integration tab, select your app client under App clients. Review your current Hosted UI information.

2. Add a callback URL under Allowed callback URL(s). A callback URL is where the user is redirected to after a successful sign-in.

3. Add a sign-out URL under Allowed sign-out URL(s). A sign-out URL is where your user is redirected to after signing out.

4. Add at least one of the listed options from the list of Identity providers.

5. Under OAuth 2.0 grant types, select Authorization code grant to return an authorization code that is then exchanged for user pool tokens. Because the tokens are never exposed directly to an end user, they are less likely to become compromised. However, a custom application is required on the backend to exchange the authorization code for user pool tokens. For security reasons, we recommend that you use the authorization code grant flow, together with Proof key for code Exchange (PKCE), for mobile apps.

6. Under OAuth 2.0 grant types, select Implicit grant to have user pool JSON web tokens (JWT) returned to you from Amazon Cognito. You can use this flow when there's no backend available to exchange an authorization code for tokens. It's also helpful for debugging tokens.

7. You can enable both the Authorization code and the Implicit code grants, and then use each grant as needed. If neither Authorization code or Implicit code grants are selected and your app client has a client secret, you can enable Client credentials grants. Select Client credentials only if your app needs to request access tokens on its own behalf and not on behalf of a user.

8. Select the OpenID Connect scopes that you want to authorize for this app client.

9. Choose Save changes.

Configure a domain

1. Navigate to the App integration tab for your user pool.

2. Next to Domain, choose Actions and select Create custom domain or Create Cognito domain. If you have already configured a user pool domain, choose Delete Cognito domain or Delete custom domain before creating a new custom domain.

3. Enter an available domain prefix to use with a Cognito domain. For information on setting up a Custom domain, see Using your own Domain for the hosted UI

4. Choose Create.

Viewing your sign-in page

In the Amazon Cognito console, select the View Hosted UI button in the configuration of your app client, under App clients and analytics in the App integration tab. This button takes you to a sign-in page in your hosted UI 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 hosted UI button is useful when you want to test the basic functions of your hosted UI. You can customize your sign-in URL with additional and modified parameters. In most cases, the automatically-generated parameters of the View hosted UI 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 federation endpoints and hosted UI reference.

The hosted UI 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 callback url>

You can retrieve your user pool domain string from the App integration tab. In the same tab, you can identify app client IDs, their callback URLs, their allowed scopes, and other configuration under App clients and analytics.

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. For an example URL that bypasses the hosted UI, see SAML session initiation in Amazon Cognito user pools.

Example hosted UI request for an implicit grant

You can view the hosted UI 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  
        

Things to know about the Amazon Cognito user pools hosted UI

The hosted UI and confirming users as an administrator

For user pool local users, the hosted UI works 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, the hosted UI displays 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 hosted UI configuration

If changes to your hosted UI pages 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.

The hosted UI and CORS policies

The Amazon Cognito hosted UI doesn't support custom cross-origin resource sharing (CORS) origin policies. A CORS policy in the hosted UI would prevent users from passing authentication parameters in their requests. Instead, implement a CORS policy in the web frontend of your app. Amazon Cognito returns an Access-Control-Allow-Origin: * response header to requests to the following OAuth endpoints.

1. Token endpoint

2. Revoke endpoint

3. UserInfo endpoint