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.

Themes

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

PicketLink and Keycloak projects are merging!

Together with new PicketLink 2.7.0.Final release, we would like to announce that PicketLink and Keycloak projects will be merging their efforts. Code base of both will get unified and new features will be developed in a single place.

As part of this merge all key features of PicketLink will get included into Keycloak. Combining strengths of both projects and providing their communities a single polished and unified security solution. Joining both efforts should enable faster progress on new features which will be beneficial for all users and developers leveraging those solutions.

PicketLink origins

PicketLink project was originally started being a central hub for all security related efforts for Red Hat Middleware. It is a security framework providing a rich set of capabilities for Java EE applications including Authentication, Authorization or Permissions APIs and flexible IDM solution. One of other key features adopted and used in many organizations world wide is Federation component providing SAML Identity and Service Provider capabilities. On top of that it contains a toolbox of different useful APIs and helper classes in identity and security areas.

Keycloak origins

Keycloak initially originated as a merge of two initiatives. First one was SkeletonKey module from RestEasy project aiming to provide easy security for REST APIs in Java EE world. Second part was a prototype to provide easily consumable Social Login capabilities in a form of Identity Broker. Both merged together with aim to expose out of the box security capabilities for application developers that they could seamlessly integrate.

Reasons for merging both projects

While both project initially covered slightly different areas and angles they naturally started overlapping over time. Keycloak from being Identity Broker grew into being fully fledged Identity Provider. Initially it was only exposing basic token based security for REST APIs built on top of OAuth2 spec. Currently it aims full OpenID Connect interoperability, providing base SAML IdP capabilities and working on developing integration points via Kerberos or Identity Provider Brokering set of features.  With all of this work happening Keycloak naturally stepped into area which was initially covered by PicketLink with it’s framework capabilities.

Major difference between PicketLink and Keycloak has always been framework vs out of the box nature of both solutions. PicketLink was always focusing on providing easily used set of base features with flexibility to extend them your way to build on top. This is still the key strength that many users love. It acts a security toolbox from which you can pick from according to your needs. Original idea behind Keycloak was to provide out of the box solution which could be embedded or integrated into your application. Externalizing most of common security capabilities that developers need to repeatedly provide for their applications - like login screens, OTP or social login. All of those features accompanied with extensive and well designed UI console, resulted in skyrocketing adoption in the community

Developers engaged in both projects started hearing repeating questions from community users around overlap, differences and their future. After long debates we decided it is high time to merge them!

We will start merging key parts of PicketLink codebase into Keycloak and proceed further under this project name.

What you can expect happening during next few months?

• Specific parts of PicketLink codebase being forked and merged into Keycloak. We are starting with PicketLink Federation / SAML. 
• Inclusion or implementation of particular features will get discussed in public on the Keycloak project mailing list. We are looking forward for your participation there as we would like to hear your feedback on changes that we are doing. 
• Web sites for both projects will get slightly changed to reflect new situation.
• Many new cool features coming shortly!

What happens to PicketLink project? 

Short answer is - nothing dramatic really… No one is switching the lights off! All project sources, materials and communication channels will still remain available and open for the community. Developers associated with Red Hat will be focusing much more on new features development in Keycloak project. However if there are contributions coming in from the community we’ll still assist you as much as we can. Although expect repeating encouragement from our side to try Keycloak out everytime you ask for a new PicketLink feature ;)

Please find additional FAQ on PicketLink project website. 

We hope it will answer most of your questions or concerns.

Pedro Igor Silva - PicketLink Project Leader
Bill Burke and Stian Thorgersen - Keycloak Project Leaders
Bolesław Dawidowicz - Security Platform Architect at Red Hat.

Keycloak clustering: part 2 - Clustering support for applications

Previous blog post mentioned our support for clustered Keycloak server. From 1.1.0.Final, we have also clustering support for applications secured by Keycloak! All common scenarios like SSO, Single sign-out or propagation of global admin events should be cluster-safe now.

HTTP Session or cookie

By default, the servlet web application secured by Keycloak uses HTTP session to store information about authenticated user account. From Keycloak 1.1.0.Final, this info could be replicated across cluster and your application will safely survive failover of some cluster node. However if you don't need or don't want to use HTTP Session, you may alternatively save all info about authenticated account into cookie. In this case, no HTTP Session replication will happen among application cluster nodes. This is useful especially for stateless applications.

Backend requests optimization

Keycloak has support for OpenID Connect protocol, which is used for communication between Keycloak server and applications. The communication happens by "front" channel (browser redirects), but also by "backend" channel, when Keycloak server and application server sends messages directly to each other without involving web browser. We added possibility that "backend" channel communication is optimized and Keycloak server and application server communicates directly with each other without proxying requests through loadbalancer. This is especially useful when Keycloak and applications are deployed on same host. For example when you have cluster nodes "node1", "node2" and some HTTP Session is handled on "node2", the application will communicate by backend channel with Keycloak server on "node2" as well.

Nodes autodiscovery

In some cases admin may want to propagate some global "admin" tasks triggered from Keycloak admin console to all registered cluster nodes. For example push new notBefore for realm, or logout all users from all applications on all cluster nodes. In this case Keycloak should be aware of all application cluster nodes, so it could send event to all of them. To achieve this, we support auto-discovery mechanism.

Once new application node joins cluster, it sends registration request to Keycloak server. The request may be re-sent to Keycloak in configured periodic intervals. Admin can monitor in Keycloak admin console all registered application nodes, which are actually auto-registered and send "alive" request to them. He can also manually register or unregister nodes if don't want to rely on auto-discovery mechanism. When admin triggers "global" event, like forced logout of all users, it will be sent to all registered application cluster nodes.

For more info, check our documentation and try it in action!