Thursday, 4 February 2016

Keycloak 1.8.1.Final and 1.9.0.CR1 released

Today we have two releases. As 1.8.0.Final was released before WildFly 10 Final was available, we decided to release 1.8.1.Final which is now built on top of WildFly 10 Final.

The bigger release today is 1.9.0.CR1, this release contains a large number of bug fixes and improvements, but no major new features.

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

Friday, 29 January 2016

Keycloak 1.8.0.Final Released

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

Monday, 25 January 2016

Internationalization (i18n) and Localization (l10n) of Keycloak

Keycloak's admin console needs to be fully localized.  That is, we need to replace all of our static English text and replace it with something that can display readable text in the user's local language.  I've done this sort of thing many times in Java, but our admin console is written in AngularJS, which is rather new to me.

So I set out to discover what i18n/l10n libraries might help.  I found three candidates.


angular-localization is a relatively new library written by Rahul Dashi.  I must say I was pretty impressed with this talk he gave at an AngularJS user group.

I also checked out the GitHub repo and documentation.  This was definitely in the running.  Worth a test-drive.


angular-translate is very similar to angular-localization.  angular-translate's founder and primary author is Pascal Precht.  "Pascal" is a phenomenal name for a programmer, so his library must be good.  But just to check, I did watch a talk, looked at GitHub, and the docs. This one would get a test-drive too.


Among the three, angular-gettext wins the award for best web site.  But beyond that, I didn't like what I saw.  The approach is completely different from the first two.  You annotate your code and run it against a tool that tries to figure out where the static text is.  Then it uses the English text as keys to put into .po files for translation.  Magical!  But as any Harry Potter fan knows, while magic can be fun, it can also go horribly wrong.

The more I read about angular-gettext, the more it just didn't seem right for Keycloak.  I hate an over-reliance on tools.  I don't like forcing developers and translators to learn new tools either.  Plus, I don't think our translators ever use .po files.

Maybe I was punting on third down*, but I just couldn't justify spending more time on angular-gettext.

(*Note that "punt on third down" is an American football reference that that can not be localized to soccer. :-) ) 

angular-localization vs angular-translate

So it's down to two candidates.  To try these out, I created a simple app that localizes the Keycloak login page.  In Keycloak today, this page is already localized using Freemarker.   But for this exercise I just grabbed the raw HTML and created two AngularJS pages, one to test each library.  You can see the code or try it yourself.  I've uploaded the source to my GitHub account.

Here is how it looks with both libraries.  Both allow you to change languages with the press of a button:

So both libraries work, and the code I had to write for each is very similar.

Here is a simple translation for angular-localization:
 <label for="password">{{'password' | i18n}}</label>
Here is the same translation for angular-translate:
 <label for="password">{{'password' | translate}}</label>
Both let you do translations with directives or filters.  Both use JSON resource bundles for translation mapping.  Both let you parameterize your messages, and both have support for AngularJS features like pluralization and two-way binding.  Both meet Keycloak's requirements.

So which do we choose?

The maturity heuristic

There are indeed some technical differences between the two libraries.  And judging from what I've seen, angular-localization probably learned some things from its older, more mature cousin.  But therein lies the rub.  angular-translate is considerably more mature.

The great thing about open source is that I can assess this maturity.  It's quick and easy to look under the hood and see how far along a project really is.  You can see the frequency of commits.  You can see the diversity of the developers who have submitted pull requests.  And most important, you can see if the project is still "alive" with recent commits and releases.

In other words, you can assess the community.  Software is only as good as the company or community that stands behind it.  So in the end, the choice was pretty easy.  We went with angular-translate.

Friday, 22 January 2016

Keycloak 1.8.0.CR3 Released

A few more fixes, hopefully this will be the last CR and we can release Final next week.

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

Thursday, 21 January 2016

Keycloak 1.8.0.CR2 Released

We had a few issues reported against 1.8.0.CR1, so we're doing another CR release with the fixes. If everything is OK, 1.8.0.Final will be released next week.

There was also a feature that sneaked in. We now support sign-on with Microsoft Live.

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

Wednesday, 13 January 2016

Keycloak 1.8.0.CR1 Released

Keycloak 1.8.0.CR1 has just been released. As usual we will follow with a final release next week as long as no major issues are reported.

  • Default Admin User Removed - we no longer have a built in admin account, instead a new account has to be created initially from http://localhost:8080/auth or with the bin/add-user[sh|bat] script
  • Client Templates - with the introduction of client templates it's now possible to share mappers and scope configuration between clients
  • Partial Import - it's now possible to import users, clients, identity brokers and user federators from a json file into an existing realm
  • Truststore SPI - we've introduced a Truststore SPI which provides a centralized place to manage the truststore for clients, email, user federation and identity brokering
  • Password Hashing SPI - if you want to import existing users into Keycloak you can implement a password hashing provider so existing hashed passwords can be used (thanks to tsudo for the contribution)
  • Identity Brokering Login Flow - this allows customizing the flow used when a user logs in through an identity broker
  • SAML v2 Enhanced Client or Proxy Profile (ECP) - this SAML profile is useful for non-browser based clients (for example a desktop application)
  • OAuth2 Token Introspection - the OAuth2 token introspection specification provides a standard way to obtain the active state of a token
  • Conditional OTP - requiring OTP used to be either enabled or disabled for a realm, it's now possible to conditionally choose which users require OTP based on for example a role or a request header (thanks to thomasdarimont for the contribution)
  • Realm Display Name - a display name has been added to realms, which makes it possible to set a human readable name to be shown on login screens, emails, etc.
  • WildFly 10.0.0.CR5 - Keycloak is now built on top of WildFly 10.0.0.CR5. Deploying the server overlay to WildFly 9 is no longer supported

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

Wednesday, 9 December 2015

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 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.