[keycloak-dev] Plan for "First login with identity brokers"

[Marek Posolda]

I went again through all the previous discussions, related JIRAs and 
requirements. As of now, my plan is to:

- Use authentication SPI to handle the flow and related actions for 
first social login. (Update user profile, Detect duplicated account, 
Verify email or reauthenticate user if duplication is detected, Create 
social link to existing account). This allows most flexibility for 
admins to specify how exactly the linking should work

- Detecting duplication will be based on email only by default - (For 
example duplication is detected if Facebook user with email 
bob at gmail.com authenticates, but there is already Keycloak user with 
email bob at gmail.com ). The people can provide their own execution if 
they want different way for detect duplications

- It seems it's more proper to postpone creating user account later, 
once we know that there is no duplication. In other words, if "Update 
profile on first login" is enabled, the user account is not yet created 
when the update profile page is shown. All the info related to 
BrokeredIdentityContext stuff will be available on ClientSession. This 
seems to me easier and more proper solution then creating temporary 
account with email in some "temporary" attribute. Temporary accounts 
have other challenges (Cleaner thread for delete outdated unmerged 
accounts etc).

- If "trustEmail" flag is on for IdentityProvider, the provider link 
will be created automatically. (For example if Facebook user 
bob at gmail.com authenticates for the first time and there is already 
Keycloak user with email bob at gmail.com and trustEmail is on, the 
Facebook link is automatically created for Keycloak account 
bob at gmail.com without any additional verification)

- If "trustEmail" flag is off, there would need to be other way to 
verify user before creating social link. The user will first confirm if 
he wants to merge the accounts. Then there will be either:
-- Email verification: The mail will be sent to bob at gmail.com like 
"Someone authenticates to Keycloak server http://www.keycloak.org:8080 
through Facebook account bob at gmail.com and wants to link Facebook 
account with existing Keycloak account bob at gmail.com . If it is you, 
click here" . After user clicks, the social link is created
-- Further authentication: User will need to authenticate to existing 
bob at gmail.com keycloak account through password (or OTP or both or 
something else)
All of this is configurable through flows, so admin can disable the "Do 
you want to create social link?" screen, or enforce email verification 
instead of authentication, configure required authenticators etc.

- I am not sure if we want to handle just merge with existing account 
during first broker login, or if we also want to handle merging of 
accounts in account management? For now, I am planning to handle just 
the login flow and possibly address Account management later if there is 
need for it. The merging accounts in account management might be quite a 
challenge as there is merge of 2 already existing user accounts with 
various issues related to it (Which roles/permissions should merged 
account have? Which attributes it should have? Which federation link? 
etc.). But at least, I am planning to address the issue with redirect to 
login forms error screen instead of stay in account management - 
https://issues.jboss.org/browse/KEYCLOAK-1822

Marek