AWS Application Load Balancer

Running Stroom behind an AWS Application Load Balancer that authenticates users against Amazon Cognito, Microsoft Entra ID or any other Open ID Connect provider.

Tags:

In this deployment the Application Load Balancer is the Open ID Connect Relying Party. Its listener rule sends unauthenticated browsers to the Identity Provider (IDP) Identity Provider (IDP) An Identity Provider is a system or service that can authenticate a user and assert their identity. Identity providers can support single sign on (SSO), which allows the user to sign in once to the Identity Provider so they are then authenticated to all systems using that IDP.Click to see more details..., completes the code flow, holds the session in AWSELBAuthSessionCookie cookies, and forwards each authenticated request to Stroom with three extra headers:

Header	Contents
`x-amzn-oidc-data`	The user’s claims as a JWT, signed by the ALB with a regional AWS key (ES256)
`x-amzn-oidc-accesstoken`	The access token from the IDP, in plain text
`x-amzn-oidc-identity`	The `sub` claim, in plain text

Stroom authenticates the request by verifying the x-amzn-oidc-data signature against AWS’s regional public key endpoint, checking the token’s issuer against the configured one, and checking that the signing load balancer is one of yours.

The ALB can authenticate against an Amazon Cognito user pool (an authenticate-cognito rule) or against any OIDC provider directly (an authenticate-oidc rule). Stroom does not care which: the token it verifies is minted and signed by the ALB either way. What the IDP changes is covered in What Depends on the IDP, with worked examples for Cognito and Entra ID below.

How the ALB Builds the Token

It matters where the claims in x-amzn-oidc-data come from, because it is not where the External IDP pages assume.

After exchanging the authorization code, the ALB sends the access token to the IDP’s user info endpoint and signs the claims that come back. The ID token is discarded; nothing from it reaches Stroom. The payload therefore contains only what the IDP’s user info endpoint returns, which is typically a small subset of the ID token’s claims, plus an iss and exp that the ALB adds.

Two consequences for the Stroom configuration:

uniqueIdentityClaim and userDisplayNameClaim must name claims that the user info endpoint returns. A claim that is only in the ID token, such as Entra ID’s oid, cannot be used.
Stroom checks the payload’s iss against the issuer from openIdConfigurationEndpoint, so the issuer the ALB is configured with must be exactly the one the IDP’s discovery document advertises.

Load Balancer Setup

The authenticate-cognito and authenticate-oidc actions are only supported on an HTTPS listener.

Order the listener rules so machine traffic and the post logout page are served without authentication, then authenticate everything else:

Paths /datafeed*, /stroom/datafeed*, /remoting/*, /status → forward to the Stroom target group.

Path /signed-out → fixed-response with status 200, content type text/html and body:

<html><body><p>You have been signed out.</p><p><a href="/">Sign in again</a></p></body></html>

Default → authenticate-cognito or authenticate-oidc (see the IDP sections below) then forward to the Stroom target group.

The /signed-out rule is the landing page for logout. Stroom does not serve one of its own, and it must be a page the authenticate rule does not cover, so the load balancer answers it directly.

Points worth knowing:

SessionCookieName defaults to AWSELBAuthSessionCookie; if you change it, change edgeAuthentication.logout.cookiesToExpire to match.
The session cookie is sharded at 4KB per shard (-0, -1, …), which is why the header size limit matters.
If the total claims and access token exceed 11KB the ALB itself returns HTTP 500 and increments its ELBAuthUserClaimsSizeExceeded metric — trim what the IDP puts in the token if you hit this.
The ALB holds the IDP client secret, so the secret’s rotation is now a listener rule change, not a Stroom one.
Restrict the Stroom target’s security group to accept traffic only from the ALB’s security group; this is trust prerequisite one.

Stroom Configuration

The parts that do not depend on the IDP:

server:
  applicationConnectors:
    - type: http
      port: 8080
      useForwardedHeaders: true
      maxRequestHeaderSize: 32KiB

appConfig:
  publicUri: "https://STROOM_FQDN"    # the ALB's public address
  security:
    authentication:
      edgeAuthentication:
        enabled: true
        logout:
          cookiesToExpire: [ "AWSELBAuthSessionCookie" ]
          signOutUrl: "IDP_SIGN_OUT_URL"    # see the IDP sections below
      openId:
        identityProviderType: EXTERNAL_IDP
        # The IDP's discovery document; supplies the issuer that x-amzn-oidc-data is
        # checked against. Stroom runs no flow of its own, so no clientSecret is needed.
        openIdConfigurationEndpoint: "IDP_DISCOVERY_URL"
        # The ALB's client at the IDP.
        clientId: "ALB_CLIENT_ID"
        # MANDATORY - pins the JWT's 'signer' header to your load balancer(s).
        # Without it, every x-amzn-oidc-data token is rejected. Each value must reach at
        # least the account id; use the full ALB ARN where you know it.
        expectedSignerPrefixes:
          - "arn:aws:elasticloadbalancing:REGION:ACCOUNT_ID:"

`expectedSignerPrefixes`

The regional AWS endpoint that Stroom fetches verification keys from serves the keys of every load balancer in that region, so the signature alone proves a token came from an ALB, not from your ALB. This setting closes that gap: the signer field in the token’s header, which is the signing load balancer’s ARN, must start with one of the configured values.

It is required — with it unset, every ALB token is rejected, and the log message names this property.

`publicKeyUriPattern`

The default value fetches keys from https://public-keys.auth.elb.${awsRegion}.amazonaws.com/${keyId}, which is correct for the commercial AWS regions. AWS GovCloud serves the keys from different, S3 hosted endpoints, so GovCloud deployments must override it, e.g.:

        publicKeyUriPattern: "https://s3-us-gov-west-1.amazonaws.com/\
aws-elb-public-keys-prod-us-gov-west-1/${keyId}"

What Depends on the IDP

	Amazon Cognito	Microsoft Entra ID	Other OIDC provider
ALB action	`authenticate-cognito`	`authenticate-oidc`	`authenticate-oidc`
Client registration	User pool app client	App registration	Per provider
Claims in `x-amzn-oidc-data`	`sub`, `username`, `email`	v2.0: `sub`, `name`, `given_name`, `family_name`, `email`; v1.0: `sub`, `oid`, `tid`, name claims	Whatever the user info endpoint returns
`uniqueIdentityClaim`	`sub` (default)	`sub` (default), or `oid` on v1.0	`sub` (default)
`userDisplayNameClaim`	`username` or `email`	`email` or `name`	Check the user info claims
`signOutUrl`	Hosted UI `/logout`	`oauth2/v2.0/logout`	The end session endpoint

The default userDisplayNameClaim of preferred_username is not returned by either Cognito’s or Entra ID’s user info endpoint, so set it explicitly, or users will sign in with no display name.

Logout

AWS documents ending an ALB session as the application’s job: expire the session cookies and send the browser to the IDP’s logout endpoint. The Stroom configuration above does exactly that — cookiesToExpire removes the AWSELBAuthSessionCookie shards and signOutUrl sends the browser to the IDP.

The IDP then returns the browser to a landing page, which is the /signed-out fixed response in the listener rules. Two things must be true of it:

It must be served by a rule that comes before the authenticate rule, or the sign in flow simply restarts and the user never appears to sign out.
Its full URL, https://STROOM_FQDN/signed-out, must be registered with the IDP as an allowed post logout destination; the sections below say where.

Amazon Cognito

Cognito Setup

Create a user pool, hosted UI domain and app client as described on the Cognito page, with these differences:

The app client belongs to the ALB, not to Stroom, so its allowed callback URL is the ALB’s own: https://STROOM_FQDN/oauth2/idpresponse (this fixed path is handled by the load balancer itself and never reaches Stroom).
The client must have a client secret and use the code grant; the ALB requires both.
Register https://STROOM_FQDN/signed-out as an allowed sign out URL for the client.

No second app client for Stroom is needed. The ALB is the only OIDC client in this topology.

Listener Rule

The default rule is an authenticate-cognito action naming your user pool, app client and hosted UI domain, followed by a forward to the Stroom target group. Cognito’s default openid scope returns an ID token, which the ALB needs to complete the flow; email and profile add the claims of the same name.

Stroom Configuration for Cognito

      edgeAuthentication:
        enabled: true
        logout:
          cookiesToExpire: [ "AWSELBAuthSessionCookie" ]
          signOutUrl: "https://MY_DOMAIN.auth.REGION.amazoncognito.com/logout?\
client_id=ALB_CLIENT_ID&logout_uri=https://STROOM_FQDN/signed-out"
      openId:
        identityProviderType: EXTERNAL_IDP
        openIdConfigurationEndpoint: "https://cognito-idp.REGION.amazonaws.com/\
POOL_ID/.well-known/openid-configuration"
        clientId: "ALB_CLIENT_ID"
        expectedSignerPrefixes:
          - "arn:aws:elasticloadbalancing:REGION:ACCOUNT_ID:"
        # Cognito's user info endpoint returns 'username' and 'email', not 'preferred_username'.
        userDisplayNameClaim: "username"

The default uniqueIdentityClaim of sub is correct and stable.

Microsoft Entra ID

App Registration

Create an app registration as described under Creating the App Registration, with these differences:

The registration belongs to the ALB, so the Web platform redirect URI is https://STROOM_FQDN/oauth2/idpresponse, not Stroom’s signin-oidc callback.
Add https://STROOM_FQDN/signed-out as a second Web redirect URI; Entra ID requires the post_logout_redirect_uri to be registered.
A client secret is required, and it goes in the listener rule rather than Stroom’s configuration. Entra ID secrets expire, with a maximum lifetime of 24 months; when this one does, the ALB can no longer complete sign in for anyone, so record the date.

The Exposing an API for Access Tokens step is not needed for browser sign in. The access token Entra ID gives the ALB is a Microsoft Graph token, and the ALB only uses it to call Graph’s user info endpoint, which is exactly what it is for. It is still needed if Stroom-Proxies or other machine clients obtain Entra ID tokens to present to Stroom directly, as that traffic does not go through the ALB’s authenticate rule.

Use a single tenant registration. The example below uses the v2.0 endpoints, as the Entra ID page recommends, but behind an ALB the choice of endpoint generation decides which claims Stroom gets, so read Identity Claims before settling on it.

Listener Rule

The default rule is an authenticate-oidc action, followed by a forward to the Stroom target group. Entra ID’s discovery document does not need to be, and cannot be, given to the ALB; the endpoints are entered individually:

{
    "Type": "authenticate-oidc",
    "AuthenticateOidcConfig": {
        "Issuer": "https://login.microsoftonline.com/TENANT_ID/v2.0",
        "AuthorizationEndpoint": "https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize",
        "TokenEndpoint": "https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/token",
        "UserInfoEndpoint": "https://graph.microsoft.com/oidc/userinfo",
        "ClientId": "ALB_CLIENT_ID",
        "ClientSecret": "ALB_CLIENT_SECRET",
        "Scope": "openid profile email offline_access",
        "OnUnauthenticatedRequest": "authenticate"
    },
    "Order": 1
}

Issuer must be exactly https://login.microsoftonline.com/TENANT_ID/v2.0, with the /v2.0 and no trailing slash. It becomes the iss claim of x-amzn-oidc-data, and Stroom checks it against the issuer from the v2.0 discovery document, so any difference rejects every request.
Scope must include profile and email, otherwise the user info endpoint returns only sub. offline_access makes Entra ID issue a refresh token, which the ALB uses to renew the session silently; without it every user is bounced back through Entra ID when the access token expires, typically hourly.
The user info endpoint is on graph.microsoft.com, not login.microsoftonline.com, so the ALB needs outbound access to both.

Identity Claims

The v1.0 and v2.0 generations of Entra ID endpoint have different user info endpoints, and they return different claims. Because the ALB signs the user info claims and discards the ID token, this decides which identity claims Stroom can use:

	v2.0 endpoints	v1.0 endpoints
User info endpoint	`https://graph.microsoft.com/oidc/userinfo`	`https://login.microsoftonline.com/TENANT_ID/openid/userinfo`
Claims returned	`sub`, `name`, `given_name`, `family_name`, `picture`, `email`	`sub`, `oid`, `tid` and the v1.0 name claims, but not `email`
`uniqueIdentityClaim`	`sub` only; `oid` is not returned	`sub` or `oid`
Issuer	`https://login.microsoftonline.com/TENANT_ID/v2.0`	`https://sts.windows.net/TENANT_ID/`

Neither returns preferred_username, so userDisplayNameClaim must be set explicitly either way, and the default fullNameClaimTemplate of ${name} works with both given the profile scope.

With the v2.0 endpoints uniqueIdentityClaim must be left at the default of sub. With uniqueIdentityClaim: "oid" copied from the Entra ID page, every request is rejected and the log says Expecting claims to contain configured uniqueIdentityClaim 'oid' but it is not there, followed by the claims that did arrive. In Entra ID sub is pairwise, i.e. specific to the app registration, and stable for as long as that registration exists. Deleting and recreating the ALB’s app registration changes every user’s sub and orphans their Stroom user, so treat the registration as permanent.

With the v1.0 endpoints oid is available, which is the durable identifier the Entra ID page recommends, and the one an existing Stroom that used to be Entra ID’s own client will already be keyed on. It also means users can be created in Stroom before they first sign in, because oid can be read from the directory, which pairwise sub cannot. The cost is that v1.0 is the legacy generation of the platform, and its user info endpoint does not return email. The full configuration is under Using the v1.0 Endpoints.

Whichever generation you pick, check what actually arrives before the first user signs in, with the DEBUG logging described under Setting up the Admin User, and decide the identity claim then. Changing it later orphans every user.

Warning

Moving an existing Stroom from being Entra ID’s client itself to sitting behind the ALB on the v2.0 endpoints changes every user’s identity: they were known by oid (or by the sub pairwise to Stroom’s own app registration) and are now known by the sub pairwise to the ALB’s. None of the existing Stroom users will match, so their permissions and group memberships have to be reapplied to the new identities. Plan this before switching, rather than discovering it when the administrator signs in to an empty UI. Using the v1.0 endpoints with uniqueIdentityClaim: "oid" avoids this for a Stroom that was already keyed on oid.

Stroom Configuration for Entra ID

      edgeAuthentication:
        enabled: true
        logout:
          cookiesToExpire: [ "AWSELBAuthSessionCookie" ]
          signOutUrl: "https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/logout?\
post_logout_redirect_uri=https://STROOM_FQDN/signed-out"
      openId:
        identityProviderType: EXTERNAL_IDP
        # Note the '/v2.0' path part, which must agree with the listener rule's Issuer.
        openIdConfigurationEndpoint: "https://login.microsoftonline.com/TENANT_ID/v2.0/\
.well-known/openid-configuration"
        clientId: "ALB_CLIENT_ID"
        expectedSignerPrefixes:
          - "arn:aws:elasticloadbalancing:REGION:ACCOUNT_ID:"
        # Entra ID's user info endpoint does not return 'preferred_username'.
        userDisplayNameClaim: "email"

Compared with the Entra ID page’s configuration, there is no clientSecret, validIssuers, allowedAudiences, requestScopes or uniqueIdentityClaim: oid. Stroom runs no flow, only v2.0 tokens are ever involved, the ALB’s token carries no audience, the scopes are set on the listener rule, and oid is not returned by the v2.0 user info endpoint. For the v1.0 variant, see Using the v1.0 Endpoints.

Using the v1.0 Endpoints

The same app registration works for either generation; nothing in the registration selects v1.0 or v2.0. What changes is the listener rule, which names the v1.0 endpoints, and the Stroom configuration, which has to accept the v1.0 issuer.

The v1.0 endpoints support only the openid scope; profile, email and offline_access are v2.0 concepts. The user info endpoint returns the name claims regardless, and the code flow returns a refresh token without being asked, so the ALB can still renew the session silently.

{
    "Type": "authenticate-oidc",
    "AuthenticateOidcConfig": {
        "Issuer": "https://sts.windows.net/TENANT_ID/",
        "AuthorizationEndpoint": "https://login.microsoftonline.com/TENANT_ID/oauth2/authorize",
        "TokenEndpoint": "https://login.microsoftonline.com/TENANT_ID/oauth2/token",
        "UserInfoEndpoint": "https://login.microsoftonline.com/TENANT_ID/openid/userinfo",
        "ClientId": "ALB_CLIENT_ID",
        "ClientSecret": "ALB_CLIENT_SECRET",
        "Scope": "openid",
        "OnUnauthenticatedRequest": "authenticate"
    },
    "Order": 1
}

Issuer must be exactly https://sts.windows.net/TENANT_ID/, including the trailing slash; it is what the v1.0 discovery document advertises and what Stroom checks the token’s iss against.

      edgeAuthentication:
        enabled: true
        logout:
          cookiesToExpire: [ "AWSELBAuthSessionCookie" ]
          signOutUrl: "https://login.microsoftonline.com/TENANT_ID/oauth2/logout?\
post_logout_redirect_uri=https://STROOM_FQDN/signed-out"
      openId:
        identityProviderType: EXTERNAL_IDP
        # The v1.0 discovery document: no '/v2.0' path part.
        openIdConfigurationEndpoint: "https://login.microsoftonline.com/TENANT_ID/\
.well-known/openid-configuration"
        clientId: "ALB_CLIENT_ID"
        expectedSignerPrefixes:
          - "arn:aws:elasticloadbalancing:REGION:ACCOUNT_ID:"
        # The v1.0 issuer shares no base URI with the discovery endpoint, so Stroom refuses
        # to start unless it is listed here; see the Entra ID page. With validIssuers set,
        # the discovery document's issuer must be in the list, which this one is.
        validIssuers:
          - "https://sts.windows.net/TENANT_ID/"
        # The v1.0 user info endpoint returns 'oid', so the durable identifier is available.
        uniqueIdentityClaim: "oid"
        # It does not return 'email' or 'preferred_username'.
        userDisplayNameClaim: "name"

The differences from the v2.0 configuration are the oauth2/logout sign out endpoint (no v2.0), the discovery document, validIssuers, and the two claim settings. https://STROOM_FQDN/signed-out still has to be registered as a redirect URI in the app registration.

With oid as the identity, the administrator can be set up before anyone signs in, exactly as on the Entra ID page: the Object ID is shown on the user’s page in the Entra admin centre. The sign in first procedure under Setting up the Admin User is only needed for sub.

Setting up the Admin User

With the v2.0 endpoints the identity is the pairwise sub, and that cannot be looked up in advance: it is computed by Entra ID for each app registration, is not exposed by the Graph API or the admin centre, and only ever appears in a token issued for that user to that client. Any process that reads identities from the directory and pre-creates Stroom users, as is possible with oid, does not work with sub. Users have to sign in first, which creates their Stroom user, and be granted permissions afterwards.

For the first administrator:

Have them sign in once through the ALB. Stroom creates a user with name set to their sub and display_name set to the email claim, with no permissions.

Read the sub from the database:

SELECT name FROM stroom_user WHERE display_name = 'admin@example.com' AND is_group = 0;

Grant permissions with manage_users as described under Setting up the Admin User in Stroom, using that value as the subject id. The command is repeatable, so running it against a user that already exists is fine.

Once one administrator exists, further users can be found under Users in the UI after their first sign in, or a script can find them by display name with POST /api/users/v1/find and add them to groups with PUT /api/users/v1/{userUuid}/{groupUuid}, matched on the email address the directory reports for them.

If the sub is not where you expect, the logger stroom.security.common.impl.StandardJwtContextFactory at DEBUG logs the claims of every token Stroom verifies.

Migrating Existing Users

A Stroom that was Entra ID’s own client already has users keyed on oid, or on the sub pairwise to Stroom’s app registration. Behind the ALB on the v2.0 endpoints those users will never be matched again; on the v1.0 endpoints with uniqueIdentityClaim: "oid" they will, and nothing needs migrating.

To migrate to the v2.0 identities, each user signs in once, which creates an empty user keyed on their new sub, and their groups and permissions are then copied across from the old user:

Find the old user’s UUID: GET /api/users/v1/fetchBySubjectId/{oid}.
Find the new user’s UUID by display name, as above. The old user’s display name is the UPN (the preferred_username claim) and the new one’s is the email claim; where those differ in your tenant, resolve oid to mail with the Graph API.
POST /api/users/v1/{newUserUuid}/copyPermissions with the old user’s UUID as the body. This copies group memberships, application permissions and document permissions, and is the same operation as Copy Permissions in the Users screen.
Disable the old user.

Ownership of things such as API keys and processor filters is not copied, as it is tied to the user’s UUID rather than its permissions; recreate those against the new user where needed.

Other OIDC Providers

Any provider the ALB can reach works the same way as Entra ID: an authenticate-oidc rule with the provider’s issuer and endpoints, and the generic Stroom configuration with the provider’s discovery document. Check three things against the provider’s documentation:

The Issuer on the rule is exactly the issuer its discovery document advertises.
What its user info endpoint returns, and set userDisplayNameClaim accordingly.
What its end session endpoint is called, what parameter it takes for the return address, and whether that address must be registered.

Verifying it Works

After deploying, load Stroom in a browser and check, in the developer tools network tab:

You are redirected to the IDP’s sign in page, sign in, and land back at Stroom.
The request to /api/auth/flow/v1/status returns 200 with "authenticated": true and the UI loads.
There is no further navigation to the IDP’s authorization endpoint (.../oauth2/authorize for Cognito, .../oauth2/v2.0/authorize for Entra ID) after that first sign in — if there is, Stroom is running a second flow and edgeAuthentication.enabled is not set.
Signing out lands on the You have been signed out page, and following its link asks you to sign in again.

On the Stroom side, the log should not contain Redirecting with an AuthenticationRequest to: during normal browsing.

If every request is rejected with Authenticated user is not permitted to use stroom, set the logger stroom.security.common.impl.StandardJwtContextFactory to DEBUG: it logs the raw x-amzn-oidc-data token (jws:) and why verification failed. Decode the token’s header and payload (base64 JSON, the first and second dot separated segments) and compare the payload’s iss with the issuer in the discovery document at openIdConfigurationEndpoint, and the header’s signer with expectedSignerPrefixes.

Last modified September 22, 2026: Merge pull request #142 from gchq/edge-proxy (8ba264a)

AWS Application Load Balancer

Tags:

See Also

How the ALB Builds the Token

Load Balancer Setup

Stroom Configuration

`expectedSignerPrefixes`

`publicKeyUriPattern`

What Depends on the IDP

Logout

Amazon Cognito

See Also

Cognito Setup

Listener Rule

Stroom Configuration for Cognito

Microsoft Entra ID

See Also

App Registration

Listener Rule

Identity Claims

Warning

Stroom Configuration for Entra ID

Using the v1.0 Endpoints

Setting up the Admin User

Migrating Existing Users

Other OIDC Providers

Verifying it Works