Introspection doesn't reflect the access token when using a custom protocol mapper that uses httpRequest attributes as claims #45535

Darkness4 · 2026-01-16T14:53:02Z

Darkness4
Jan 16, 2026

Hello,

We plan to use the "lightweight access token" feature, and use Token Introspection to fetch all the claims.

However, before we did this, I tested the Token Introspection without an "lightweight access token" and found a weird behavior where the given JWT and claims from the introspection doesn't reflect the access token claims at issuance.

The setup is the following:

1 OAuth Client is configured with JWT Authorization Grant+Client Credentials (Service Account Roles)
1 OAuth Client is configured with Client Credentials just for introspection. ("Support JWT claim in Introspection Response" is enabled, all scopes removed)

In our use-case, we want the claim embed_context from the assertion JWT to be mapped to the access token. Since the JWT Authorization Grant Identity Provider doesn't have any mapper to map claims from the assertion JWT to the access token, we did a JS Custom Protocol Mapper, which looks like this:

embed-context-mapper.js (click me)

var HashMap = Java.type('java.util.HashMap');
var ArrayList = Java.type('java.util.ArrayList');
var JWSInput = Java.type('org.keycloak.jose.jws.JWSInput');

function objectToHashMap(obj) {
  var map = new HashMap();
  for (var key in obj) {
    if (obj.hasOwnProperty(key)) {
      var value = obj[key];

      // Handle nested objects recursively
      if (
        value !== null &&
        typeof value === 'object' &&
        !Array.isArray(value)
      ) {
        value = objectToHashMap(value);
      }
      // Handle arrays
      else if (Array.isArray(value)) {
        value = arrayToArrayList(value);
      }

      map.put(key, value);
    }
  }
  return map;
}

function arrayToArrayList(arr) {
  var list = new ArrayList();
  for (var i = 0; i < arr.length; i++) {
    var item = arr[i];
    if (item !== null && typeof item === 'object' && !Array.isArray(item)) {
      item = objectToHashMap(item);
    } else if (Array.isArray(item)) {
      item = arrayToArrayList(item);
    }
    list.add(item);
  }
  return list;
}

exports = (function () {
  'use strict';

  // Configuration
  var DEBUG = true;

  function log(message) {
    if (DEBUG) {
      print('[EmbedContextMapper] ' + message);
    }
  }

  log('Starting');

  try {
    // Get HTTP request context
    var httpRequest = keycloakSession.getContext().getHttpRequest();
    if (!httpRequest) {
      log('No HTTP request context available');
      return null;
    }

    if (typeof token !== 'undefined' && token) {
      log('Found token');
      log(token);
      var existingClaim = token.getOtherClaims().get('embed_context');
      if (existingClaim) {
        log('Found existing embed_context in token');
        return existingClaim;
      }
    }

    if (typeof tokenResponse !== 'undefined' && tokenResponse) {
      log('Found tokenResponse');
      log(tokenResponse);
      var existingClaim = tokenResponse.getOtherClaims().get('embed_context');
      if (existingClaim) {
        log('Found existing embed_context in tokenResponse');
        return existingClaim;
      }
    }

    var assertion = null;

    // Try to get from form parameters (POST)
    if (!assertion) {
      var formParams = httpRequest.getDecodedFormParameters();
      if (formParams && formParams.containsKey('assertion')) {
        assertion = formParams.getFirst('assertion');
        log('Found in form parameters');
      }
    }

    // If not found, try query parameters (GET)
    if (!assertion) {
      var queryParams = httpRequest.getUri().getQueryParameters();
      if (queryParams && queryParams.containsKey('assertion')) {
        assertion = queryParams.getFirst('assertion');
        log('Found in query parameters');
      }
    }

    if (!assertion) {
      log("'assertion' not found");
      return null;
    }

    var jwsInput = new JWSInput(assertion);
    var payloadString = jwsInput.readContentAsString();
    var payload = JSON.parse(payloadString);

    var embedContext = payload.embed_context;
    if (!embedContext) {
      log("Parameter 'embed_context' not found in assertion assertion");
      return null;
    }

    if (typeof token !== 'undefined' && token) {
      token.getOtherClaims().put('embed_context', embedContext);
    }

    if (typeof tokenResponse !== 'undefined' && tokenResponse) {
      tokenResponse.getOtherClaims().put('embed_context', embedContext);
    }

    // Add claim
    log(JSON.stringify(embedContext));
    log('Completed successfully');

    return objectToHashMap(embedContext);
  } catch (error) {
    log('ERROR: ' + error);
    if (error.stack) {
      log('Stack trace: ' + error.stack);
    }
    return null;
  }
})();

Basically, it fetches the assertion in the request parameter, which is given during JWT Authorization Grant, parse the JWT, fetch the embed_context claim and put it in the access token using exports = ....

The mapper DOES work at the access token issuance (POST /protocol/openid-connect/token). But the introspection doesn't (POST /protocol/openid-connect/token/introspect).

Here's a demo:

example.py (click me)

import jwt
import base64
import requests
import datetime

# Customer generate its assertion claims
path_to_private_key = "./my-pk.pem"
token = {
    "iss": "9601932e-7315-4374-8170-713312f29337-embed",
    "aud": "https://keycloak.example.com/realms/9601932e-7315-4374-8170-713312f29337/protocol/openid-connect/token",
    "iat": datetime.datetime.now(datetime.timezone.utc).timestamp(),
    "exp": datetime.datetime.now(datetime.timezone.utc)
    + datetime.timedelta(seconds=300),
    "jti": "some-unique-id",
    "sub": "domain-i-want-access-sa",  # That's a service account linked to the JWT Assertion Grant IdP
    "embed_context": {
        "attributes": {},
    },
}
with open(path_to_private_key, "rb") as f:
    pk = f.read()
signed_token = jwt.encode(token, pk, algorithm="RS512")


client_id = "domain-i-want-access"
client_secret = "client-secret"
creds = base64.b64encode(f"{client_id}:{client_secret}".encode("utf-8")).decode("utf-8")

# Get access token which can be used to access services behind auth
response = requests.post(
    f"https://keycloak.example.com/realms/9601932e-7315-4374-8170-713312f29337/protocol/openid-connect/token",
    data={
        "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
        "scope": "embed",
        "assertion": signed_token,
    },
    headers={
        "Content-Type": "application/x-www-form-urlencoded",
        "Authorization": f"Basic {creds}",
    },
)

data = response.json()
# If "lightweight token" was enabled, the token is very short
print("access token", jwt.decode(data["access_token"], options={"verify_signature": False}))

# Introspection (which is used by internal services to inspect the access token and fetch the claims)
creds = base64.b64encode(
    f"client-for-introspection:client-secret".encode("utf-8")
).decode("utf-8")
response = requests.post(
    "https://keycloak.example.com/realms/9601932e-7315-4374-8170-713312f29337/protocol/openid-connect/token/introspect",
    headers={
        "Content-Type": "application/x-www-form-urlencoded",
        "Accept": "application/jwt",
        "Authorization": f"Basic {creds}",
    },
    data={"token": data["access_token"]},
)

data = response.json()

print("introspection", data)
print("introspection jwt", jwt.decode(data["jwt"], options={"verify_signature": False}))

The results is something like this (prettyfied):

access token {
  'exp': 1768573620, 
  'iat': 1768573320, 
  'jti': 'trrtag:782a4d62-e4c7-a4c4-06ff-683263966afc', 
  'iss': 'https://keycloak.example.com/realms/9601932e-7315-4374-8170-713312f29337', 
  'aud': 'domain-i-want-access', 
  'sub': 'a15b42da-7cda-409e-980a-3488e9ed7bae', 
  'typ': 'Bearer', 
  'azp': 'domain-i-want-access', 
  'scope': 'embed',
  'tenant_id': '9601932e-7315-4374-8170-713312f29337', 
  'embed_context': {
    'attributes': {}
  }
}

introspection {
  'exp': 1768573620, 
  'iat': 1768573320, 
  'jti': 'trrtag:782a4d62-e4c7-a4c4-06ff-683263966afc', 
  'iss': 'https://keycloak.example.com/realms/9601932e-7315-4374-8170-713312f29337', 
  'aud': 'domain-i-want-access', 
  'sub': 'a15b42da-7cda-409e-980a-3488e9ed7bae', 
  'typ': 'Bearer', 
  'azp': 'domain-i-want-access', 
  'scope': 'embed', 
  'tenant_id': '9601932e-7315-4374-8170-713312f29337', 
  'client_id': 'domain-i-want-access', 
  'username': 'service-account-domain-i-want-access', 
  'token_type': 'Bearer', 
  'active': True, 
  'jwt': '[SIMULATED: see below for claims]'
}

introspection jwt {
  'exp': 1768573620, 
  'iat': 1768573320, 
  'jti': 'trrtag:782a4d62-e4c7-a4c4-06ff-683263966afc', 
  'iss': 'https://keycloak.example.com/realms/9601932e-7315-4374-8170-713312f29337', 
  'aud': 'domain-i-want-access', 
  'sub': 'a15b42da-7cda-409e-980a-3488e9ed7bae', 
  'typ': 'Bearer', 
  'azp': 'domain-i-want-access', 
  'scope': 'embed', 
  'tenant_id': '9601932e-7315-4374-8170-713312f29337'
}

(tenant_id comes from an hardcoded claim mapper from the embed scope).

As you can see, the JWT given from the introspection is not the same from the issuance and is missing the embed_context claim. Based on the logs I suspect the mapper is re-executed at introspection (I think?), which doesn't have the assertion parameter in the httpRequest object.

Is there a way to persist the claims mapped when the access token is issued, so that they can be sent back during introspection? Or do I need to use some kind of external storage to properly map the claim?

If there is no way, can I request for such feature (being able to store properties per access token)?

I tried to store the claims in notes in userSession, keycloakSessiongetContext().getAuthenticationSession(), and define claims in token (global variable ID Token in JS Protocol Mapper) or tokenResponse, but without success, probably because a Client Credentials authentication doesn't create any session.

pragyajoshii · 2026-01-20T07:03:35Z

pragyajoshii
Jan 20, 2026

8000 Hi,

I'm from fintech IT firm and I’ve come across your experience with Keycloak through some of your posts, and I was wondering if you could help us by sharing quick feedback from teams using Keycloak (SSO/IAM, etc.). We’re aiming to understand real-world pain points and feature needs.

The survey is anonymous and takes less than five minutes to complete. Your input would really help us shape better enterprise solutions.

👉 Please find the survey here:
https://forms.gle/kjGBqQUFkuAvzzGV6

Would it be possible for you to share this with your groups as well, so we can gather more responses?

Thanks a lot! 😊

0 replies

Darkness4 · 2026-02-06T16:03:45Z

Darkness4
Feb 6, 2026
Author

Found a workaround using infinispan with persistence.

Added cache-ispn.xml:

<infinispan
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="urn:infinispan:config:15.0 http://www.infinispan.org/schemas/infinispan-config-15.0.xsd"
  xmlns="urn:infinispan:config:15.0">

  <cache-container name="keycloak">
    <transport lock-timeout="60000"/>

    <local-cache name="keycloak-attributes">
      <remote-store xmlns="urn:infinispan:config:store:remote:15.0"
        cache="keycloak-attributes"
        purge="false"
        preload="false"
        segmented="false"
        shared="true"
        raw-values="true">

        <remote-server host="${env.KC_CACHE_REMOTE_HOST:my.infinispan.host}"
          port="${env.KC_CACHE_REMOTE_PORT:11222}" />
        <security>
          <authentication>
            <digest username="${env.KC_CACHE_REMOTE_USERNAME:keycloak}"
              password="${env.KC_CACHE_REMOTE_PASSWORD:password}"
              realm="default" />
          </authentication>
        </security>
      </remote-store>
    </local-cache>
  </cache-container>
</infinispan>

Set the flags for the remote cache:

KC_CACHE : ispn
KC_CACHE_CONFIG_FILE : cache/cache-ispn.xml
KC_CACHE_REMOTE_HOST : my.infinispan.host
KC_CACHE_REMOTE_PASSWORD : ...
KC_CACHE_REMOTE_PORT : 11222
KC_CACHE_REMOTE_TLS_ENABLED : false
KC_CACHE_REMOTE_USERNAME : keycloak

And invoked the cache in the mapper:

var InfinispanConnectionProvider = Java.type('org.keycloak.connections.infinispan.InfinispanConnectionProvider');
var provider = keycloakSession.getProvider(InfinispanConnectionProvider.class);
var cache = provider.getCache('keycloak-attributes')
var assertion = cache.get(jti);

// ... if not found, search in POST params or query params, etc...

if (!assertion) {
  return null;
}
cache.put(jti, assertion);

Which worked. However, I am still not sure about if this is a good solution. For example, I am not sure about distributed-cache vs local-cache. I am also not sure about the flexibility of this solution either.

0 replies

Navigation Menu

Repository navigation

Introspection doesn't reflect the access token when using a custom protocol mapper that uses httpRequest attributes as claims #45535

Uh oh!

{{title}}

Uh oh!

Replies: 2 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Introspection doesn't reflect the access token when using a custom protocol mapper that uses httpRequest attributes as claims #45535

Uh oh!

Darkness4 Jan 16, 2026

Replies: 2 comments

Uh oh!

pragyajoshii Jan 20, 2026

Uh oh!

Darkness4 Feb 6, 2026 Author

Darkness4
Jan 16, 2026

pragyajoshii
Jan 20, 2026

Darkness4
Feb 6, 2026
Author