Add an app client with the hosted UI
After you create a user pool, you can create an app client for an application that brings up the built-in webpages of the hosted UI. In the hosted UI, users can:
After you create an Amazon Cognito user pool, the next step is to set up an app client. An app client is the user pool settings for one application. That application can authenticate users with the hosted UI, SDK requests to the user pools API, or both. In this case, we'll configure an app client for the hosted UI and OAuth 2.0 authorization server. The hosted UI is a collection of web pages that handle common user authentication flows, such as sign-up, sign-in, password reset, and multi-factor authentication.
When you activate the hosted UI, you also activate an OAuth 2.0 authorization server. The authorization server handles OpenID Connect (OIDC) and OAuth 2.0 authentication flows. Tasks include querying user accounts, issuing tokens, and integrating with external identity providers. The hosted UI and authorization server work best with applications where you want to limit your level of custom UI creation and where your application works best with OIDC identity providers.
The following are some of the capabilities of the hosted UI and authorization server:
Features that are exclusive to hosted UI app clients
-
Request machine-to-machine (M2M) access tokens.
Features that are shared between hosted UI and SDK-based app clients
-
Sign in with or without multi-factor authentication.
-
Allow users to reset their password, confirm new user accounts, and verify email address and phone number attributes.
-
Exchange user access tokens for attribute information. This is also possible in SDK-based applications with GetUser.
To create an app client for hosted UI sign-in
-
Go to the Amazon Cognito console
. If prompted, enter your AWS credentials. -
Choose User Pools.
-
Choose an existing user pool from the list, or create a user pool. If you create a new user pool, you will be prompted to set up an app client and configure the hosted UI during the wizard.
-
Choose the App integration tab for your user pool.
-
Next to Domain, choose Actions, and then select either Create custom domain or Create Amazon Cognito domain. If you have already configured a user pool domain, choose Delete Amazon Cognito domain or Delete custom domain before creating your new custom domain.
-
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 the Hosted UI.
-
Choose Create.
-
Navigate back to the App integration tab for the same user pool and locate App clients. Choose Create an app client.
-
Choose an Application type. Some recommended settings will be provided based on your selection. An app that uses the hosted UI is a Public client.
-
Enter an App client name.
-
For this exercise, choose Don't generate client secret. The client secret is used by confidential apps that authenticate users from a centralized application. In this exercise, you will present a hosted UI sign-in page to your users and will not require a client secret.
-
Choose the Authentication flows that you will allow with your app. Ensure that
USER_SRP_AUTH
has been selected. -
Customize token expiration, Advanced security configuration, and Attribute read and write permissions as needed. For more information, see Configuring App Client Settings.
-
Add a callback URL for your app client. This is where you will be directed after hosted UI authentication. You don't need to add an Allowed sign-out URL until you're able to implement sign-out in your app.
For an iOS or Android app, you can use a callback URL such as
myapp://
. -
Select the Identity providers for the app client. At minimum, enable Amazon Cognito user pool as a provider.
Note
To sign in with external identity providers (IdPs) such as Facebook, Amazon, Google, and Apple, as well as through OpenID Connect (OIDC) or SAML IdPs, first configure them as shown in Adding user pool sign-in through a third party. Then return to the App client settings page to enable them.
-
Choose 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.
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.
Note
You can enable both the Authorization code grant and the Implicit code grant, and then use each grant as needed.
Select Client credentials only if your app needs to request access tokens on its own behalf, not on behalf of a user.
-
Unless you specifically want to exclude one, select all OpenID Connect scopes.
-
Select any Custom scopes that you have configured. Custom scopes are typically used with confidential clients.
-
Choose Create.
To view your sign-in page
From your App client page, select View hosted UI to open a new browser tab to a sign-in page that is pre-populated with the app client ID, scope, grant, and callback URL parameters.
You can view the hosted UI sign-in webpage manually with the following URL. Note the
response_type
. In this case, response_type=code for the authorization code grant.
https://
your_domain
/login?response_type=code&client_id=your_app_client_id
&redirect_uri=your_callback_url
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://
your_domain
/login?response_type=token&client_id=your_app_client_id
&redirect_uri=your_callback_url
You can find the JSON web token (JWT) identity token after the
#idtoken=
parameter in the response.
The following URL is a sample response from an implicit grant request. Your identity token string will be much longer.
https://www.example.com/#id_token=123456789tokens123456789&expires_in=3600&token_type=Bearer
Amazon Cognito user pools tokens are signed using an RS256 algorithm. You can decode and verify
user pool tokens using AWS Lambda. For more information, see Decode and verify Amazon Cognito JWT tokens
Your domain is shown on the Domain name page. Your app client ID and callback URL are shown on the General settings page. If the changes that you made in the console don't appear immediately, wait a few minutes and then refresh your browser.