Keycloak Token Status Plugin

A Keycloak plugin that reports the status of verifiable credentials to an external status list server, so you can revoke a credential before it expires, for example when it is compromised or must be invalidated for compliance reasons.

Features

• Reports credential status to an external status list server
• Revokes issued verifiable credentials through a dedicated endpoint
• Caps non-revoked credentials per holder and type, with an overflow policy to either fail issuance or revoke oldest credentials automatically

Compatibility

This plugin has been tested and verified to work with:

Component	Version
Keycloak	26.8.0

It works with any status list server that implements both the OAuth 2.0 Status List format and the management API used by this plugin, such as the status list server project. A public instance is available at https://statuslist.eudi-adorsys.com.

Getting started

Installation

Prerequisite: Java 17 or later.

1. Build the plugin:

   ./mvnw clean package -DskipTests

2. Copy the resulting JAR from target/keycloak-token-status-plugin-*.jar into Keycloak's providers directory.

3. Restart Keycloak.

The plugin is also published on Maven Central.

Configuration

Enable the plugin for a realm and point it at your status list server using these realm attributes:

Attribute	Description
status-list-enabled	Enables the status list service for the realm
status-list-server-url	URL of the status list server

Enabling these attributes alone is not sufficient. The status claim is only emitted after the oid4vc-status-list-claim-mapper protocol mapper is attached to the client scope of the credential configuration you want to publish. See Enabling the Status List protocol mapper for details.

The full list of configuration properties is documented in the technical reference.

Revoking a credential

A client application can revoke an issued credential through the plugin's /revoke endpoint, which sets the credential's status to INVALID so it can no longer be used. The request requires a bearer access token, mode=issued_credential_revocation, and the credential_id of the credential to revoke.

See the technical reference for the full request and response details.

Demo

This plugin can be combined with the OpenID4VP plugin, the status list server and the Mock FE app to build an end-to-end credential revocation demo. A step-by-step setup guide is available in docs/credential-revocation-demo/setup.md.

Development

./mvnw test            # run tests
./mvnw spotless:check  # verify formatting
./mvnw spotless:apply  # fix formatting

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only). See LICENSE for details.