Wednesday, 18 March 2015

Customizing Keycloak

With Keycloak we strive to create an out of the box security solution that works for as many scenarios as possible, but there are times when some customization is needed. Most will want to adapt the end-user visible pages to integrate well with their corporate identity and applications. Some will want to federate users with a bespoke relational database. Others would like a highly customized authentication flow. The list goes on, but what's common is that most advanced deployments of Keycloak will require some level of customization beyond what we provide out of the box. This is why customization is a core feature of Keycloak.

Customization points in Keycloak are provided through a number of Service Provider Interfaces (SPI). We have quite a few already and plan to introduce more in the future. This article describes some of the most important SPIs we have at the moment and also briefly mentions some we plan to introduce in the future.


Keycloak provides login and account management pages that are visible to end-users. To make these integrate well with applications and corporate identities these are themable. This can range from adding a custom stylesheet to modifying the HTML templates. It's even possible to replace our implementation completely and implement your own provider of the Account Management and Login Form SPIs.

The example below shows how the look and feel of the login screen can be customized through themes.

Event Listeners

When a user logs in, modifies the account or an application retrieves a token, an event is fired with details about what happened. By implementing a provider for the Event Listener SPI it's possible to be notified and react to these events. This could for example be used to push events to a central audit log or to update statistics about how many users have registered to your site after a marketing campaign.

The image below shows a list of events viewed through the admin console.

Identity Brokering

Through Identity Brokering it's easy to allow users to authenticate to Keycloak using external Identity Providers or Social Networks. We have built-in support for OpenID Connect and SAML 2.0 as well as a number of social networks such as Google, GitHub, Facebook and Twitter. Through the Identity Provider SPI you can also add your own. It's even possible to expose the external token to your application for example if it wants to retrieve a list of Facebook friends.

User Federation

Keycloak maintains its own user database, but it has a very flexible user federation model which allows syncing users from external sources. This makes it possible to sync users from LDAP, Active Directory, RDBMS or any custom source into Keycloak. It's also possible to push changes back to the external source.

Protocol Mapping

We're soon about to introduce a very flexible approach to defining the contents of tokens. With protocol mapping you can define exactly what attributes goes into the token provided to your application by choosing from a set of built-in options or by implementing your own mappers.

The screenshot below shows the default mappings for an application that uses OpenID Connect.

More to come

We'll be introducing more extension points to Keycloak in 2015. Here's a few of those we're planing to add:

  • Mapping claims from external tokens - customize how tokens from external Identity Providers are mapped
  • Mapping attributes from User Federation sources - customize how attributes from external user sources are mapped, including the ability to map ldap groups onto roles
  • Authentication - introduce custom authentication mechanisms, including additional options for multi-factor authentication
  • Required action - define custom actions that users are required to perform during login
  • Admin events - fire events when admins view or make any changes