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

Short description

To manage and authenticate users, you can integrate an Application Load Balancer with an Amazon Cognito user pool. 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 next section.

To create an Application Load Balancer, complete the following steps:

1. Create an internet-facing 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

To 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, copy and save your load balancer's DNS name. Use this DNS name to test access to your Application Load Balancer's endpoint URL.

Create and configure an Amazon Cognito user pool

To create and configure an Amazon Cognito user pool, complete the following steps:

1. Create an Amazon Cognito user pool with an app client. When you configure the app client, select the Generate a client secret radio button. For more information, see Prepare to use Amazon Cognito.
   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 example, you can't change the required standard attributes for user registration.
2. Open the Amazon Cognito console.
3. In the navigation pane, choose User pools, and then select your user pool. Copy and save the User pool ID. Use this ID to configure your Application Load Balancer for user authentication.
4. Choose the App integration tab for your user pool, and then add a domain for your user pool.
5. From the App integration tab for your user pool, navigate to the App clients and analytics section. Then, select your app client.
6. On the app client page, under App client information, copy and save the Client ID. Use this ID to configure your Application Load Balancer for user authentication.
7. In the Hosted UI section, choose Edit.
8. Choose Add callback URL, and then enter https://load-balancer-dns-name/oauth2/idpresponse.
   -or-
   If you used a CNAME record to map a custom domain to your Application Load Balancer, and then enter https://CNAME/oauth2/idpresponse.
   Note: Replace load-balancer-dns-name with the DNS name that you copied from the Amazon EC2 console. The DNS name can't contain any uppercase letters. If you use a CNAME record, then replace CNAME with your custom domain.
9. 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/.
10. For Identity providers, select the Cognito user pool check box.
11. Under OAuth 2.0 grant types, select the Authorization code grant check box. Select any additional OAuth grant types that you need for your use case.
12. Under OpenID Connect scopes, select the OpenID check box. The OpenID scope returns an ID token. Select any additional OpenID Connect (OIDC) scopes that you need for your use case.
13. Choose Save changes.

For more information, see Updating user pool and app client configuration and Adding user pool sign-in through a third party.

Configure your Application Load Balancer

To 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, then choose Manage rules, and then choose Edit rules.
5. In the Listeners rules section, select the default rule that you want to update, then choose Action, and then choose Edit rules.
6. Edit the HTTPS listener default rule with the following settings:
   For Authentication, select Use OpenID or Amazon Cognito.
   For Identity provider, choose Amazon Cognito.
   For the User pool, select the User pool ID that you got from the Amazon Cognito console.
   For the App client, select the Client ID that you got from the Amazon Cognito console.
   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 in the configuration is ["openid","email","phone","profile"], then enter openid email phone profile.
   For Action on unauthenticated request, leave it as the default value.
   (Optional) Expand Extra request parameters - optional. This option lets you pass extra 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}. This parameter lets you skip the Cognito Hosted UI and reach the Google sign in page directly. For more information on the allowed /oauth2/authorize parameters, see Authorize endpoint.
7. Continue to edit the HTTPS listener default rule with the following settings:
   For Routing actions, choose Forward to target group, and then choose one or more target groups.
   (Optional) For Target group stickiness, choose Turn on target group stickiness when your use case requires it.
8. Configure 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.
9. To apply the updates to the HTTPS listener default rule, 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 the DNS name that you copied from the Amazon EC2 console. Or, replace 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