Linking account on legacy systems to new Keycloak ones

The problem:

  • We have two realms; our new Keycloak realm that we want all new users to use, and an old realm that’s set up in Keycloak as a User Federation, using a custom User Provider SPI to allow users to log in with old accounts on our existing system.

What we want to achieve:

  • We want all users to register new accounts, BUT if they have an old account we want them to be able link it to their new one. This is so we can access their old ID for downstream systems that still need it.
  • They can obviously go to their ‘Federated Identities’ page in their account and add it there, this all works now, but we would like to offer them the opportunity to link their old account when they register a new one.
  • Ideally we’d do this by having them tick a box to “Link old account” during the registration process. Then after entering their new details they would be directed to log into their old account which would be automatically linked to the new one.
  • This could happen before or after the new account is verified, but allowing them to do it before verification seems like it might be simpler and less confusing.

Our question is what is the best way to achieve this?

  • Do we customise the new account theme pages somehow, or can we create a custom Authentication flow to achieve it?
  • Or a combination of both?
  • Or some other way?