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

[Thomas Darimont]

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.

WDYT?

Cheers,
Thomas