How to Invalidate Compromised JWT Tokens in Keycloak

1. Force Logout a User from Keycloak Admin Console

When you know that only a specific user’s token is compromised, you can invalidate their session manually from the Keycloak Admin Console.

Steps:

Log in to the Keycloak Admin Console.
Go to Users → [username] → Sessions tab.
Click on Logout.

What It Does:

It terminates the user’s current session in Keycloak.
Any access token or refresh token issued for that session becomes invalid immediately.
It prevents the attacker (or the real user) from using the same token further.

Why It’s Useful:

It’s fast, effective, and surgical—applies to only the affected user.
Ideal for handling user-reported compromises.

2. Logout All Sessions of the User

This option is useful if the user is logged in from multiple devices, and you want to invalidate all tokens issued to them, including mobile or desktop sessions.

Steps:

In the Admin Console, go to Users → [username] → Sessions.
Click Logout All Sessions.

What It Does:

Ends all sessions across all devices or platforms for that user.
Invalidates all access tokens, refresh tokens, and any session cookies.

Why It’s Useful:

Ensures that if a token was stolen from a particular device, all tokens are still revoked across the board.
Commonly used in response to lost/stolen devices or credentials.

3. Logout All Users from the Realm

When you suspect a mass compromise or you’re dealing with a server-side vulnerability, you might want to force all users to log out.

Steps:

Go to Realm Settings → Sessions.
Click the button labeled Logout All.

What It Does:

Immediately invalidates all active user sessions in the realm.
Users will be forced to re-authenticate.

Why It’s Useful:

Helps contain a large-scale token compromise.
Can be used as a kill switch during a breach or penetration testing response.

4. Programmatic Logout via Admin REST API

Instead of using the Admin UI, you can also log out users using Keycloak’s Admin REST API.

Endpoint:

POST /admin/realms/{realm}/users/{user-id}/logout

Requirements:

A valid admin access token.
The user’s UUID (can be retrieved via API or Admin UI).

What It Does:

Same as UI logout—it invalidates all the user’s sessions and tokens.

Why It’s Useful:

Allows automation of user logout, e.g., in response to suspicious behavior detected by your backend or SIEM tools.

5. Use OAuth 2.0 Token Revocation Endpoint (for Refresh Tokens)

The standard OAuth 2.0 revocation endpoint can be used to revoke refresh tokens. This is particularly useful for OAuth-based applications or external clients using Keycloak.

Endpoint:

POST /realms/{realm}/protocol/openid-connect/revoke

Required Parameters:

token: The refresh token to be revoked.
client_id and client_secret: Required if your client is confidential.

What It Does:

It prevents the compromised refresh token from being used to get a new access token.
Access tokens (which are usually short-lived) will expire naturally.

Why It’s Useful:

Prevents prolonged access using refresh tokens.
Useful in mobile applications where access token rotation is common.

6. Shorten Token Lifespans

To reduce the window of exposure for stolen tokens, you should configure shorter token lifetimes.

Steps:

Go to Realm Settings → Tokens.
Set:
- Access Token Lifespan (e.g., 5–15 minutes)
- Refresh Token Lifespan (e.g., 30 minutes to 7 days)
- SSO Session Idle and SSO Session Max

What It Does:

Forces users to re-authenticate more frequently (or use refresh tokens).
Stolen tokens become useless after a short period.

Why It’s Useful:

It limits the amount of time an attacker can use a stolen token.
Increases overall security posture at the cost of some user convenience.

7. Enable Refresh Token Revocation (One-Time Use Only)

Keycloak allows you to configure clients so that refresh tokens can only be used once. If they are used again (like by an attacker who intercepted it), they will be rejected.

Steps:

Go to Clients → [your client] → Settings.
Enable the toggle Revoke Refresh Token.

What It Does:

Ensures that a refresh token is invalidated immediately after use.
When the client gets a new access token, it also gets a new refresh token.

Why It’s Useful:

Prevents replay attacks where someone captures and reuses a refresh token.
Greatly reduces the risk of long-lived token theft.

8. Rotate Realm Key Pair (Only If Key Is Compromised)

In case of a serious compromise, where you suspect the signing key (private key or secret) has been leaked, you can rotate the realm key.

Steps:

Go to Realm Settings → Keys.
Click Add Keystore to generate a new key pair.
Set it as the new active key.

What It Does:

All previously signed tokens will fail signature validation unless fallback keys are allowed.
Forces re-authentication for all users.

Why It’s Useful:

Essential step when your JWT signing keys are compromised.
Acts as a reset for the entire realm’s authentication infrastructure.

9. Add Custom Claims for Fine-Grained Token Invalidation (Advanced)

Keycloak allows adding custom claims in tokens using Protocol Mappers.

Example Use Case:

Add a claim like token_version or last_logout_time.
Store a matching value in your user DB.
On each token validation in your backend, compare the claim with DB.
Reject tokens if they are outdated.

Why It’s Useful:

Adds flexible control for invalidating tokens without changing keys or server configs.
Allows application-level token versioning and targeted invalidation.

Best Practices Summary for Securing JWTs in Keycloak

Recommendation	Description
Use HTTPS only	Prevents token theft via sniffing
Prefer short access token lifespan	Reduce risk window if token is stolen
Use refresh tokens with rotation	Control and monitor token issuance
Enable refresh token revocation	Prevent replay attacks
Force logout or session invalidation on suspicion	Quickly revoke compromised tokens
Rotate keys if private keys are exposed	Ensures attackers can’t forge valid tokens
Audit login and token usage patterns	Detect anomalies or suspicious behavior