ZGW JWT tokens Introspection Provider for Keycloak

This provider adds ZGW token verification and parsing to Keycloak. It exposes a realm endpoint that validates HS256-signed ZGW JWTs by looking up the token's client_id in Keycloak and verifying the signature with that client's secret, returning an OAuth2 token introspection response.

Note: This provider exists for backwards compatibility with the self-signed JWT tokens described in the VNG ZGW standard. For new integrations we recommend OAuth2 access tokens issued by your identity provider.

Supported Keycloak version

This provider is built against and supported on Keycloak 26.7.5. Because it compiles against the Keycloak server SPI, deploy it only into a supported Keycloak 26.x server; Keycloak 24.x and older are unsupported.

Overview

Introspection endpoint:

• Requires a client_id claim
• Resolves the Keycloak client by client_id and verifies the HS256 signature using that client's secret stored in Keycloak (no external secret store)
• Includes claims from any OIDC Hardcoded Claim protocol mappers configured in keycloak, on the client
• Requires the realm and the client to be enabled
• Requires an OIDC Hardcoded Claim mapper for rsin on the client; tokens for clients without one are inactive, and the token's own rsin is always replaced by the mapper value
• Rejects tokens whose iat is before the realm or client not-before policy (Revoke in the admin console); once a not-before is set, iat is required. Clients sign their own tokens and set iat themselves, so a not-before only invalidates tokens already issued; if the client secret has leaked, disable the client or rotate its secret
• Enforces token activity (validates exp/nbf when present)
• Tokens without exp claim will be treated as active, but warning will be logged in keycloak. It's recommended to use short lived tokens.

Build

1. Ensure you have Java 21 installed (download from https://learn.microsoft.com/en-us/java/openjdk/download)
2. Download Maven Binary zip archive from https://maven.apache.org/download.cgi
3. Add the bin directory of the created directory apache-maven-* to the PATH environment variable
4. Run the following command to build the JAR:

   mvn clean package

5. The compiled JAR will be in the target/ directory: zgw-token-introspection.jar

Deployment

1. Copy the JAR file to your Keycloak deployment:

   • For host install: {KEYCLOAK_HOME}/providers/
   • For Docker: mount to /opt/keycloak/providers/

2. Restart Keycloak. In dev:

   • {KEYCLOAK_HOME}/bin/kc.sh start-dev In prod:
   • {KEYCLOAK_HOME}/bin/kc.sh build && {KEYCLOAK_HOME}/bin/kc.sh start

Endpoint

• Path: /realms/{realm}/zgw-token-introspection/introspect
• Method: POST
• Content-Type: application/x-www-form-urlencoded
• Parameter: token=<JWT>

Token requirements

The provider expects JWT tokens generated with the following characteristics:

• Algorithm: HS256
• Secret: Client secret from Keycloak
• Required claim: client_id (must match a client in the realm)
• Issued at: iat is required once a realm or client not-before policy is set
• Temporal: Token must be active; exp is recommended

Usage

Submit the token to the introspection endpoint:

curl -X POST \
  "http://localhost:8080/realms/{realm}/zgw-token-introspection/introspect" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Returns an OAuth2 introspection-style payload with selected standard and custom claims. On success you will receive { "active": true, ... } and claim from token; otherwise { "active": false }.

Troubleshooting

• Check Keycloak logs for detailed error messages
• Ensure the client exists in Keycloak and has a secret configured
• Ensure the client and realm are enabled and the client has a Hardcoded Claim mapper for rsin
• Verify the token is properly formatted and not expired
• Confirm the signing algorithm is HS256
• Make sure the client secret matches what was used to sign the token