Hosted UI

You are currently viewing the AWS SDK for Mobile documentation which is a collection of low-level libraries. Use the Amplify libraries for all new app development. Learn more

Amazon Cognito Hosted UI

Amazon Cognito provides a customizable user experience via the Hosted UI. The Hosted UI is an OAuth 2.0 flow that allows you to launch a login screen without embedding an SDK for Cognito or a social provider into your application. The Hosted UI allows end-users to sign-in directly to your user pool through Facebook, Amazon, and Google, as well as through OpenID Connect (OIDC) and SAML identity providers. To learn more about Amazon Cognito Hosted UI, please visit Amazon Cognito Developer Guide.

You need to configure your identity providers(Google, Facebook or Login with Amazon) which you would like to use.

Setup Your Auth Provider

  1. Create a developer account with Facebook.

  2. Sign In with your Facebook credentials.

  3. Choose My Apps from the top navigation bar, and on the page that loads choose Create App. Create App button in the My Apps page of the Facebook developer account.

  4. For your use case, choose Set up Facebook Login. Set up Facebook Login option selected from list.

  5. For platform, choose Website and select No, I'm not building a game.

  6. Give your Facebook app a name and choose Create app. Form fields for the Facebook create app form.

  7. On the left navigation bar, choose Settings and then Basic. App ID and App Secret in the basic settings tab of the dashboard.

  8. Note the App ID and the App Secret. You will use them in the next section during the CLI flow.

  1. Go to Google developer console.

  2. Click Select a project Select a project button on the nav bar is circled.

  3. Click NEW PROJECT The new project button is circled on the select a project popup.

  4. Type in project name and click CREATE The create button is circled in the new project page.

  5. Once the project is created, from the left Navigation menu, select APIs & Services, then select Credentials The top left menu icon is selected, then the APIs and services option, then the credentials option.

  6. Click CONFIGURE CONSENT SCREEN The configure consent screen button is circled in the oauth consent screen section.

  7. Click CREATE The create button is circled in the OAuth consent screen section.

  8. Type in App Information and Developer contact information which are required field and click SAVE AND CONTINUE three times (OAuth consent screen -> Scopes -> Test Users) to finish setting up consent screen

  9. Back to Credentials tab, Create your OAuth2.0 credentials by choosing OAuth client ID from the Create credentials drop-down list. The Create credentials button is circled, then the oauth client ID button is circled in the credentials section..

  10. Choose Web application as Application type and name your OAuth Client.

  11. Click Create.

  12. Take note of Your client ID and Your Client Secret. You will need them for the next section in the CLI flow.

  13. Choose OK.

  1. Create a developer account with Amazon.
  2. Sign in with your Amazon credentials.
  3. You need to create an Amazon security profile to receive the Amazon client ID and client secret. Choose Create a Security Profile. The login with Amazon console with a create a new security profile button displayed.
  4. Type in a Security Profile Name, a Security Profile Description, and a Consent Privacy Notice URL. Security profile management page with steps to fill out a form for the new security profile.
  5. Choose Save.
  6. Choose Client ID and Client Secret to show the client ID and secret. You will need them for the next section in the CLI flow. Choosing client id and client secret.
  1. Sign In with your Apple developer credentials.
  2. On the main developer portal page, select Certificates, IDs, & Profiles.
  3. On the left navigation bar, select Identifier.
  4. On the Identifiers page, select the + icon.
  5. On the Register a New Identifier page, select App IDs.
  6. On the Register an App ID page, under App ID Prefix, take note of the Team ID value.
  7. Provide a description in the Description text box and provide the bundleID of the iOS app. Register an App ID in the certificates, identifiers and profiles section.
  8. Under Capabilities, select Sign in with Apple.
  9. Select Continue, review the configuration, and then select Register.
  10. On the Identifiers page, on the right, select App IDs, and then select Services ID.
  11. Select the + icon and, on the Register a New Identifier page, select Services IDs.
  12. Provide a description in the Description text box and provide an identifier for the service id. Register a services ID in the certificates, identifiers and profiles section.
  13. Continue and register the service id.

Configure Auth Category

Once you have the social provider configured, run the following in your project’s root folder:

1amplify add auth ## "amplify update auth" if already configured

Choose the following options (the last steps are specific to Facebook here but are similar for other providers):

1? Do you want to use the default authentication and security configuration?
2 `Default configuration with Social Provider (Federation)`
3? How do you want users to be able to sign in?
4 `Username`
5? Do you want to configure advanced settings?
6 `No, I am done.`
7? What domain name prefix you want us to create for you?
8 `(default)`
9? Enter your redirect signin URI:
10 `http://localhost:3000/`
11? Do you want to add another redirect signin URI
12 `No`
13? Enter your redirect signout URI:
14 `http://localhost:3000/`
15? Do you want to add another redirect signout URI
16 `No`
17? Select the social providers you want to configure for your user pool:
18 `<choose your provider and follow the prompts to input the proper tokens>`

Run amplify push to publish your changes. Once finished, it will display an auto generated URL for your web UI. You can retrieve your user pool domain URL at anytime by running amplify status using the CLI.

You need to now inform your auth provider of this URL:

  1. Sign In to your Facebook developer account with your Facebook credentials.

  2. Choose My Apps from the top navigation bar, and on the Apps page, choose your App you created before.

  3. On the left navigation bar, choose Products. Add Facebook Login if it isn't already added.

  4. If already added, choose Settings under the Configure dropdown. The Settings option is circled from the configure dropdown.

  5. Under Valid OAuth Redirect URIs type your user pool domain with the /oauth2/idpresponse endpoint.

    https://<your-user-pool-domain>/oauth2/idpresponse

Userpool domain is pasted into the text field with /oauth2/ endpoint.

  1. Save changes.
  1. Go to the Google developer console.

  2. On the left navigation bar, look for APIs & Services under Pinned or under More Products if not pinned.

  3. Within the APIs and Services sub menu, choose Credentials.

  4. Select the client you created in the first step and click the edit button.

  5. Type your user pool domain into Authorized Javascript origins.

  6. Type your user pool domain with the /oauth2/idpresponse endpoint into Authorized Redirect URIs.

    The URLs 1 form fields for authorized Javascript origins and authorized redirect URLs are circled.

    Note: If you saw an error message Invalid Redirect: domain must be added to the authorized domains list before submitting. when adding the endpoint, please go to the authorized domains list and add the domain.

  7. Click Save.

  1. Sign in with your Amazon credentials.
  2. Hover over the gear and choose Web Settings associated with the security profile you created in the previous step, and then choose Edit. The web settings option is selected in the dropdown menu from the gear icon.
  3. Type your user pool domain into Allowed Origins and type your user pool domain with the /oauth2/idpresponse endpoint into Allowed Return URLs. Userpool domain is typed into the allowed origins field with /oauth2/ as the endpoint in the Allowed Return URLs field.
  4. Choose Save.
  1. Sign In with your Apple developer credentials.
  2. On the main developer portal page, select Certificates, IDs, & Profiles.
  3. On the left navigation bar, select Identifiers and then select Service IDs from the drop down list on the right.
  4. Select the service id created in Setup your auth provider step above.
  5. Enabled Sign In with Apple and select Configure.
  6. Under Primary App ID select the app id that was created before.
  7. Type your user pool domain into Domains and Subdomains.
  8. Type your user pool domain with the /oauth2/idpresponse endpoint into Return URLs. The return URLs text field is selected.
  9. Click Next, review the information, then select Done.
  10. On Edit your Services ID Configuration click Continue, review the information, then select Save.
  11. On the main Certificates, Identifiers & Profiles, select Keys.
  12. On the Keys page, select the + icon.
  13. Provide a name for the key under Key Name.
  14. Enable Sign in with Apple and select Configure The sign in with apple option is enabled and the key name text field is filled out.
  15. Under Primary App ID select the app id that was created before.
  16. Click on Save
  17. On Register a New Key click Continue, review the information, then select Register.
  18. On the page you are redirected to take note of the Key ID and download the .p8 file containing the private key. The download key page is shown with the option to download the .p8 file with the private key.

Federated sign-in does not invoke any Custom authentication challenge Lambda triggers, Migrate user Lambda trigger, Custom message Lambda trigger, or Custom sender Lambda triggers in your user pool. For information on the supported Lambda triggers refer to the AWS documentation

Setup Amazon Cognito Hosted UI in Android App

Add the following activity and queries tag to your app's AndroidManifest.xml file, replacing myapp with whatever value you used for your redirect URI prefix:

1<queries>
2 <intent>
3 <action android:name="android.intent.action.VIEW" />
4 <data android:scheme="https" />
5 </intent>
6 <intent>
7 <action android:name=
8 "android.support.customtabs.action.CustomTabsService" />
9 </intent>
10</queries>
11<application ...>
12 ...
13 <activity
14 android:name="com.amazonaws.mobile.client.activities.HostedUIRedirectActivity"
15 android:exported="true">
16 <intent-filter>
17 <action android:name="android.intent.action.VIEW" />
18 <category android:name="android.intent.category.DEFAULT" />
19 <category android:name="android.intent.category.BROWSABLE" />
20 <data android:scheme="myapp" />
21 </intent-filter>
22 </activity>
23 ...
24</application>
  1. Add the following activity to your app's AndroidManifest.xml file, replacing myapp with whatever value you used for your redirect URI prefix:
1<activity
2 android:name="com.amazonaws.mobile.client.activities.HostedUIRedirectActivity">
3 <intent-filter>
4 <action android:name="android.intent.action.VIEW" />
5 <category android:name="android.intent.category.DEFAULT" />
6 <category android:name="android.intent.category.BROWSABLE" />
7 <data android:scheme="myapp" />
8 </intent-filter>
9</activity>
  1. If you previously setup HostedUI for versions between 2.18.0 and 2.23.0, then the only required change is to replace com.amazonaws.mobileconnectors.cognitoauth.activities.CustomTabsRedirectActivity with the updated version (com.amazonaws.mobile.client.activities.HostedUIRedirectActivity). You are no longer required to call the method AWSMobileClient#handleAuthResponse(Intent) in your app.

Note: These versions have known issues with the sign-out flow. Please use the SDK versions 2.24.0 and above.

  1. Add the following activity to your app's AndroidManifest.xml file, replacing myapp with whatever value you used for your redirect URI prefix:
1<activity
2 android:name="com.amazonaws.mobileconnectors.cognitoauth.activities.CustomTabsRedirectActivity">
3 <intent-filter>
4 <action android:name="android.intent.action.VIEW" />
5 <category android:name="android.intent.category.DEFAULT" />
6 <category android:name="android.intent.category.BROWSABLE" />
7 <data android:scheme="myapp" />
8 </intent-filter>
9</activity>
  1. Add the following result handler to whichever Activity you are calling HostedUI from:
1@Override
2protected void onActivityResult(int requestCode, int resultCode, Intent data) {
3 super.onActivityResult(requestCode, resultCode, data);
4 if (requestCode == AuthClient.CUSTOM_TABS_ACTIVITY_CODE) {
5 AWSMobileClient.getInstance().handleAuthResponse(data);
6 }
7}
  1. If you previously setup HostedUI for version 2.17.1 or below, remove the intent filter you previously added to your activity in the AndroidManifest.xml file with the URI scheme (e.g. myapp) as well as the onResume() or onNewIntent() handler method you previously added to your Activity.
  1. Add myapp:// to your app's Intent filters located in AndroidManifest.xml. The your.package.YourAuthIntentHandlingActivity will be referenced in the next step.

    1<?xml version="1.0" encoding="utf-8"?>
    2 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
    3 xmlns:amazon="http://schemas.amazon.com/apk/res/android"
    4 package="com.amazonaws.mobile.client">
    5
    6 <uses-permission android:name="android.permission.INTERNET"/>
    7 <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    8
    9 <application>
    10 <activity android:name="your.package.YourAuthIntentHandlingActivity">
    11 <intent-filter>
    12 <action android:name="android.intent.action.VIEW" />
    13 <category android:name="android.intent.category.DEFAULT" />
    14 <category android:name="android.intent.category.BROWSABLE" />
    15 <data android:scheme="myapp" />
    16 </intent-filter>
    17 </activity>
    18 </application>
    19</manifest>
  2. Attach an intent callback so that AWSMobileClient can handle the callback and confirm sign-in or sign-out. This should be in your.package.YourAuthIntentHandlingActivity.

    1@Override
    2protected void onResume() {
    3 super.onResume();
    4 Intent activityIntent = getIntent();
    5 if (activityIntent.getData() != null &&
    6 "myapp".equals(activityIntent.getData().getScheme())) {
    7 AWSMobileClient.getInstance().handleAuthResponse(activityIntent);
    8 }
    9}

Launching the Hosted UI

To launch the Hosted UI from from your application, you can use the showSignIn API of AWSMobileClient.getInstance():

1// No options are being specified, only the config will be used
2HostedUIOptions hostedUIOptions = HostedUIOptions.builder()
3 .scopes("openid", "email")
4 .build();
5SignInUIOptions signInUIOptions = SignInUIOptions.builder()
6 .hostedUIOptions(hostedUIOptions)
7 .build();
8// 'this' refers to the current active Activity
9AWSMobileClient.getInstance().showSignIn(this, signInUIOptions, new Callback<UserStateDetails>() {
10 @Override
11 public void onResult(UserStateDetails details) {
12 Log.d(TAG, "onResult: " + details.getUserState());
13 }
14
15 @Override
16 public void onError(Exception e) {
17 Log.e(TAG, "onError: ", e);
18 }
19});

Note: By default, the Hosted UI will show all sign-in options; the username-password flow as well as any social providers which are configured. If you wish to bypass the extra sign-in screen showing all the provider options and launch your desired social provider login directly, you can set the HostedUIOptions as shown in the next section.

Configuring Hosted UI to launch Facebook/ Google/ SAML sign in directly

1// For Google
2HostedUIOptions hostedUIOptions = HostedUIOptions.builder()
3 .scopes("openid", "email")
4 .identityProvider("Google")
5 .build();
6
7// For Facebook
8HostedUIOptions hostedUIOptions = HostedUIOptions.builder()
9 .scopes("openid", "email")
10 .identityProvider("Facebook")
11 .build();
12
13SignInUIOptions signInUIOptions = SignInUIOptions.builder()
14 .hostedUIOptions(hostedUIOptions)
15 .build();
16// 'this' refers to the current active Activity
17AWSMobileClient.getInstance().showSignIn(this, signInUIOptions, new Callback<UserStateDetails>() {
18 @Override
19 public void onResult(UserStateDetails details) {
20 Log.d(TAG, "onResult: " + details.getUserState());
21 }
22
23 @Override
24 public void onError(Exception e) {
25 Log.e(TAG, "onError: ", e);
26 }
27});

Sign Out from HostedUI

1AWSMobileClient.getInstance().signOut(SignOutOptions.builder().invalidateTokens(true).build(), new Callback<Void>() {
2 @Override
3 public void onResult(Void result) {
4 Log.d(TAG, "onResult: ");
5 }
6
7 @Override
8 public void onError(Exception e) {
9 Log.e(TAG, "onError: ", e);
10 }
11});

If you want to sign out locally by just deleting tokens, you can call signOut method:

1AWSMobileClient.getInstance().signOut();

Add Response handler

Add the result handler if you need to capture sign in cancellations that occurred before the user submitted credentials.

1@Override
2protected void onActivityResult(int requestCode, int resultCode, Intent data) {
3 super.onActivityResult(requestCode, resultCode, data);
4
5 if (requestCode == AuthClient.CUSTOM_TABS_ACTIVITY_CODE &&
6 resultCode == Activity.RESULT_CANCELED) {
7 // handle canceled sign in
8 }
9}

Manual Setup

To configure your application for hosted UI, you need to use HostedUI options. Update your awsconfiguration.json file to add a new configuration for Auth. The configuration should look like this:

1{
2 "IdentityManager": {
3 ...
4 },
5 "CredentialsProvider": {
6 ...
7 },
8 "CognitoUserPool": {
9 ...
10 },
11 "Auth": {
12 "Default": {
13 "OAuth": {
14 "WebDomain": "YOUR_AUTH_DOMAIN.auth.us-west-2.amazoncognito.com", // Do not include the https:// prefix
15 "AppClientId": "YOUR_APP_CLIENT_ID",
16 "SignInRedirectURI": "myapp://callback",
17 "SignOutRedirectURI": "myapp://signout",
18 "Scopes": ["openid", "email"]
19 }
20 }
21 }
22}

Note: The User Pool OIDC JWT token obtained from a successful sign-in will be federated into a configured Cognito Identity pool in the awsconfiguration.json and the SDK will automatically exchange this with Cognito Identity to also retrieve AWS credentials.

Using Auth0 Hosted UI

You can use AWSMobileClient to use Auth0 as OAuth 2.0 provider. You can use Auth0 as one of the providers of your Cognito Federated Identity Pool. This will allow users authenticated via Auth0 have access to your AWS resources. Learn how to integrate Auth0 with Cognito Federated Identity Pools

Setup Auth0 Hosted UI in Android App

Setup Amazon Cognito Hosted UI in Android App

  1. To configure your application for hosted UI, you need to use HostedUI options. Update your awsconfiguration.json file to add a new configuration for Auth. The configuration should look like this:

    1{
    2 "IdentityManager": {
    3 ...
    4 },
    5 "CredentialsProvider": {
    6 ...
    7 },
    8 "CognitoUserPool": {
    9 ...
    10 },
    11 "Auth": {
    12 "Default": {
    13 "OAuth": {
    14 "AppClientId": "YOUR_AUTH0_APP_CLIENT_ID",
    15 "TokenURI": "https://YOUR_AUTH0_DOMAIN.auth0.com/oauth/token",
    16 "SignInURI": "https://YOUR_AUTH0_DOMAIN.auth0.com/authorize",
    17 "SignInRedirectURI": "com.your.bundle.configured.in.auth0://YOUR_AUTH0_DOMAIN.auth0.com/android/com.your.bundle/callback",
    18 "SignOutURI": "https://YOUR_AUTH0_DOMAIN.auth0.com/v2/logout",
    19 "SignOutRedirectURI": "com.your.bundle.configured.in.auth0://yourserver.auth0.com/android/com.amazonaws.AWSAuthSDKTestApp/signout",
    20 "SignOutURIQueryParameters": {
    21 "client_id" : "YOUR_AUTH0_APP_CLIENT_ID",
    22 "returnTo" : "com.your.bundle.configured.in.auth0://yourserver.auth0.com/android/com.amazonaws.AWSAuthSDKTestApp/signout"
    23 },
    24 "Scopes": ["openid", "email"]
    25 }
    26 }
    27 }
    28}
  2. Add the sign-in and sign-out redirect URIs to your app's Intent filters located in AndroidManifest.xml.

    1<?xml version="1.0" encoding="utf-8"?>
    2 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
    3 xmlns:amazon="http://schemas.amazon.com/apk/res/android"
    4 package="com.amazonaws.mobile.client">
    5
    6 <uses-permission android:name="android.permission.INTERNET"/>
    7 <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    8
    9 <application>
    10 <activity android:name="your.package.YourAuthIntentHandlingActivity">
    11 <intent-filter>
    12 <action android:name="android.intent.action.VIEW" />
    13
    14 <category android:name="android.intent.category.DEFAULT" />
    15 <category android:name="android.intent.category.BROWSABLE" />
    16
    17 <data android:scheme="com.your.bundle.configured.in.auth0" />
    18 </intent-filter>
    19 </activity>
    20 </application>
    21
    22</manifest>
  3. Attach an intent callback so that the AWSMobileClient can handle the callback and confirm sign-in or sign-out. This should be in your.package.YourAuthIntentHandlingActivity.

    1@Override
    2protected void onResume() {
    3 super.onResume();
    4 Intent activityIntent = getIntent();
    5 if (activityIntent.getData() != null &&
    6 "com.your.bundle.configured.in.auth0".equals(activityIntent.getData().getScheme())) {
    7 AWSMobileClient.getInstance().handleAuthResponse(activityIntent);
    8 }
    9}

Launching the Hosted UI for Auth0

To launch the Hosted UI from from your application, you can use the showSignIn API of AWSMobileClient.getInstance():

1final HostedUIOptions hostedUIOptions = HostedUIOptions.builder()
2 .federationProviderName("YOUR_AUTH0_DOMAIN.auth0.com")
3 .build();
4final SignInUIOptions signInUIOptions = SignInUIOptions.builder()
5 .hostedUIOptions(hostedUIOptions)
6 .build();
7// 'this' refers to the current active Activity
8AWSMobileClient.getInstance().showSignIn(this, signInUIOptions, new Callback<UserStateDetails>() {
9 @Override
10 public void onResult(UserStateDetails result) {
11 Log.d(TAG, "onResult: " + result.getUserState());
12 }
13
14 @Override
15 public void onError(Exception e) {
16 Log.e(TAG, "onError: ", e);
17 }
18});

Sign Out from HostedUI

1AWSMobileClient.getInstance().signOut(SignOutOptions.builder().invalidateTokens(true).build(), new Callback<Void>() {
2 @Override
3 public void onResult(Void result) {
4 Log.d(TAG, "onResult: ");
5 }
6
7 @Override
8 public void onError(Exception e) {
9 Log.e(TAG, "onError: ", e);
10 }
11});

If you want to sign out locally by just deleting tokens, you can call signOut method:

1AWSMobileClient.getInstance().signOut();