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.

Monday, 11 May 2015

Distribution changes

We're making some changes to how Keycloak is distributed. Some changes already arrived in 1.2.0, while others will come in 1.3.0. In this post I'll explain what changes we're making and why we're doing it.

Standalone will be the default download of the Keycloak server and will be the recommended option for production and also for non-JavaEE developers. While the appliance was built on the full WildFly application server, the new standalone download will be based on WildFly Core. This will provide a much smaller download and also reduce the footprint of the server.

For JavaEE developers we'll also provide an option to install Keycloak server into an existing WildFly application server. This download is not recommended for production. It will only be possible to install a release off Keycloak server onto one specific WildFly version.

These changes doesn't not affect adapters. Adapters will still be available for JBoss AS7, several versions of WildFly, EAP, Tomcat, Jetty and more.

There are a few reasons why we're going away from the WAR option:

  • Compatibility - We can focus on providing features instead of spending time trying to get things to work on multiple containers.
  • Testing - Again, we can focus on testing features rather than testing multiple containers.
  • WildFly features - We believe WildFly is the best container and it provides a lot of features other containers don't (for example modules, JBoss CLI, patching).
  • Integration - By only integrating with one container we can provide a single way of doing things. Some features are not feasible to add to multiple containers, for example authenticating clients with SSL certificates.

Wednesday, 6 May 2015

Persistent grants in Keycloak

In Keycloak versions before 1.2.0.CR1, we had two separate entities representing client applications. These were Applications, which didn't require consent from user after authentication and OAuth Clients, where the consent was always required.

In Keycloak 1.2.0.CR1 we simplified this and we merged both Applications and OAuth clients to single Client entity, which has on/off configuration switch in Keycloak admin console specifying if consent should be required or not.

When consent is not required from the user, then after user authenticates, the client application will automatically receive access token with all the personal info and permissions of the user. However if consent is required, Keycloak will display consent screen where user needs to confirm all the permissions required by particular Client.

From this release, the granted consents are persistent. This means that user doesn't need to confirm consent for particular client more times. Also each user has possibility to see all the available Client applications in Keycloak Account management and see:

  • Permissions he has for particular application
  • Granted personal info to particular application
  • Granted permissions for particular application

He can also revoke previously granted consent, so next time he authenticates to the application, the consent screen will be shown again.

Also it's possible to view and manage consents from Keycloak admin console. Admin can see the available consents for every user and he can revoke them.