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.

Keycloak 1.7.0.Final Released

This release contains no changes since 1.7.0.CR1 as there where no major bugs reported. Thanks to everyone that did give CR1 a try and provided feedback.

For new features in this release check out the blog post about Keycloak 1.7.0.CR1 release

For the full list of issues resolved check out JIRA and to download the release go to the Keycloak homepage.

Keycloak 1.7.0.CR1 Released

I'm pleased to announce the release of Keycloak 1.7.0.CR1. Recently we've gone straight to Final, but we'd like to give everyone a chance to try a release out first. Unless there are major issues reported we will release Final next week.

As usual we've been far from idle and have a number of highlights in this release, including:

• Groups - users can belong to one or more groups and inherit role mappings and attributes from the group.
• First Broker Login Flow - we've introduced a number of improvements to first login with identity brokers as well as the ability to customize the flow used.
• Client Registration - clients can now dynamically register themselves with a Keycloak server. This supports Keycloak client representations, OpenID Connect Dynamic Client Registration and SAML Entity Descriptors. Client registration are simple REST endpoints, there's also a Java library and a CLI is coming soon.
• OpenID Connect Implicit and Hybrid flows - we've added support for the Implicit and Hybrid flows. It's also possible to select what flows are available for a specific client.
• Add User script - as a first step to not having a default admin user we've added a script that allows creating an initial admin account.
• Cache fixes - there's a number of fixes related to caching, which should improve performance especially in clusters.
• Email Sender SPI - previously we had one SPI that created email content from FreeMarker and also sent emails. We've now split this into two separate SPIs.
• SAML SP WildFly subsystem - there's now a WildFly subsystem for the SAML SP adapter, which makes it easier to use the SAML SP adapter on WildFly.
• WildFly 10 adapter support - the WildFly adapter, including adapter subsystem, now supports WildFly 10.

For the full list of issues resolved check out JIRA and to download the release go to the Keycloak homepage.

Offline tokens in Keycloak

In Keycloak 1.6.1 We added support for offline tokens. This feature is described in OpenID Connect 1.0 specification and is useful for the applications, which needs to be able to do some actions on behalf of user, but in offline mode. Offline mode means that user is currently not logged in.

For example imagine Photo Album application, which needs to do periodic backup of saved user photos every day on midnight. This application can't never ensure that user is logged each midnight, but what it can do is:

• When user authenticates to the application through Keycloak server, the application asks Keycloak server to return offline token instead of classic refresh token. The only thing application needs to do to request offline token is to add the parameter scope=offline_access during authentication request to Keycloak. Offline token is just special kind of refresh token, which never expires.
• Photo Album application then saves the offline token in it's database
• When user logout from the application, the session of user is invalidated. However offline token is still considered valid by Keycloak server.
• On midnight, the application loads the offline token from it's database and send request to Keycloak to retrieve new access token. Even if user is offline, Keycloak will return access token corresponding to previously authenticated user. Application can use this access token to do the backup of photos on behalf of user and invoke any REST Backup service with the issued access token.

User is able to see and revoke any previously issued offline tokens in Keycloak Account Management application.

Also admin has possibility to see and revoke offline tokens of any particular user or eventually revoke all offline tokens issued to particular client application.

For more details, see Keycloak documentation and our Offline-access-app example, which is part of Keycloak example demo.