AWS ALB Federated OIDC with Cognito and Entra ID

Introduction

In the previous post, we talked about how to configure the AWS ALB listener for Entra ID OIDC authentication. We noticed that the ALB does not forward the ID token that contains the user’s group memberships to the backend. The ALB forwards the access token as x-amzn-oidc-accesstoken. It generates new JWTs as headers called x-amzn-oidc-data and x-amzn-oidc-identity that contain the user claims from the user info endpoint and the subject field (sub) respectively. The Entra ID user info endpoint does not return any group memberships of the user and hence the need for some alternatives to get the groups claim. We discussed using the Graph API to get the groups in the last post, and today we will discuss how to use Cognito configured with Entra ID as the OIDC provider for the ALB.

Configure ALB Entra ID OIDC Federation with Cognito

Below is the terraform code snipper to create a new Cognito User Pool with an Entra ID OIDC client. In addition, we map the attributes that we want to forward to the backend application to a new custom attribute. We mapped the most important claims such as sub, name, email, groups, and roles to custom attributes. Since Entra ID is used to manage the users, we should disable the user sign-up feature in Cognito when we create the user pool.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
locals {
  tenant_id              = "<Azure_AD_tenant_ID>"
  microsoft_login_url    = "https://login.microsoftonline.com/${local.tenant_id}"
  authorization_endpoint = "${local.microsoft_login_url}/oauth2/v2.0/authorize"
  issuer                 = "${local.microsoft_login_url}/v2.0"
  token_endpoint         = "${local.microsoft_login_url}/oauth2/v2.0/token"
  user_info_endpoint     = "https://graph.microsoft.com/oidc/userinfo"
  scope                  = "openid profile email"
  client_id              = "<FETCH_FROM_AZURE_APP_REGISTRATION>"
  client_secret          = "<FETCH_FROM_SECRET_MANAGER>"
  certificate_arn        = "<FETCH_FROM_ACM>"
  cognito_user_pool_schema_names = [
    "sub",
    "name",
    "aud",
    "iss",
    "iat",
    "nbf",
    "exp",
    "email",
    "groups",
    "idp",
    "name",
    "oid",
    "preferred_username",
    "roles",
    "sid",
    "sub",
    "tid",
    "ver",
  ]
  attribute_mapping = {
    email                       = "preferred_username"
    username                    = "sub"
    name                        = "name"
    "custom:aud"                = "aud"
    "custom:iss"                = "iss"
    "custom:iat"                = "iat"
    "custom:nbf"                = "nbf"
    "custom:exp"                = "exp"
    "custom:email"              = "email"
    "custom:groups"             = "groups"
    "custom:idp"                = "idp"
    "custom:name"               = "name"
    "custom:oid"                = "oid"
    "custom:preferred_username" = "preferred_username"
    "custom:roles"              = "roles"
    "custom:sid"                = "sid"
    "custom:sub"                = "sub"
    "custom:tid"                = "tid"
    "custom:ver"                = "ver"
  }
}

resource "aws_cognito_user_pool" "entraid" {
  name = "entraid-oidc-pool"
  dynamic "schema" {
    for_each = toset(local.cognito_user_pool_schema_names)
    content {
      attribute_data_type      = "String"
      developer_only_attribute = false
      mutable                  = true
      name                     = schema.value
      required                 = false
      string_attribute_constraints {}
    }
  }
}

resource "aws_cognito_identity_provider" "entra_oidc" {
  user_pool_id  = aws_cognito_user_pool.entraid.id
  provider_name = "EntraID"
  provider_type = "OIDC"

  provider_details = {
    authorize_scopes          = "openid profile email"
    attributes_request_method = "GET"
    oidc_issuer               = local.issuer
    authorize_url             = local.authorization_endpoint
    token_url                 = local.token_endpoint
    attributes_url            = local.user_info_endpoint
    client_id                 = local.client_id
    client_secret             = local.client_secret
  }

  attribute_mapping = local.attribute_mapping
}

Note that there is a 2048 char limit for mapped Cognito custom attributes!

After creating all the Cognito resources, we can now configure the ALB listener to use Cognito for OIDC authentication. The below is the terraform code snippet for configuring the HTTPS listener:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
resource "aws_lb_listener" "https" {
  load_balancer_arn = aws_lb.alb.arn
  port              = 443
  protocol          = "HTTPS"
  ssl_policy        = "ELBSecurityPolicy-TLS13-1-2-Res-2021-06"
  certificate_arn   = local.certificate_arn

  default_action {
    type = "authenticate-cognito"

    authenticate_cognito {
      user_pool_arn       = aws_cognito_user_pool.entra_pool.arn
      user_pool_client_id = aws_cognito_user_pool_client.entra_client.id
      user_pool_domain    = aws_cognito_user_pool_domain.entra_domain.domain
    }
  }

  default_action {
    type             = "forward"
    target_group_arn = aws_lb_target_group.backend.arn
  }
}

Don’t forget to update the app registration call back URIs with the auth one from Cognito!

Now the ALB listener is configured to use Cognito for OIDC authentication, and Cognito is configured to use Entra ID. Once a user authenticates, the ALB listener forwards the request to Cognito. Cognito then redirects the user to Entra ID. Once the user enters their credentials correctly, Entra ID issues the tokens and redirects the user back to Cognito. Cognito maps the custom attributes that we configured in the Cognito user pool to the custom attributes that we want to forward to the backend application. The ALB listener now adds these custom attributes to the x-amzn-oidc-data header JWT that will be forwarded to the backend application. Below is the ALB Cognito authentication sequence diagram:

  sequenceDiagram
    participant User as User (Browser)
    participant ALB as AWS ALB (HTTPS Listener)
    participant Cognito as Cognito User Pool
    participant Entra ID as Entra ID (Azure AD)
    participant Backend as Backend (Application)
    User ->> ALB: Request resources
    ALB ->> Cognito: Cognito OIDC authentication
    Cognito ->> Entra ID: Entra ID OIDC authentication
    Entra ID -->> Cognito: ID and Access Tokens from Microsoft
    Cognito -->> ALB: Cognito tokens with group memberships such as "custom:roles"
    ALB ->> Backend: ALB x-amzn-oidc-* tokens now contain group memberships via custom:* attributes
    Backend -->> User: Authorize user according to group memberships
    Note right of Cognito: Cognito custom attributes mapping:<br/>"custom:roles" = "roles"<br/>"custom:groups" = "groups"<br/>etc. (additional custom attributes)

Architecture Diagram

Here is the architecture diagram for the above setup:

The user sends an HTTPS request to the ALB listener.
The ALB checks the encrypted AWSELBAuthSessionCookie to see if the user is authenticated.
If the user is authenticated and the credentials have not expired, the ALB forwards the request to the backend application.
If the user is not authenticated, the ALB redirects to Cognito.
Cognito redirects the user to Entra ID.
Entra ID issues the ID and access tokens and redirects the user back to Cognito.
Cognito issues new ID and access tokens where the custom attributes that we configured in the Cognito user pool are mapped to the Microsoft ID token claim that we want to forward to the backend application.
The ALB listener adds these custom attributes to the x-amzn-oidc-data header JWT that will be forwarded to the backend application.
The ALB forwards the request to the backend application.

Debugging ALB Headers

We mapped one of the ALB target groups to a Lambda function that prints the headers that are forwarded to the backend application. The below is the Lambda function code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
export const handler = async (event) => {
    if (event.path === "/health") {
        return {
            statusCode: 200,
            statusDescription: "200 OK",
            isBase64Encoded: false,
            headers: {
                "content-type": "application/json"
            },
            body: JSON.stringify({status: "ok"})
        };
    }

    const response = {
        statusCode: 200,
        statusDescription: "200 OK",
        isBase64Encoded: false,
        headers: {
            "content-type": "application/json"
        },
        body: JSON.stringify({
            message: "Hello from Lambda!",
            headers: event.headers
        }, null, 2),
    };

    return response;
};

Here is the browser Lambda function response containing all the headers that are forwarded to the backend application:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "message": "Hello from Lambda!",
  "headers": {
    "accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7",
    "accept-encoding": "gzip, deflate, br, zstd",
    "accept-language": "en-GB,en;q=0.9",
    "cache-control": "max-age=0",
    "cookie": "AWSALBAuthNonce=yRxRypFZxo6WVJ5r",
    "host": "myapp.aws.cloud",
    "priority": "u=0, i",
    "referer": "https://login.microsoftonline.com/",
    "sec-ch-ua": "\"Opera\";v=\"131\", \"Not.A/Brand\";v=\"8\", \"Chromium\";v=\"147\"",
    "sec-ch-ua-mobile": "?0",
    "sec-ch-ua-platform": "\"macOS\"",
    "sec-fetch-dest": "document",
    "sec-fetch-mode": "navigate",
    "sec-fetch-site": "cross-site",
    "sec-fetch-user": "?1",
    "upgrade-insecure-requests": "1",
    "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36 OPR/131.0.0.0",
    "x-amzn-oidc-accesstoken": "eyJra..",
    "x-amzn-oidc-data": "eyJ0..",
    "x-amzn-oidc-identity": "6a39920f-22f1-80c5-a800-5ff93f246878",
    "x-amzn-trace-id": "Root=1-93745822-6b42af092447ea692bdc5848",
    "x-forwarded-for": "MY_IP_ADDRESS",
    "x-forwarded-port": "443",
    "x-forwarded-proto": "https"
  }
}

Let’s check the x-amzn-oidc-data header to see if the custom attributes that we mapped from the Microsoft ID token claims are forwarded to the backend application. Here is a decoded x-amzn-oidc-data JWT:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "typ": "JWT",
  "kid": "bc1052be-9015-45ab-9cd0-d59f70cd3d58",
  "alg": "ES256",
  "iss": "https://login.microsoftonline.com/AZURE_AD_TENANT_ID/v2.0",
  "client": "Azure_Application_Client_ID",
  "signer": "arn:aws:elasticloadbalancing:eu-central-1:123456789012:loadbalancer/...",
  "exp": 1782336016
}.{
  "sub": "...",
  "email_verified": "false",
  "custom:nbf": "Wed Jun 24 20:55:55 UTC 2026",
  "custom:preferred_username": "email@domain.com",
  "custom:aud": "[Azure_Application_Client_ID]",
  "custom:tid": "AZURE_AD_TENANT_ID5",
  "custom:oid": "44df6ec6-99d3-4816-8e87-f4f58dc93194",
  "custom:groups": "[\"bfb757fa-2c21-4b60-98f2-a1e0fd6c1435\"]",
  "custom:ver": "2.0",
  ...
}.[
  Signature
]

All the custom attributes that we mapped from the Microsoft ID token claims are now forwarded to the backend application. We used Cognito as a federated OIDC provider for the ALB listener.

Conclusion

In this post, we discussed how to configure the AWS ALB listener to use Cognito for OIDC authentication and how to configure Cognito to map custom attributes from the Microsoft ID token claims to be forwarded to the ALB tokens. This solved the problem of the disappearing ID token along with its group memberships claim that can be used by the backend for AuthZ as described in the first post.

Microsoft ID token with claims
              |
              | (e.g. groups)
              V
Cognito idToken with custom attributes mapping
              |
              | (e.g. "custom:groups" = "groups")
              V
ALB x-amzn-oidc-data token with custom:groups and other custom attributes
              |
              | x-amzn-oidc-* tokens forwarded
              V
Backend application receives all mapped custom attributes

References: