How to include custom claims (acr, amr, etc.) directly inside Stateless JWT Access Tokens?

[dairoca90]

Hello everyone,

I am testing stateless OAuth2 tokens in OpenAM/OpenIdentityPlatform and I have a question regarding custom claims in JWT access tokens.

After enabling:

Use Stateless Access & Refresh Tokens

in the OAuth2 Provider configuration, the generated access token is correctly returned as a signed JWT.

However, I noticed that claims added through:

• OIDC claims scripts
• OAuth2 script plugins
• custom scope/claim mappings

are not embedded directly inside the generated stateless JWT access token.

For example, the generated id_token correctly contains custom claims such as:

{
  "sub": "demo",
  "some": "value",
  "acr": "ldap"
}

But the generated access_token JWT only contains standard fields:

{
  "sub": "demo",
  "scope": "some openid",
  "aud": "sdkPublicClient",
  "exp": 1779584967
}

Even though the same authentication flow was used, the access token does not include:

• acr
• amr
• some
• or any custom claims added through the OIDC claims script.

The custom claims do appear correctly when using:

• /oauth2/tokeninfo
• /oauth2/userinfo

which makes me think the scripting is working correctly, but only for:

• ID Tokens
• UserInfo responses
• TokenInfo responses

and not for stateless JWT access tokens themselves.

My main goal is to allow downstream APIs, gateways, and policy enforcement points to:

• validate the JWT signature locally
• evaluate authentication assurance (acr, amr)
• avoid calling /tokeninfo or /userinfo on every request

Ideally, I would like the generated access token to contain claims such as:

{
  "acr": "iot",
  "amr": ["pwd", "otp"]
}

I already tested:

• acr_values during authorization requests
• OIDC claims scripts
• OAuth2 script plugins
• custom scope mappings

but the claims still do not appear inside the stateless JWT access token payload.

So my questions are:

1. Is this the expected/default behavior for stateless JWT access tokens?
2. Are stateless access tokens intentionally limited to a fixed set of claims?
3. Is there a supported mechanism (for example an Access Token modification script) to inject custom claims directly into the JWT access token?

Any guidance would be greatly appreciated.

[maximthomas]

Hi @dairoca90,

1. This is the expected behavior, an access token is just an identifier to retrieve users info from the server.
2. Access token claim are limited to a fixed set of claims.
3. Unfortunately, there is no built-in mechanism to inject custom claims. However, you can modify or extend the StatelessTokenStore class to extend the supported claims list.

[dairoca90]

Thank you for the clarification.

I understand that stateless access tokens are intentionally limited and that custom claims are not injected through the standard OIDC claims scripting pipeline.

However, after reviewing the StatelessTokenStore implementation, I noticed something that confuses me a bit regarding the intended design.

Inside createRefreshToken(), the stateless JWT refresh token explicitly persists authentication context information such as:

• ACR
• AUTH_MODULES (effectively AMR/auth modules)
• validated claims

For example:

claimsSetBuilder.claim(AUTH_MODULES, authModules);

claimsSetBuilder.claim(ACR, acr);

OpenAM/openam-oauth2/src/main/java/org/forgerock/openam/oauth2/StatelessTokenStore.java

Line 451 in f521ba4

public RefreshToken createRefreshToken(String grantType, String clientId, String resourceOwnerId,

String authModules = null;
        String acr = null;
        AuthorizationCode authorizationCode = request.getToken(AuthorizationCode.class);
        if (authorizationCode != null) {
            authModules = authorizationCode.getAuthModules();
            acr = authorizationCode.getAuthenticationContextClassReference();
        }

        RefreshToken currentRefreshToken = request.getToken(RefreshToken.class);
        if (currentRefreshToken != null) {
            authModules = currentRefreshToken.getAuthModules();
            acr = currentRefreshToken.getAuthenticationContextClassReference();
        }

        if (authModules != null) {
            claimsSetBuilder.claim(AUTH_MODULES, authModules);
        }
        if (acr != null) {
            claimsSetBuilder.claim(ACR, acr);
        }

This makes me wonder:

If authentication assurance/context data is considered important enough to be embedded directly inside stateless refresh tokens, why is the same information intentionally omitted from stateless access tokens?

From an OAuth2/OIDC architecture perspective, downstream APIs, gateways, and policy enforcement points are usually the components that need to evaluate:

• authentication strength
• MFA usage
• assurance level
• step-up context

and those systems normally only receive the access token.

So I am trying to better understand the intended design rationale here.

Would it be correct to say that:

1. The omission of acr/amr from stateless access tokens is mainly an implementation limitation of StatelessAccessToken generation rather than a strict architectural/security decision?

2. If acr/auth modules are already trusted enough to persist inside refresh token JWTs, then propagating them into access tokens should also be considered safe/consistent?

3. Or alternatively, should refresh tokens also avoid carrying those claims for consistency?

I just want to confirm whether this asymmetry between refresh token claims and access token claims is intentional by design or simply an artifact of the current implementation.

Thanks again for your help.

[maximthomas]

Hi @dairoca90,

This functionality is inherited from ForgeRock and by design.

We suggest some workarounds:

1. Call /oauth2/tokeninfo or /oauth2/userinfo as you have already suggested.

2. Add a quick patch - extract acr and amr from AuthorizationCode / RefreshToken directly into the access token (it's simple since this is already done for refresh tokens).

3. Create a new OAUTH2_ACCESS_TOKEN_MODIFICATION script type, like in ForgeRock AM 6.5.

If you want to help - we'd appreciate a PR from you!