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

Wed Aug 30 04:46:11 EDT 2017

Hello Stian,

thanks for the great feedback!

Yes merging accounts can be quite complex as it can have many side effects.
My PoC implementation is very basic and just demonstrates the idea. A
complete
implementation would of course span multiple areas.

I agree with you that there should be a dedicated realm option "Allow
Account Merge" to enable this feature.
I've seen the mockups of the new account UI in JIRA - looking forward to
see it in action.

Some notes about the integrations you mentioned:

Admin Console:
I agree that this could be integrated quite easily to support the following
workflow:
1. Open the user details of a user in the "users" section.
2. Click on (new) Merge tab.
The merge tab shows two sections:
- "User selection" where the admin can select exactly one user.
- "Merge options" where the admin can configure how the merge is performed.
3. Select User
4. Select Merge Options
Options could include checkboxes with descriptions, e.g.
"Merge Profile", "Merge Roles", "Merge Group Memberships", "Merge
federation links",
"Merge user attributes"
Perhaps one could also indicate whether or not values can be overridden
(User Profile:  etc.)
5. Perform the merge by clicking "Merge"

User Account:
I think the need to be able merge user accounts arises quite often in
legacy integration
scenarios, e.g. when multiple big and partially overlapping user bases from
multiple
applications are consolidated into one.
Therefore I think it should be an operation that's available as
self-service to users as well,
users usually know their user accounts for different systems. This helps to
keep support efforts small.

I like your idea of a two phase user merge, first let user1 request to
merge with user2.
User2 needs to approve the merge. If user2 accepts his user information
will be
merged into user1 and user2 will be removed.

I agree that the user to be merged needs to go through the complete
authentication flow
in order to proof account ownership.

I think this could be done as follows:
In the account client there would be a new page "Merge Accounts".
On the "Merge Accounts" page there would be sections like "Request Account
Merge",
"Pending Account Merge" and potentially "Approved Account Merges".

In "Request Account Merge" the currently logged in user could enter the
username of the
user to merge with and request the merge via a "Request Merge" button.

The "Pending Account Merge" section could show the recently "Account Merge
Request"
 with some additional information about the user who send the merge request
(username, e-mail, firstname, lastname) and some metadata datetime,
IP-Address?, etc.
Here the user has now the option to "Cancel" or "Accept" the "Account Merge
request".

The "Approved Merge Requests" is optional and could just show a list of
accepted "Account merge requests".

Example workflow (happy path) for merging the user account user2 into the
leading user account user1.

User1
1. User1 logs into the the account application and goes to the "Merge
Accounts".
2. User1 would then select a user (user2) and click on "Request Merge".
This would register a "Account Merge Request" for the user2.
If user2 has an email address configured he would be notified via email
with a link
to the "Merge Account" page.
If the user doesn't have an email there could be a RequiredAction added to
user2 to send
the user to the "Merge Account" page on next browser login.

User2
1. User2 logs into the the account application and goes to the "Merge
Accounts",
   either by clicking on the link in the email or redirected by the
required action.
2. The user sees the pending Account Merge request and clicks on "Accept".
3. A confirmation prompt is shown to the user indicating that this
operation is
irreversible and that his account will be removed after the merge with the
account of user1.
4. User confirms the merge and is logged out.

Now user1 can re-login and (potentially) sees the merged user information
of user2, e.g by
visiting the "Merge Account" page and see the "Approved" merge request in
the "Approved Merge Requests"
section.

This workflow would go through the complete authentication flow for both
users including all custom authenticators.

As shown in my PoC, accepting a merge fires an ACCOUNT_MERGED event to
notify other other parties about
the merge. When user federation is involved it might be a bit more tricky,
as the merge operation
might need to be propagated through the federation provider explicitly.

Cheers,
Thomas

2017-08-30 8:50 GMT+02:00 Stian Thorgersen <sthorger at redhat.com>:

> Would be nice to have, but I'm worried about how complex it would end up
> being. It would have to leverage regular login pages and flows as otherwise
> it'd just be way to complex. We're also working on a new account management
> console that is HTML5 and uses new account management REST endpoints. Then
> I could see complications if the user has identity brokering links and also
> if the user is pulled in from an external user federation store. Would also
> need to be available to admins to be a complete feature.
>
> In the admin console the flow would probably be relatively simple, just
> open a user, click on merge tab, find the user and click merge. Might want
> to have some options on how to consolidate the two users there as well.
>
> In user account management console I'm not really sure. It seems that it
> would really be a feature that is not that commonly used, so wonder if it's
> best just left to admins? If available to users it should definitively be
> an option that has to be enabled for the realm. The user shouldn't be able
> to list users, but would have to provide details about the other account.
> That should just request the merge. To complete the merge the user should
> have to login as the other user and approve the merge. Afterwards the user
> would be logged out and able to login as the merged user.
>
> As this is a pretty big thing to add I would first want to make sure
> there's no-one that objects to it and as usual the PR would have to be
> implemented in a generic way (not just the way you want it ;)) and come
> complete with all tests and documentations.
>
> On 29 August 2017 at 15:53, Thomas Darimont <thomas.darimont at googlemail.
> com> wrote:
>
>> As a quick follow up, I implemented a working PoC for merging user
>> accounts
>> in the following branch:
>> https://github.com/thomasdarimont/keycloak/tree/issue/
>> KEYCLOAK-XXX-merge-user-accounts
>>
>> Cheers,
>> Thomas
>>
>> 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.
>> >
>> > WDYT?
>> >
>> > Cheers,
>> > Thomas
>> >
>> _______________________________________________
>> keycloak-dev mailing list
>> keycloak-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/keycloak-dev
>>
>
>