Presenters

Source

🛡️ Stop Building “God Tokens”: Avoiding the Top Keycloak Mistakes

At the first-ever KeycloakCon in Amsterdam, industry veteran Niko Köbler dropped a bombshell: 90% of Keycloak developers are making critical mistakes in their configuration. Having worked with Keycloak since its infancy in 2015, Niko has seen it all—from massive enterprise LDAP migrations to modern microservices architectures.

If your application “just works,” you might think you’re safe. But in the world of identity and access management, “working” and “secure” are two very different things. Here is how to stop issuing dangerous God tokens and start implementing professional-grade security.

🛑 The Trap of the “God Token”

Most developers rely on Keycloak’s default settings. While these defaults make initial development easy, they create a massive security liability. In many enterprise environments, users are connected via LDAP or Active Directory—systems that have grown over 30 years. These systems often contain 2,000 to 3,000 roles.

By default, Keycloak issues tokens that contain every single role assigned to a user. Niko highlights that even a “simple” user like Fred Flintstone might carry 23 role mappings in a demo, but in a real-world scenario, this explodes to hundreds or thousands.

The Impact:

  • Bloated Tokens: Massive headers can crash some web servers or proxies.
  • Security Leakage: You are exposing your entire internal role structure to every service that receives the token.
  • Performance: Large tokens increase latency and bandwidth consumption.

🕵️‍♂️ Mistake 1: Leaking Personal Data (The GDPR Nightmare)

Keycloak’s default configuration includes personal information—like email addresses and profile data—directly in the access token.

Niko argues this is a fundamental misunderstanding of the protocols. OAuth 2.0 access tokens are meant for accessing resources, not for providing personal user data. OpenID Connect (OIDC) provides the ID Token and the User Info endpoint for personal details.

🛠️ The Fix:

Don’t just set client scopes to optional. Instead, go into the Mappers for your scopes (like the email scope) and toggle off Add to access token. This ensures that while your Web App gets the email in the ID Token, your downstream APIs receive only what they need to authorize the request. Use the principle of data minimization to stay compliant with GDPR.

🏰 Mistake 2: The “Full Scope Allowed” Vulnerability

In the Keycloak Admin UI, every client has a “Dedicated Client Scope.” Hidden inside is a toggle called Full Scope Allowed, which is ON by default. This setting allows the token to include every role the user possesses across the entire realm.

The Tradeoff: Switching this OFF requires more manual configuration, but the security payoff is massive. When you disable full scope, you must explicitly assign only the specific roles that the target API needs.

The Result: If a user has 500 roles but API 1 only needs 2, the token sent to API 1 will contain exactly 2 roles. This follows the Principle of Least Privilege.

🎯 Mistake 3: Trusting Your Libraries to Check the Audience

A common scenario involves a Web App calling API 1, which then calls API 2. If your Web App’s token contains an audience (aud) claim that includes both APIs, the Web App could bypass API 1 and call API 2 directly.

Niko warns that many developers assume their libraries—like Quarkus or Spring Security—handle audience validation automatically.

  • Quarkus handles this via configuration.
  • Spring Security often requires active implementation (extra lines of code) to verify the aud claim.

If you don’t check the audience, your API will accept any valid token issued by your Keycloak realm, regardless of which client it was intended for. 🚀

🔄 The Pro Solution: Token Exchange

When API 1 needs to talk to API 2, you shouldn’t just forward the original user’s token. Instead, use Token Exchange.

This process allows API 1 to:

  1. Take the incoming Access Token.
  2. Send a request to Keycloak’s token endpoint using the grant_type=urn:ietf:params:oauth:grant-type:token-exchange.
  3. Request a new token specifically for API 2.

Why this matters: The new token will have its audience strictly set to API 2 and will only contain the roles necessary for that specific interaction. This prevents token propagation abuse and keeps your microservices isolated and secure. 🦾

❓ Q&A with Niko Köbler

Q: Does token exchange revoke the original token? Niko: No. You get a second, new token. The original token remains valid until it expires. Remember: you cannot easily revoke an access token once issued. This is why you must use short-lived tokens (minutes, not hours).

Q: Does the new token in API 2 know the original sender was the Web App? Niko: By default, no. The token exchange standard doesn’t automatically preserve the originating system’s info. The token is simply a “golden ticket” for the holder. If you need “on-behalf-of” tracking, you must configure that manually.

Q: How do I handle permissions if one product is built on top of another in the same realm? Niko: This usually requires a mixture of configurations. You might allow the Web App to access both APIs directly, or perform a token exchange for the second layer. It depends on how strictly you want to separate your layers.

✨ Final Thoughts

Security is not a “set it and forget it” task. Keycloak is a powerful tool, but its default “it just works” settings are often at odds with production security standards.

Niko’s Golden Rules:

  • Check your tokens using the Evaluate tool in the Keycloak UI (but never paste production tokens into random websites! 👾).
  • Minimize data by removing personal info from access tokens.
  • Restrict scope by disabling “Full Scope Allowed.”
  • Verify the audience in your API code.

By following these steps, you move from being a developer who just uses Keycloak to a security-conscious engineer who masters it. 🌐💡

Appendix