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, and get its DNS name.

2.    Create and configure an Amazon Cognito user pool.

3.    Configure the Application Load Balancer.

4.    Test the setup.

Resolution

To configure an Application Load Balancer and an Amazon Cognito user pool to authenticate your application users, complete the following steps.

Create an Application Load Balancer

Note: If you already configured an Application Load Balancer, then proceed to the next section.

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

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

Create and configure an Amazon Cognito user pool

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://loadBalancerDNSName/oauth2/idpresponse.

-or-

If you used a CNAME record to map a custom domain to your Application Load Balancer, then enter https://CNAME/oauth2/idpresponse.

Note: Replace loadBalancerDNSName with the DNS name that you copied from the Amazon EC2 console. If you're using 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. For testing, 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 according to your requirements.

12.    Under OpenID Connect scopes, select the OpenID check box. The OpenID scope returns an ID token. Select any additional OpenID Connect (OIDC) scopes according to your requirements.

13.    Choose Save changes.

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

Configure your Application Load Balancer

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 tab, select the HTTPS listener default rule that you want to update, and then choose Actions, Manage rules.

5.    Edit the HTTPS listener default rule with the following settings:

• For THEN, choose Add action.
• Choose Authenticate.
• For Authenticate, choose Amazon Cognito.
• For the user pool, enter the User pool ID that you copied from the Amazon Cognito console.
• For the app client, enter the Client ID that you copied from the Amazon Cognito console.
• Expand Advanced settings.
• 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.
• Choose the check mark icon.

6.    Continue editing the HTTPS listener default rule with the following settings:

• For THEN, choose Add action.
  Note: If you can't choose Add action, then use the trash can icon to delete the existing routing action, such as Redirect to. Then, try again.
• Choose Forward to.
• For Forward to, choose one or more target groups.
• (Optional) Configure Group-level stickiness.
• Choose the check mark icon.

7.    Choose Update to update the HTTPS listener default rule.

Test the setup

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

• https://loadBalancerDNSName/
• https://CNAME/

Note: Replace loadBalancerDNSName with the DNS name that you copied from the Amazon EC2 console. Or, replace CNAME with your custom domain. 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