Introduction

An identity migration can add a new external identity broker in Keycloak while client logins still redirect users to the old one. The realm stays online, but authentication lands at the retired broker, one client uses the new upstream IdP while another still follows the previous alias or login flow, or failures begin only after the old broker is disabled because identity provider aliases, client defaults, and browser authentication flows often change separately.

Treat this as a broker-selection problem instead of a generic Keycloak outage. Start by checking which identity provider alias an affected client actually triggers during login, because migrations often validate the new broker in the realm admin console while real client entry points continue following older redirect and login-flow settings.

Symptoms

  • A Keycloak client still redirects to the old identity broker after migration
  • The realm is healthy, but user sign-in lands at the retired upstream IdP
  • One client or login entry point uses the new broker while another still uses the previous one
  • Redirect failures begin only after the old broker alias, endpoint, or trust is removed
  • The new broker is configured, but migrated clients never send users there
  • The issue started after moving Keycloak, external identity providers, or realm authentication flows

Common Causes

  • The client still references the old identity provider alias or default IdP setting
  • Browser authentication flow or home-realm-discovery logic still routes users to the previous broker
  • Theme customizations, bookmarked login links, or app entry URLs still include the retired broker hint
  • Realm import or environment promotion restored older identity-provider configuration
  • One realm or client override was updated while another still follows the previous broker selection path
  • Validation confirmed the new broker worked from manual testing but did not verify which broker live client logins actually invoked

Step-by-Step Fix

  1. Capture one affected login and record the client, realm, broker alias, login URL, and redirect flow it actually uses, because the live broker-selection path determines where authentication really lands.
  2. Compare that active broker path with the intended post-migration identity design, because one stale alias or login entry point can keep production authentication tied to the retired upstream IdP.
  3. Review identity provider aliases, client settings, default IdP config, browser flows, theme overrides, and app login links for references to the old broker, because Keycloak broker routing can be controlled by both realm config and client entry behavior.
  4. Check each realm, client, and login shortcut separately if behavior differs, because migrations often update one authentication path while another still redirects through the previous broker.
  5. Update the authoritative identity-provider alias, default IdP selection, kc_idp_hint usage, and login-flow selection so affected users are sent to the intended broker, because adding the new upstream IdP alone does not retarget existing Keycloak entry points.
  6. Run a controlled login from the affected client and confirm the intended broker alias handles the redirect, because a healthy realm login page does not prove the right upstream IdP answered the request.
  7. Verify the old broker no longer receives redirected authentication requests from migrated clients, because split federation paths can remain hidden while both brokers stay available.
  8. Review redirect URI trust, signature settings, and client scopes if logins still fail, because the destination can be correct while federation trust or client policy still blocks the new path.
  9. Document which team owns realm broker configuration, client login links, and migration validation so future identity cutovers verify the actual runtime redirect target before retiring the previous broker.