从Keycloak生成的JWT Token移除Realm Access的方法及实践疑问

Great question! Let’s tackle this from two angles: whether including realm access roles in JWTs is a bad practice, and how to remove them in Keycloak.

Is Carrying Realm Access (Roles) in JWT Tokens a Bad Practice? #

It’s not an absolute "bad practice"—it depends entirely on your use case:

• If your application needs realm-level role checks: Carrying this information makes sense. It avoids round-trips to Keycloak for every request to validate realm roles, which boosts performance.
• If your app only uses client-specific roles: The realm_access claim becomes redundant. Extra unneeded data increases the token’s size, which can slow down transmission (especially if you have many realm roles) and adds unnecessary overhead. In this scenario, removing it is a valid optimization.

In short: It’s bad only if it’s unnecessary for your system’s authorization flow.

How to Remove Realm Access Information from Keycloak-Generated JWT Tokens #

There are three reliable methods to do this, depending on your scope (per-client or global):

1. Custom Hardcoded Claim Mapper (Per-Client) #

This is the simplest approach for individual clients:

• Log into your Keycloak admin console and navigate to your target realm.
• Go to Clients → Select your client → Switch to the Mappers tab.
• Click Create and choose the Hardcoded Claim type.
• Configure it like this:
  • Name: Something descriptive (e.g., "Remove Realm Access")
  • Token Claim Name: realm_access
  • Claim Value: Leave empty or set to {} (empty JSON object)
  • Claim JSON Type: JSON
  • Check the boxes for the token types you want to apply this to (e.g., Access Token)
• Save the mapper. Newly generated tokens will no longer have the original realm_access data (it’ll be overwritten to empty or removed).

2. Script Mapper (Flexible Per-Client) #

Use this if you need more control (e.g., conditional removal):

• In your client’s Mappers tab, create a new mapper and select Script Mapper.
• Use a Groovy script like this to directly remove the claim:

  def realmAccess = token.getRealmAccess()
  if (realmAccess != null) {
      token.getOtherClaims().remove("realm_access")
  }
  return null
  

• Set the script to apply to your desired token types and save. This will strip the realm_access field entirely from the token.

3. Global Mapper (All Clients in a Realm) #

If you want to remove realm_access for every client in your realm (use with caution—ensure no app depends on this data):

• Go to Realm Settings → Mappers tab.
• Create a mapper using either the hardcoded claim method or script method above. Since this is a realm-level mapper, it’ll apply to all clients under the realm.

Important Note #

Before making changes, verify that all services consuming these JWTs don’t rely on the realm_access claim. Test modified tokens with a JWT decoder to confirm the field is removed or overwritten as expected.

内容的提问来源于stack exchange，提问作者ThatMan