Debugging SSO Authentication — Common Issues in Spring Boot

After integrating Keycloak (or any SSO provider) with Spring Boot, the most common question developers face is:

“My SSO login works sometimes, but other times I get 403, redirect loops, or the roles are wrong. How do I debug this?”

This post shows **systematic ways to debug SSO authentication issues** and avoid guessing.

---

1️⃣ Token not being parsed or expired

SSO usually involves JWTs or tokens issued by the IdP. Common mistakes:

• Token expired — default Keycloak token is 5 minutes
• Token not sent in Authorization header
• Token audience mismatch

Debug tip: Log the raw token and validate it using jwt.io or Keycloak admin console.

---

2️⃣ Roles not mapped correctly

Even if the token is valid, access can fail if roles/authorities are missing:

• Check Keycloak client and realm roles
• Ensure Spring Security maps Keycloak roles to authorities
• Remember hasRole("ADMIN") vs hasAuthority("ROLE_ADMIN")

Debug tip: Print Authentication.getAuthorities() right after login.

---

3️⃣ Redirect loops

You might see the user redirected back and forth between your app and Keycloak.

• Common cause: wrong redirect URI in Keycloak client
• Public vs confidential client mismatch
• Misconfigured Spring Security adapter

Debug tip: Enable DEBUG logs for org.keycloak.adapters and watch the login flow.

---

4️⃣ Filter chain / reactive context issues

For Spring MVC:

• Check which filters are applied — Keycloak adapter uses a filter chain
• 403 usually means authentication succeeded but roles are missing

For WebFlux (reactive apps):

• Reactive context is not thread-local
• Logging outside reactive chain may show null authentication
• Use reactive hooks or custom ReactiveAuthorizationManager

---

5️⃣ Session vs Bearer-only mode

Keycloak clients can operate in two modes:

• Confidential / public client: full login, session-based
• Bearer-only: token-only, no login page

Mistaking the mode often causes:

• 401 or 403
• Unexpected redirects to Keycloak login page

---

6️⃣ How to systematically debug

A repeatable debugging workflow:

1. Check Keycloak logs for token issuance
2. Inspect the token using jwt.io
3. Log Spring Security Authentication object after login
4. Verify roles and authorities
5. Check your redirect URIs and client configuration
6. Use DEBUG logging for filters and adapters

Once you follow this workflow, most SSO issues are solved in minutes.

---

Final tips

• Always separate authentication issues from authorization issues (401 vs 403)
• Reactive apps need extra attention on context propagation
• Keep your logs clean: one clear log line per login/denial
• Check Keycloak client roles vs realm roles carefully

---

Next steps

The next post will cover **SSO in Spring WebFlux applications**, highlighting key differences from MVC and common pitfalls.

Part of the Spring Boot SSO Series

❤️ Support This Blog

---

If this post helped you, you can support my writing with a small donation. Thank you for reading.

---

Coffee ☕ Thanks 🙏 Extra Support ❤️