April 7, 2025

Mastering Keycloak Client Access Settings – A Complete Guide with Real Use Cases & Best Practices

🔐 Mastering Keycloak Client Access Settings – A Complete Guide with Real Use Cases & Best Practices

✨ Why Understanding Keycloak Client URLs Matters

Imagine you have a secure web application. You want users to:

  • Log in via Keycloak

  • Get redirected to the right page after login

  • Be returned to a nice page after logout

  • Avoid CORS issues in SPAs

  • Handle backend logout events when a session ends

All of this is controlled via Keycloak Client Access Settings.

🔑 Let’s Break Down the URLs with a Story

🧑‍💼 Meet Aditi, who is logging in to your app:

App:

https://tenant-123.example.com

Keycloak:

https://auth.example.com

What happens?

1. Aditi opens: https://tenant-123.example.com ➡️
2. App redirects to Keycloak for login ➡️
3. Keycloak checks if redirect URL is allowed (Valid Redirect URIs) ➡️
4. After login, Keycloak redirects her back to: https://tenant-123.example.com/login/oauth2/code/keycloak
5. After logout, she’s taken to: https://tenant-123.example.com/logout-success

🧩 Client URL Types — Explained with Examples

URL Type Purpose Example Required?
Root URL Base URL of your app, used by Keycloak as default https://tenant-123.example.com ✅ Yes
Home URL Where “Back to App” points https://tenant-123.example.com/dashboard 🔄 Optional
Valid Redirect URIs Where to return users after login https://tenant-*.example.com/login/oauth2/code/keycloak ✅ Yes
Valid Post Logout Redirect URIs Where to redirect after logout https://tenant-*.example.com/logout-success ✅ Yes
Web Origins Trusted domains for browser-based requests https://tenant-*.example.com ✅ Yes (for SPAs)
Admin URL Where to send backchannel logout (server to server) https://tenant-123.example.com/backchannel-logout 🧪 Optional

🔁 Flow Diagram (Text-based Arrows)

🔐 Login Flow:

User ➡️ https://tenant-123.example.com
      ➡️ (App redirects to Keycloak)
      ➡️ https://auth.example.com/realms/demo/protocol/openid-connect/auth
      ➡️ (User logs in)
      ➡️ Redirects to: https://tenant-123.example.com/login/oauth2/code/keycloak
      ➡️ App handles token + navigates to: /dashboard

🚪 Logout Flow:

User clicks Logout ➡️
      App calls: https://auth.example.com/realms/demo/protocol/openid-connect/logout
      ➡️ Keycloak clears session
      ➡️ Redirects to: https://tenant-123.example.com/logout-success

🛰️ Backchannel Logout (Optional)

Keycloak (server) ➡️ POST to Admin URL
                   https://tenant-123.example.com/backchannel-logout
                   (App terminates session silently)

💡 Best Practices (Updated)

🔐 Security Tips:

  • Avoid using * in any URL setting in production.

  • Use wildcards like https://tenant-*.example.com/* only when you have DNS control.

  • Test each environment (localhost, dev, staging, prod).

⚙️ Wildcard Examples:

Use Case URI Pattern
Dev environment http://localhost:3000/*
Multi-tenant https://tenant-*.example.com/*
Logout page https://tenant-*.example.com/logout-success
Web origin for SPA https://tenant-*.example.com

🧘 Final Thoughts

These settings might look technical, but they're your app's gatekeepers. A properly configured Keycloak client:

  • Protects users from phishing

  • Prevents CORS headaches

  • Creates a seamless login/logout experience

Now that you’re equipped with:

  • URL meanings ✅

  • Flow diagrams ✅

  • Real-world story ✅

  • Best practices ✅

You’re ready to master Keycloak like a pro.

Would you like me to convert this blog into a Markdown/HTML file for publishing?

Posted by