Thursday, 20 August 2015

Improved LDAP integration with Keycloak

LDAP integration in Keycloak is done through User Federation SPI. It works in a way that users are synced from LDAP into Keycloak database. This is needed because Keycloak needs to store various metadata about users and some of them may not be supported by the LDAP schema. The configuration of LDAP Federation provider in admin console is flexible enough, so you can choose whether your LDAP server is read-only or writable and whether new users created in Keycloak will be synced back to LDAP or just into Keycloak database etc.

Before 1.3.1 release we pulled just basic data of users from LDAP like first name, surname, email, username and password. From 1.3.1 we improved this and added support for LDAP mappers. This allows you even more flexibility in configuring which LDAP data are synced to Keycloak and back (for writable LDAP). Right now we have:

  • User Attribute mapper - This allows to specify which LDAP attributes are mapped to which User attributes in Keycloak. As you can see there are various things you can configure. For example you can specify if attribute is read-only. In this case will be data synced from LDAP to Keycloak DB, but not back to LDAP in case that user is changed in Keycloak.
  • Full name mapper - Allows some additional flexibity in mapping full name. Many LDAP deployments have full name in single LDAP attribute like "cn: John Doe". This mapper will ensure that this single attribute is properly mapped to first name and lastname in Keycloak DB
  • Role mapper - Allows to map role mappings from LDAP into Keycloak. You can specify LDAP DN where are roles configured and you can specify whether the roles are mapped into realm roles in Keycloak or to client roles of specified client. You can also specify the mode like whether role mappings are read-only or writable to LDAP etc.
Mapper SPI provides few callback methods, which are executed at the point when new user is registered in Keycloak, imported from LDAP or searched in Keycloak. You can implement the SPI and add your own mapper if default implementations are not sufficient.

Mappers were added in older 1.3.1 release, but in 1.4 we added more improvements and fixed lot of bugs based on the feedback from community. We also added simple LDAP example, which is part of Keycloak example distribution . It's really easy to have the example up and running, as it contains embedded ApacheDS based LDAP server, so only thing you need is JDK and maven. More documentation about mappers is in Keycloak documentation but note that admin console contains tooltips on various options and hence is quite self-documenting.

It's still possible that you can see the issues - various organizations have various data in their LDAP servers and it's quite a challenge to handle everything correctly in Keycloak. In this case, feel free to write questions on our keycloak-user mailing list or create JIRA.

Wednesday, 29 July 2015

Keycloak 1.4.0.Final released

Keycloak 1.4.0.Final is available for download. As usual we've been busy bringing new features as well as a number of improvements and bug fixes (in fact we resolved 119 issues for this release!). The highlights of this release includes:
  • Authentication and Required Actions SPI - We've create SPIs for authentication flows and required actions and made existing flows pluggable. Currently the flows are hard-coded, but can be configured to some extent. In the future we'll make it possible to define your own authentication flows, authenticators as well as required actions.
  • Service account - We've added support for clients to obtain tokens on behalf of themselves. These tokens can be obtained by using the Client Credentials Grant flow. In the future we'll add support for additional mechanisms to authenticate clients.
  • User impersonation - Admins can now impersonate users. This allows admins to login to applications as a specific user without knowing the users credentials.
  • Re-captcha for registration - Re-captcha can be enabled for the registration page.
  • Upgrade to WildFly 9.0.1.Final - Keycloak is now built on top of WildFly 9.0.1.Final.
  • More details on server info page - There's now a bit more details about the Keycloak server on the server info page in the admin console.
  • Improvements to admin console We've had the UXP experts look at our admin console and we've already done some improvements. Expect more fine tuning of the admin console in the future.
For all changes in this release check out JIRA, to download the release go to the Keycloak website.

Wednesday, 17 June 2015

Keycloak 1.3.1.Final Released

Keycloak 1.3.1.Final has just been released. There's not too many new features this time around, but a lot of improvements.

LDAP enhancements and mappers

This release brings a lot of improvements to our LDAP User Federation Provider and also introduces mappers for User Federation making it possible to map attributes and groups from LDAP to attributes and role mappings in the Keycloak database.

WildFly 9.0.0.CR2

Keycloak standalone is now built on WildFly 9.0.0.CR2. This also means that the server-overlay is only deployable to WildFly 9.0.0.CR2 and we no longer support WildFly 8.2.0.Final for the server. There's also a server-overlay-eap which supports deploying the server to EAP 6.4.0.GA.

We've also added adapter for WildFly 9. There's different downloads for WildFly 8 and 9, so make sure you grab the correct one.

Admin events

You can now enable admin events through the admin console. This will log all modifications done by admins. You can view what changes where made and by whom.

Easier cluster setup

It's now slightly easier to setup clustering as the included standalone-ha.xml contains the Infinispan configuration. All you need to do now is to change providers in keycloak-server.json and add a shared database.

Recover admin password

In the past if you forgot your admin password your only option was to edit the database directly. We've now introduced a mechanism that lets you recover the admin password. Obviously this requires you to have direct access to the server.

Release notes and download

For all issues resolved in this release see the change log in JIRA. As usual refer to the migration guide before upgrading. To download yet another great Keycloak release go to our web site.

Sunday, 7 June 2015

OpenShift UI Console authentication with Keycloak and OpenID Connect

Two months ago OpenShift team implemented OpenID Connect support for authentication in its UI Console. Thanks to this work it can be easily integrated with Keycloak using fairly simple configuration. In this blog post I'll take you through example configuration process.

For complete documentation about configuration of authentication in OpenShift please check official guide here


  • Keycloak 1.2.0.Final zip distribution
  • Environment with properly installed and configured Docker 1.6. Steps below were verified on Fedora 22

Part 1 - Keycloak installation and SSL setup

OpenShift v3 requires usage of HTTPS and also verifies that requests are signed with valid Certificate Authority. For the purpose of this blog we'll take the shortest possible route and quickly generate our own CA and self signed certs. In practice even when using self signed certificates there are number of good practices to follow which we'll not cover here. Be warned that what is described below is not a proper production setup :)

Create a directory which will be used for Keycloak installation, certs and OpenShift configuration:
$ export DEMO_DIR=/home/bdaw/kc_os_demo 
$ mkdir $DEMO_DIR
$ cd $DEMO_DIR
$ mkdir certs
$ mkdir openshift
Those few commands below should generate dummy CA and a keystore for Keycloak with properly signed certificate. "localhost" should be used as a domain name and "secret" as a password.

$ cd certs
$ keytool -genkey -alias localhost -keyalg RSA -keystore keycloak.jks -validity 10950
Enter keystore password: secret
Re-enter new password: secret
What is your first and last name?
 [Unknown]: localhost
What is the name of your organizational unit?
 [Unknown]: IT
What is the name of your organization?
 [Unknown]: ACME
What is the name of your City or Locality?
 [Unknown]: Eden
What is the name of your State or Province?
 [Unknown]: Heaven
What is the two-letter country code for this unit?
 [Unknown]: AA
Is CN=localhost, OU=IT, O=ACME, L=Eden, ST=Heaven, C=AA correct?
 [no]: yes
Enter key password for <localhost>
 (RETURN if same as keystore password): secret
Re-enter new password: secret 
$ keytool -certreq -alias localhost -keystore keycloak.jks > keycloak.careq
Enter keystore password: secret 
$ openssl genrsa -out rootCA.key 2048 

$ openssl req -x509 -new -nodes -key rootCA.key -days 1024 -out rootCA.pem
Country Name (2 letter code) [XX]:AA
State or Province Name (full name) []:Heaven
Locality Name (eg, city) [Default City]:Eden
Organization Name (eg, company) [Default Company Ltd]:ACME
Organizational Unit Name (eg, section) []:IT
Common Name (eg, your name or your server's hostname) []:localhost
Email Address [] 
$ openssl x509 -req -in keycloak.careq -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out keycloak-ca.crt -days 500
Signature ok
Getting CA Private Key 
$ keytool -import -keystore keycloak.jks -file rootCA.pem -alias root
Enter keystore password: secret
Trust this certificate? [no]:  yes
$ keytool -import -alias localhost -keystore keycloak.jks -file keycloak-ca.crt
Enter keystore password: secret
Certificate reply was installed in keystore 
$ ls
keycloak-ca.crt keycloak.careq keycloak.jks rootCA.key rootCA.pem

Now unzip keycloak and copy created keystore
$ cd $DEMO_DIR
$ cp <dir_with_your_kc_zip>/ .
$ unzip keycloak-1.2.0.Final
$ cp $DEMO_DIR/certs/keycloak.jks $DEMO_DIR/keycloak-1.2.0.Final/standalone/configuration/
To configure Keycloak to use SSL you need to follow procedure described in documentation. As you already have properly generated and signed certs in a keystore only changes in standalone.xml need to be applied.

Open $DEMO_DIR/keycloak-1.2.0.Final/standalone/configuration/standalone.xml in your favourite text editor and apply changes listed below:

To the security-realms element add:
<security-realm name="UndertowRealm">
                <keystore path="keycloak.jks" relative-to="jboss.server.config.dir" keystore-password="secret" />
Find the element <server name="default-server"> (it's a child element of <subsystem xmlns="urn:jboss:domain:undertow:1.2">) and add:
<https-listener name="https" socket-binding="https" security-realm="UndertowRealm"/>
Additionally we need to avoid conflict with default ports used by OpenShift. Find and adjust line below to change port 8080 to 8180 and 8443 to 8543:
<socket-binding name="http" port="${jboss.http.port:8180}"/>
<socket-binding name="https" port="${jboss.https.port:8543}"/>

Part II - Keycloak Configuration - Realm and OpenID Connect client for OpenShift

Start Keycloak and create new realm for openshift configuration
$ cd $DEMO_DIR/keycloak-1.2.0.Final/bin
$ ./
Go to https://localhost:8543/auth/admin

Log in with credentials admin/admin

In the top right corner click on "Add realm" link. Use "openshift" as a name and click "Save". You can play with configuration a bit if you want - allowing user registration and etc.

As a next step create "openshift" client

On the left side click on "Clients" and then "create" button. Fill in "openshift" for both client ID and name and "https://localhost:8443/*" for valid redirect URIs. Leave all other fields with default values.

Go to "Credentials" tab and copy value of "secret" field. It will be needed later in OpenShift configuration.

To verify authentication we'll need a sample user. On the left side click on "Users" and then "Add user". Use "test-user" as a username and click save. Then go to "Credentials" tab and set new password - for simplicity just use "password" as a value and submit with Enter :)

Voila! Now Keycloak should be properly configured to provide authentication for OpenShift. As you can see above biggest part of it was actually not related to OpenID Connect and OpenShift at all but to proper generation of certificates and SSL configuration... :)

Part III Openshift installation and configuration

There are few different ways to install OpenShift which are described either in official documentation or on github. Fabric8 can be used as well as it was described by Marko in one of previous posts

Simplest way to obtain needed parts to try out UI authentication is to use docker image and this is the setup we'll follow.

Start another terminal windows (first one should be occupied with running Keycloak server).
$ export DEMO_DIR=/home/bdaw/kc_os_demo 
$ sudo docker run -it --name "openshift-origin" --net=host --privileged -v /var/run/docker.sock:/var/run/docker.sock -v $DEMO_DIR:/opt/demo/ openshift/origin start master --write-config="/opt/demo/openshift/config"
It should create configuration files and exit.

Open $DEMO_DIR/openshift/config/master-config.yaml in your favorite text editor and adust configuration as below.

Find "oauthConfig" section and replace whole "identityProviders" section under it with content below:
  - name: keycloak
    challenge: false
    login: true
      apiVersion: v1
      kind: OpenIDIdentityProvider
      ca: /opt/demo/certs/rootCA.pem
      clientID: openshift
      clientSecret: fdceb89f-3fa7-4b6d-8780-06074de5c62e
        - sub
        - preferred_username
        - name
        - email
        authorize: https://localhost:8543/auth/realms/openshift/tokens/login
        token: https://localhost:8543/auth/realms/openshift/tokens/access/codes

Important thing to not forget - replace "clientSecret" value with the one which you found in Keycloak Admin UI.

As you can see "ca" is pointing to our dummy CA certificate (rootCA.pem). Alternatively you can remove this line and just add this cert to your system. OpenShift will validate against system wide ones by default.

Additionally locate the line starting with "logoutURL" and point it to Keycloak:

logoutURL: "https://localhost:8543/auth/realms/openshift/protocol/openid-connect/logout?redirect_uri=https://localhost:8443/console"

That is pretty much everything which is required on OpenShift side

In the master-config.yaml you can see to which IP address container is bind by checking "masterPublicURL" value. Obviously there are few other and probably better ways to determine it upfront... :). In my case it is "". This URL needs to be added to "openshift" client configuration in Keycloak as "Valid Redirect URI".

Now you can start OpenShift container again:
$ sudo docker rm openshift-origin
$ sudo docker run -it --name "openshift-origin" --net=host --privileged -v /var/run/docker.sock:/var/run/docker.sock -v $DEMO_DIR:/opt/demo/ openshift/origin start master --config="/opt/demo/openshift/config/master-config.yaml"
Go to "https://localhost:8443/console" and log in as "test-user" with password "password". Please note that you can also logout and this will properly get propagated to Keycloak.

In case of any issues you should hopefully see a meaningful error message logged either by OpenShift or by Keycloak server. Most common problems are related to network connectivity between OS and KC, certificate validation on the OS side and having proper redirect URI whitelisted in Keycloak. 

Huge thanks to Jordan Liggitt who implemented OpenID Connect support in OpenShift and Rob Cernich who contributed to it and initially tested it with Keycloak. You guys rock! :) 

Monday, 25 May 2015

Keycloak session at Red Hat Summit and DevNation

When securing applications and services there are a lot of challenges you will encounter. Most of these are applicable to you both if you are developing new applications or if you already have existing security solutions in place.

Challenges you'll encounter include:

  • Keeping user passwords safe
  • Single-Sign On/Out
  • Multi-factor authentication
  • Social logins
  • Mobile devices
  • Public APIs
  • Managing users, permissions and sessions
  • Integrating with existing infrastructure such as LDAP server
  • Integrating with partners solutions

In the Keycloak session available to both Summit and DevNation attendees we'll talk about how it doesn't have to be hard to solve these challenges. In fact it can be quite simple by using Keycloak, an open source Identity and Access Management solution from Red Hat JBoss. We'll show how Keycloak can be used to secure a modern architecture, including HTML5 applications, mobile applications and RESTful services. We'll also show how you can leverage the integration features provided by Keycloak to integrate with existing security infrastructure and partners.

Thursday, 21 May 2015

Securing Microservices

In a traditional multi-tiered architecture like the one shown in the picture below a server-side web tier deals with authenticating the user by calling out to a relational database or an LDAP server. An HTTP session is then created containing the required authentication and user details. The security context is propagated between the tiers within the application server so there's no need to re-authenticate the user.

With a microservice architecture the server-side web application is gone, instead we have HTML5 and mobile applications on the client side. The applications invoke multiple services, which may in turn call other services. In this architecture there's no longer a single layer that can deal with authentication and usually it's stateless as well so there's no HTTP session.

As microservices is all about having many smaller services each that deal with one distinct task the obvious solution to security is an authentication and authorization service. This is where Keycloak and OpenID Connect comes to the rescue. Keycloak provides the service you need to secure micro services.

The first step to securing micro services is authenticating the user. This is done by adding the Keycloak JavaScript adapter to your HTML5 application. For mobile applications there's a Keycloak Cordova adapter, but there's also native support though the AeroGear project.

In an HTML5 application you just need to add a login button and that's pretty much it. When the user clicks the login button the users browser is redirected to the login screen on the Keycloak server. The user then authenticates with the Keycloak server. As the authentication is done by the Keycloak server and not your application it's easy to add support for multi-factor authentication or social logins without having to change anything in your application.

Once the user is authenticated, Keycloak gives the application a token. The token contains details about the user as well as permissions the user has.

The second step in securing micro services is to secure them. Again, with Keycloak this is easy to do with our adapters. We've got JavaEE adapters, NodeJS adapters and are planning to adding more in the future. If we don't have an adapter it's also relatively easy to verify the tokens yourself. A token is basically just a signed JSON document and can be verified by the services itself or by invoking the Keycloak server.

If a service needs to invoke another service it can pass on the token it received, which will invoke the other service with the users permissions. Soon we'll add support for services to authenticate directly with Keycloak to be able to invoke other services with their own permissions, not just on behalf of users.

For more details about OpenID Connect you can look at the OpenID Connect website, but the nice thing is with Keycloak you don't really need to know the low level details so it's completely optional. As an alternative just go straight to the Keycloak website, download the server and adapters, and check out our documentation and many examples.

Tuesday, 19 May 2015

Keycloak 1.2.0.Final released

No major changes since 1.2.0.CR1 only some minor bug fixes.

For full details see JIRA and to download go to SourceForge.