Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Authenticate users using an Application Load Balancer

You can configure an Application Load Balancer to securely authenticate users as they access your applications. This enables you to offload the work of authenticating users to your load balancer so that your applications can focus on their business logic.

Prepare to use an OIDC-compliant IdP

Do the following if you are using an OIDC-compliant IdP with your Application Load Balancer:

Prepare to use Amazon Cognito

Do the following if you are using Amazon Cognito user pools with your Application Load Balancer:

The callback URL in the app client settings must use all lowercase letters.

To enable a user to configure a load balancer to use Amazon Cognito to authenticate users, you must grant the user permission to call the cognito-idp:DescribeUserPoolClient action.

Prepare to use Amazon CloudFront

Enable the following settings if you are using a CloudFront distribution in front of your Application Load Balancer:

Configure user authentication

You configure user authentication by creating an authenticate action for one or more listener rules. The authenticate-cognito and authenticate-oidc action types are supported only with HTTPS listeners. For descriptions of the corresponding fields, see AuthenticateCognitoActionConfig and AuthenticateOidcActionConfig in the Elastic Load Balancing API Reference version 2015-12-01.

The load balancer sends a session cookie to the client to maintain authentication status. This cookie always contains the secure attribute, because user authentication requires an HTTPS listener. This cookie contains the SameSite=None attribute with CORS (cross-origin resource sharing) requests.

For a load balancer supporting multiple applications that require independent client authentication, each listener rule with an authenticate action should have a unique cookie name. This ensures that clients are always authenticated with the IdP before being routed to the target group specified in the rule.

Application Load Balancers do not support cookie values that are URL encoded.

By default, the SessionTimeout field is set to 7 days. If you want shorter sessions, you can configure a session timeout as short as 1 second. For more information, see Session timeout.

Set the OnUnauthenticatedRequest field as appropriate for your application. For example:

The load balancer must be able to communicate with the IdP token endpoint (TokenEndpoint) and the IdP user info endpoint (UserInfoEndpoint). Verify that the security groups for your load balancer and the network ACLs for your VPC allow outbound access to these endpoints. Verify that your VPC has internet access. If you have an internal-facing load balancer, use a NAT gateway to enable the load balancer to access these endpoints. For more information, see NAT gateway basics in the Amazon VPC User Guide.

Use the following create-rule command to configure user authentication.

aws elbv2 create-rule --listener-arn listener-arn --priority 10 \
--conditions Field=path-pattern,Values="/login" --actions file://actions.json

The following is an example of the actions.json file that specifies an authenticate-oidc action and a forward action. AuthenticationRequestExtraParams allows you to pass extra parameters to an IdP during authentication. Please follow documentation provided by your identity provider to determine the fields that are supported

[{
    "Type": "authenticate-oidc",
    "AuthenticateOidcConfig": {
        "Issuer": "https://idp-issuer.com",
        "AuthorizationEndpoint": "https://authorization-endpoint.com",
        "TokenEndpoint": "https://token-endpoint.com",
        "UserInfoEndpoint": "https://user-info-endpoint.com",
        "ClientId": "abcdefghijklmnopqrstuvwxyz123456789",
        "ClientSecret": "123456789012345678901234567890",
        "SessionCookieName": "my-cookie",
        "SessionTimeout": 3600,
        "Scope": "email",
        "AuthenticationRequestExtraParams": {
            "display": "page",
            "prompt": "login"
        },
        "OnUnauthenticatedRequest": "deny"
    },
    "Order": 1
},
{
    "Type": "forward",
    "TargetGroupArn": "arn:aws-cn:elasticloadbalancing:region-code:account-id:targetgroup/target-group-name/target-group-id",
    "Order": 2
}]

The following is an example of the actions.json file that specifies an authenticate-cognito action and a forward action.

[{
    "Type": "authenticate-cognito",
    "AuthenticateCognitoConfig": {
        "UserPoolArn": "arn:aws-cn:cognito-idp:region-code:account-id:userpool/user-pool-id",
        "UserPoolClientId": "abcdefghijklmnopqrstuvwxyz123456789",
        "UserPoolDomain": "userPoolDomain1",
        "SessionCookieName": "my-cookie",
        "SessionTimeout": 3600,
        "Scope": "email",
        "AuthenticationRequestExtraParams": {
            "display": "page",
            "prompt": "login"
        },
        "OnUnauthenticatedRequest": "deny"
    },
    "Order": 1
},
{
    "Type": "forward",
    "TargetGroupArn": "arn:aws-cn:elasticloadbalancing:region-code:account-id:targetgroup/target-group-name/target-group-id",
    "Order": 2
}]

For more information, see Listener rules.

Authentication flow

The following network diagram is a visual representation of how an Application Load Balancer uses OIDC to authenticate users.

The numbered items below, highlight and explain elements shown in the preceding network diagram.

Every new request goes through steps 1 through 11, while subsequent requests go through steps 9 through 11. That is, every subsequent request starts at step 9 as long as the cookie has not expired.

The AWSALBAuthNonce cookie is added to the request header after the user authenticates at the IdP. This does not change how the Application Load Balancer processes redirect requests from the IdP.

If the IdP provides a valid refresh token in the ID token, the load balancer saves the refresh token and uses it to refresh the user claims each time the access token expires, until the session times out or the IdP refresh fails. If the user logs out, the refresh fails and the load balancer redirects the user to the IdP authorization endpoint. This enables the load balancer to drop sessions after the user logs out. For more information, see Session timeout.

User claims encoding and signature verification

After your load balancer authenticates a user successfully, it sends the user claims received from the IdP to the target. The load balancer signs the user claim so that applications can verify the signature and verify that the claims were sent by the load balancer.

Access tokens and user claims are different from ID tokens. Access tokens and user claims only allow access to server resources, while ID tokens carry additional information to authenticate a user. The Application Load Balancer creates a new access token when authenticating a user and only passes the access tokens and claims to the backend, however it does not pass the ID token information.

These tokens follow the JWT format but are not ID tokens. The JWT format includes a header, payload, and signature that are base64 URL encoded, and includes padding characters at the end. An Application Load Balancer uses ES256 (ECDSA using P-256 and SHA256) to generate the JWT signature.

The JWT header is a JSON object with the following fields:

{
   "alg": "algorithm",
   "kid": "12345678-1234-1234-1234-123456789012",
   "signer": "arn:aws-cn:elasticloadbalancing:region-code:account-id:loadbalancer/app/load-balancer-name/load-balancer-id", 
   "iss": "url",
   "client": "client-id",
   "exp": "expiration"
}

The JWT payload is a JSON object that contains the user claims received from the IdP user info endpoint.

{
   "sub": "1234567890",
   "name": "name",
   "email": "alias@example.com",
   ...
}

Because the load balancer does not encrypt the user claims, we recommend that you configure the target group to use HTTPS. If you configure your target group to use HTTP, be sure to restrict the traffic to your load balancer using security groups.

To ensure security, you must verify the signature before doing any authorization based on the claims and validate that the signer field in the JWT header contains the expected Application Load Balancer ARN.

To get the public key, get the key ID from the JWT header and use it to look up the public key from the endpoint.

For China (Beijing), the endpoint is as follows:

https://aws-elb-public-keys-prod-cn-north-1.s3.cn-north-1.amazonaws.com.cn/

The following example shows how to get the key ID, public key, and payload in Python 3.x:

import jwt
import requests
import base64
import json

# Step 1: Validate the signer
expected_alb_arn = 'arn:aws:elasticloadbalancing:region-code:account-id:loadbalancer/app/load-balancer-name/load-balancer-id'

encoded_jwt = headers.dict['x-amzn-oidc-data']
jwt_headers = encoded_jwt.split('.')[0]
decoded_jwt_headers = base64.b64decode(jwt_headers)
decoded_jwt_headers = decoded_jwt_headers.decode("utf-8")
decoded_json = json.loads(decoded_jwt_headers)
received_alb_arn = decoded_json['signer']

assert expected_alb_arn == received_alb_arn, "Invalid Signer"

# Step 2: Get the key id from JWT headers (the kid field)
kid = decoded_json['kid']

# Step 3: Get the public key from regional endpoint
url = 'https://aws-elb-public-keys-prod-cn-north-1.s3.cn-north-1.amazonaws.com.cn/' + kid
req = requests.get(url)
pub_key = req.text

# Step 4: Get the payload
payload = jwt.decode(encoded_jwt, pub_key, algorithms=['ES256'])

The following example shows how to get the key ID, public key, and payload in Python 2.7:

import jwt
import requests
import base64
import json

# Step 1: Validate the signer
expected_alb_arn = 'arn:aws:elasticloadbalancing:region-code:account-id:loadbalancer/app/load-balancer-name/load-balancer-id'

encoded_jwt = headers.dict['x-amzn-oidc-data']
jwt_headers = encoded_jwt.split('.')[0]
decoded_jwt_headers = base64.b64decode(jwt_headers)
decoded_json = json.loads(decoded_jwt_headers)
received_alb_arn = decoded_json['signer']

assert expected_alb_arn == received_alb_arn, "Invalid Signer"

# Step 2: Get the key id from JWT headers (the kid field)
kid = decoded_json['kid']

# Step 3: Get the public key from regional endpoint
url = 'https://aws-elb-public-keys-prod-cn-north-1.s3.cn-north-1.amazonaws.com.cn/' + kid
req = requests.get(url)
pub_key = req.text

# Step 4: Get the payload
payload = jwt.decode(encoded_jwt, pub_key, algorithms=['ES256'])

Timeout

Session timeout

The refresh token and the session timeout work together as follows:

Client login timeout

A client must initiate and complete the authentication process within 15 minutes. If a client fails to complete authentication within the 15-minute limit, it receives an HTTP 401 error from the load balancer. This timeout can't be changed or removed.

For example, if a user loads the login page through the Application Load Balancer, they must complete the login process within 15 minutes. If the user waits and then attempts to log in after the 15-minute timeout has expired, the load balancer returns an HTTP 401 error. The user will have to refresh the page and attempt logging in again.

Authentication logout

When an application needs to log out an authenticated user, it should set the expiration time of the authentication session cookie to -1 and redirect the client to the IdP logout endpoint (if the IdP supports one). To prevent users from reusing a deleted cookie, we recommend that you configure as short an expiration time for the access token as is reasonable. If a client provides a load balancer with a session cookie that has an expired access token with a non-NULL refresh token, the load balancer contacts the IdP to determine whether the user is still logged in.

The client logout landing page is an unauthenticated page. This means that it cannot be behind an Application Load Balancer rule that requires authentication.