How do I set up an Application Load Balancer to authenticate users through an Amazon Cognito user pool?

Short description

To set up user authentication with an Application Load Balancer and an Amazon Cognito user pool, complete the following steps:

1. Create an Application Load Balancer.
2. Get the DNS name of your Application Load Balancer.
3. Create and configure an Amazon Cognito user pool.
4. Configure the Application Load Balancer.
5. Test the setup.

Resolution

Create an Application Load Balancer

Note: If you already configured an Application Load Balancer, then proceed to the Get the DNS name of your Application Load Balancer section.

Complete the following steps:

1. Create an Application Load Balancer.
2. Create an HTTPS listener for your Application Load Balancer.

Note: Only HTTPS listeners support the authenticate-cognito and authenticate-oidc rule action types.

Get the DNS name of your Application Load Balancer

Complete the following steps:

1. Open the Amazon Elastic Compute Cloud (Amazon EC2) console.
2. In the navigation pane, under Load Balancing, choose Load Balancers.
3. Select your Application Load Balancer.
4. On the Details tab, note your load balancer's DNS name to use in a later step.

Create and configure an Amazon Cognito user pool

Complete the following steps:

1. Open the Amazon Cognito console.
2. In the navigation pane, choose Create a user pool.
   Note: When you create the user pool, configure the settings that you want for production. After you create the user pool, you can't change some user pool settings. For more information, see How do I change the attributes of an Amazon Cognito user pool after creation?
3. Configure an app client for your user pool.
   When you configure the app client, select the Generate a client secret radio button. For more information, see Prepare to use Amazon Cognito.
4. In the navigation pane, choose User pools, and then select your user pool. Note the User pool ID to use in a later step.
5. Choose the App integration tab for your user pool, and then add a domain for your user pool.
6. On the App integration tab for your user pool, select your app client in the App clients and analytics section.
7. On the App client page, under App client information, note the Client ID to use in a later step.
8. In the Hosted UI section, choose Edit.
9. Choose Add callback URL, and then enter https://load-balancer-dns-name/oauth2/idpresponse with your DNS name.  If you used a CNAME record to map a custom domain to your Application Load Balancer, then enter https://CNAME/oauth2/idpresponse with your custom domain name.
   Note: The DNS name can't contain uppercase letters.
10. Choose Add sign-out URL, and then enter a URL that you want to redirect your users to after they sign out. To test the redirect, you can enter any valid URL, such as https://example.com/.
11. For Identity providers, select Cognito user pool.
12. Under OAuth 2.0 grant types, select Authorization code grant. Select additional OAuth grant types for your use case.
13. Under OpenID Connect scopes, select OpenID. The OpenID scope returns an ID token. Select additional OpenID Connect (OIDC) scopes for your use case.
14. Choose Save changes.

For more information, see Updating user pool and app client configuration and User pool sign-in with third party identity providers.

Configure your Application Load Balancer

Complete the following steps:

1. Open the Amazon EC2 console.
2. In the navigation pane, under Load Balancing, choose Load Balancers.
3. Select your Application Load Balancer.
4. On the Listeners and rules tab, select the HTTPS protocol.
5. Choose Manage rules, and then choose Edit rules.
6. In the Listeners rules section, select the default rule that you want to update.
7. Choose Action, and then choose Edit rules.
8. Configure the following settings for the HTTPS listener default rule:
   For Authentication, select Use OpenID or Amazon Cognito.
   For Identity provider, choose Amazon Cognito.
   For the User pool, select your User pool ID.
   For the App client, select your Client ID.
   Expand Advanced authentication settings.
   Name the Session cookie.
   Set the Session timeout. The default value is 7 days.
   For Scope, enter the scopes that you configured for your user pool app client, separated by spaces. You can find the scopes in your user pool's OIDC configuration. For example, if the scopes_supported value is ["openid","email","phone","profile"], then enter openid email phone profile.
   For Action on unauthenticated request, keep the default value.
   (Optional) Expand Extra request parameters - optional to add parameters to an identity provider, such as Cognito, during authentication. For example, if the Cognito user pool has Google as its own identity provider, then you can add an extra parameter {Key: identity_provider, Value: Google}. For more information about the request parameters, see Request parameters.
   For Routing actions, choose Forward to target group, and then choose target groups.
   (Optional) For Target group stickiness, choose Turn on target group stickiness when your use case requires it.
9. Configure the following secure listener settings:
   For Security policy, choose the security policy that's appropriate for your use case.
   For Default SSL/TLS server certificate, choose your certificate source.
10. Choose Save changes.

Test the setup

In your web browser, enter one of the following URLs:

• https://load-balancer-dns-name/
• https://CNAME/

Note: Replace load-balancer-dns-name with your DNS name and CNAME with your custom domain.

When you enter the URL, you're redirected to the Amazon Cognito hosted web UI for your user pool. After users sign in and the user pool authenticates them, the users are redirected to the target.

Related information

Getting started with Application Load Balancers

Simplify login with Application Load Balancer built-in authentication

Listener rules for your Application Load Balancer

OIDC user pool IdP authentication flow