[keycloak-dev] Proposal for merging user accounts in Keycloak

Thomas Darimont thomas.darimont at googlemail.com
Tue Aug 29 09:53:59 EDT 2017

As a quick follow up, I implemented a working PoC for merging user accounts
in the following branch:


2017-08-29 2:10 GMT+02:00 Thomas Darimont <thomas.darimont at googlemail.com>:

> When integrating multiple legacy systems one often finds that a particular
> user
> has multiple user accounts. In such scenarios it would be helpful if users
> could consolidate their user accounts themselves by merging some of them
> into one.
> Currently Keycloak doesn't have an official way to merge two existing user
> accounts.
> Since I'm currently facing this in a project I thought a bit about how
> this could
> be solved in Keycloak.
> Keycloak could provide a dedicated "merge" sub-page in the account
> application,
> e.g. account/merge. There a authenticated user1 could select the account
> he likes
> to merge with and verify the ownership of this account.
> If the ownership could be verified successfully the user1 would be asked
> for a
> final merge confirmation. If the user1 confirms the merge then the
> selected user
> account (user2) would be merged into the currently logged-in user account
> (user1).
> Some logic would then need to decide how to merge the selected user2 into
> the
> currently logged-in user1, e.g. by assining roles and / or consents and
> potentially
> copy over some user profile values.
> The account for user2 would then either be marked as merged or deleted.
> Login with
> user2 is no longer possible from this point on.
> This could be supported by a dedicated "user account merge" SPI that could
> decide
> whether two accounts can be merged, how the merge is performed and what
> user information
> will be merged. This would enable great flexibility and help quite a lot
> to
> ease integration of legacy systems.
> Finally after a successful merge a USER_ACCOUNT_MERGED event with some
> metadata
> (about user1, user2 etc.) would be fired to notify other systems about the
> user account merger.
> Here are the steps in some more detail:
> # Authentication
> 0) Unauthenticated user1 goes to the /account/merge page and gets
> redirected
> to the login page.
> 1) User1 authenticates and gets redirected back to /account/merge
> # Account Selection / Verification
> 2) User1 selects an account to merge with, e.g. user2 and verfies ownership
> E.g. by showing an embedded login form and ask for Username + Password +
> 2nd Factor
> if present
> # Merge
> 3) Merge the user account
> 3.0) Ask user whether accounts should be merged (account of user1 will
> become
> the remaining / leading account). This is irreversible!
> 3.1) Avoid account modification for user2 during merge, e.g. deactivate
> the
> old user (user2)
> 3.2) Record some information about the merged user
> Perhaphs via user attributes or maintain an explicit list of merged users.
> # Decide what should be merged
> A built-in logic and / or the user decides what should be merged.
> 3.4) User Profile information (e.g. complete incomplete fields?
> E.g. firstname, lastname, mobile, etc.)
> 3.5) Grant all roles of user2 to user1
> 3.6) Grant all consents of user2 to user1
> 3.7) Grant all group memberships of user2 to user1
> Credentials of user2 would be ignored.
> # Conclude the merge
> 4) Mark user2 as merged or delete user 2
> Delete user2 or rename user2 and change email to be able to use that
> information for user1.
> 4.1) Propagate user account merge as event
> Propagate a USER_ACCOUNT_MERGED event via the EventListener infrastructure.
> The event should contain at least the userId of user1, and the userId of
> user2 and
> tells which is now the leading account. This enables downstream systems to
> get notified
> about the account merge.
> Cheers,
> Thomas

More information about the keycloak-dev mailing list