First social login in Keycloak

One of the core Keycloak features is so called social brokering and identity provider brokering. Keycloak provides integration with the known social networks (Facebook, Google, Twitter, Github, StackOverflow, LinkedIn). You can also easily plug any other OpenID Connect, OAuth2 or SAML2 authentication server. When you click on particular social network (or identity server) button on login screen, Keycloak will use it to authenticate user and then redirect back to the application.

The social integration is available in Keycloak from it's early days. But we have also issues with so called First social login from it's early days. The term First login means that user authenticates to Keycloak for the first time through some particular social network (for example through Facebook).

Let's describe this in a bit more details. When Keycloak successfully authenticates user through social provider, there can be two situations:

• There is already Keycloak user account linked with the authenticated social account. In this case, Keycloak will just authenticate as the existing user and redirect back to the application.
• There is not yet existing Keycloak user account linked with the social account. This situation is more tricky. Usually you just want to register new account into Keycloak database, but what if there is existing Keycloak account with same email like the social account? Automatically link social account with existing Keycloak account is not very good option as there are possible security flaws related to that...

For the second case, we had lot of various related issues and lot of feedback and requirements from community and from our awesome jboss.org team. In the end, We changed the behaviour to be flexible and configurable through Authentication Flows SPI . This is available from Keycloak 1.7.0.CR1. Basically, you can configure the default set of authenticators, which allows you to change the behaviour according to your needs. It's also possible to implement your own Authenticator and adjust the behaviour exactly according your requirements.

The default behaviour for first social login is this:

• User is optionally faced with the Review profile page where he can edit the claims (email, first name, last name and more) retrieved from social provider. By default, the page is displayed only when some of mandatory claims is missing (For example in case of Twitter, the page is always displayed as Twitter doesn't return email of user).
• If there is no user with conflicting email in Keycloak database, user is automatically created and redirected back to the application.
• Otherwise he needs to confirm that he wants to link his existing Keycloak account with the newly authenticated social account
• If user choose to link accounts, he needs to either confirm linking by email verification, or he needs to re-authenticate and type his password (and optionally OTP). It depends on admin on how exactly he configures the authentication flow.

Here are some screenshots of how the typical first login with Facebook can look like. It includes review profile, confirming that user wants to link his Facebook account and verification of successful account linking by email verification.

For more details, see Keycloak documentation .

Additionally in 1.8 version, we have a plan for adding post-broker flow, which will allow additional verification after each login with social provider (For example OTP). So stay tuned.