Skip to content
This repository has been archived by the owner on Jun 16, 2023. It is now read-only.

Latest commit

 

History

History
210 lines (119 loc) · 15.4 KB

cognito-user-pools-app-integration.md

File metadata and controls

210 lines (119 loc) · 15.4 KB
Raw

Using the Amazon Cognito hosted UI for sign-up and sign-in

The Amazon Cognito Hosted UI provides you an OAuth 2.0 compliant authorization server. It includes default implementation of end user flows such as registration and authentication. You can also customize user flows, such as the addition of Multi Factor Authentication (MFA), by changing your user pool configuration. Your application will redirect to the Hosted UI, which will handle your user flows. The user experience can be customized by providing brand-specific logos, as well as customizing the design of Hosted UI elements. The Amazon Cognito Hosted UI also allows you to add the ability for end users to sign in with social providers (Facebook, Amazon, Google, and Apple), as well as any OpenID Connect (OIDC)-compliant and SAML providers.

Topics

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:

Setting up the hosted UI with the Amazon Cognito console

[ Original console ]

Create an app client

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

  2. Choose Manage User Pools.

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

  4. On the navigation bar on the left-side of the page, under General settings, choose App clients .

  5. Choose Add an app client.

  6. Enter a name for your app.

  7. Unless required by your authorization flow, clear the option Generate client secret. The client secret is used by applications that have a server-side component that can secure the client secret.

  8. (Optional) Change the token expiration settings.

  9. Select Auth Flows Configuration options. For more information, see User Pool Authentication Flow.

  10. Choose a Security configuration. We recommend you select Enabled.

  11. (Optional) Choose Set attribute read and write permissions. For more information, see Attribute Permissions and Scopes.

  12. Choose Create app client.

  13. Note the App client id.

  14. Choose Return to pool details.

Configure the app

  1. Choose App client settings from the navigation bar on the left side of the console page.

  2. Select Cognito User Pool as one of the Enabled Identity Providers. Note
    To sign in with external identity providers (IdPs), such as Facebook, Amazon, Google, or Apple, as well as through OpenID Connect (OIDC) or SAML IdPs, first configure them as described in the following steps, and then return to the App client settings page to enable them.

  3. Enter Callback URL(s). A callback URL indicates where the user will be redirected after a successful sign-in.

  4. Enter Sign out URL(s). A sign-out URL indicates where your user will be redirected after signing out.

  5. 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 be 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. 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 grant and the Implicit code grant, and then use each grant as needed.

  8. Unless you specifically want to exclude one, select the check boxes for all of the Allowed OAuth scopes.

  9. Select Client credentials only if your app needs to request access tokens on its own behalf, not on behalf of a user.

  10. Choose Save changes.

Configure a domain

  1. Select Choose domain name.

  2. On the Domain name page, type a domain prefix and check availability, or enter your own domain.

  3. Make a note of the complete domain address.

  4. Choose Save changes.

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

To view 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 OIDC and hosted UI API endpoints reference.

The hosted UI sign-in webpage uses the following URL format. Note the response_type. In this case, response_type=code for the authorization code grant.

https://<your_domain>/oauth2/authorize?response_type=code&client_id=<your_app_client_id>&redirect_uri=<your_callback_url>

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.

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.

Here's 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

If changes to your hosted UI pages do not immediately appear, wait a few minutes and then refresh the page. Amazon Cognito user pools 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.

Your domain is shown on the Domain name page. Your app client ID and callback URL are shown on the App client settings page.

Note
The Amazon Cognito hosted UI does not support the custom authentication flow.

The Amazon Cognito hosted UI doesn't support custom cross-origin resource sharing (CORS) origin policies. Amazon Cognito returns an Access-Control-Allow-Origin: * response header to all requests. 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.