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

Tuesday, 10 March 2015

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.

Monday, 2 March 2015

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!

Wednesday, 4 February 2015

Keycloak clustering - Improving availability and scalability withInfinispan

One of the major features introduced in Keycloak 1.1.0.Final is improved clustering capabilities. Through clustering Keycloak you can provide high availability and scalability, which is obviously important if you rely on Keycloak to login to critical applications.

We could have chosen to build this clustering capability from the ground, but we're in the business of developing an identity and access management solution not a clustering solution. Second option could have been the excellent JGroups, but that's still low level stuff though. Luckily at JBoss we have no shortage of middleware and we obviously have a solution for this. Unless you've been living under a stone the last few years you should have heard about it, it's called Infinispan!

Infinispan is a distributed in-memory key/value data grid and cache. It's a mature project and loaded with features, which fits our needs perfectly.

In Keycloak we have 3 different types of data:
  • Realm and application meta-data
  • Users, credentials and role-mappings
  • User sessions

Each have different needs when it comes to clustering.

Realm and application meta-data are frequently read, but unless your sysadmin really loves reconfiguring things, not so frequently changed. There's also only so many realms and applications in an organization so the size is limited. This mean we can save it all in a database and cache it all in memory as its access. If a change is made it's written directly to the database. To make sure all nodes retrieve the updates we use an invalidation cache. An invalidation cache simply sends a message to the cluster that invalidates an entry in the cache. Next time the data is requested it won't be in the cache and the updated version is loaded from the database. This is beneficial for us compared to a replicated cache as it doesn't send sensitive data throughout the cluster and also reduces network traffic.

Users are by default handled the same way as realm and app meta-data. It's good practice to change your password once in a while, but certainly not every time you  log in! So that means users are also frequently read, but not so frequently changed. There can be a lot more users than realms though, so we set a maximum number of users that are cached. This results in active users being held in memory, while inactive users are purged from memory.

User sessions are very different as they are frequently updated. Every time a user logs in a new user session is created. We also have a mechanism to expire idle sessions, which results in every time a user session is accessed it's also updated. If we stored user sessions in a database and used an invalidation cache performance and scalability wouldn't be very good. Also, user sessions are not critical data so doesn't have to be persisted in a database. In the worst case scenario if a user session is lost a user has to log back in. For user sessions we use a distributed cache. This provides good performance as they are not persisted, it provides good scalability as they're split into segments where each node only holds a subset of the sessions in memory. Finally, if you really need higher availability for user sessions we recommend you configure replicating each segment to more than one node rather than persisting the sessions.

Thursday, 29 January 2015

Login to Jenkins with Keycloak

Thanks to Nadeem Mohammad it's now easy to login to your Jenkins server with Keycloak. For more details have a look at Jenkins Wiki and the Youtube demo. The source code is available in our github.

Wednesday, 28 January 2015

Keycloak 1.1.0.Final Released

The Keycloak team is proud to announce the release of Keycloak 1.1.0.Final. Highlights in this release includes:
  • SAML 2.0
  • Clustering
  • Jetty, Tomcat and Fuse adapters
  • HTTP Security Proxy
  • Automatic migration of db schema

We're already started working on features for the next release. Some exiting features coming soon includes:
  • Identity brokering
  • Custom user profiles
  • Kerberos
  • OpenID Connect interop

Tuesday, 16 December 2014

Merry Christmas from the Keycloak team

2014 was the year of Keycloak! At least that was the case for us on the Keycloak team. In January we released the very first alpha of the project. The first stable release wasn't out until September, but in return we added a lot more features as well as reaching a very high level of stability for a 1.0.

Since then we've delivered a number of security and bug fixes for 1.0, while continuing to bake in new exiting features for 1.1. We're planning to do a stable release of 1.1 early in the New Year, which will bring SAML 2, much improved clustering and a number of new application adapters.

Not only have we managed to provide a feature rich and easy to use open source security solution, but we've also managed to build an awesome community around the project. We've had over 5000 downloads, over 2500 commits from 32 contributors and our developer and user mailing lists are very active. Keycloak is already in use in production on a number of projects, in fact some has even used it in production since our first alpha release!

Our road-map for 2015 is not written in stone, but expect at least some of the following features to be delivered in 2015:
  • Custom user profiles - this will let you configure the attributes for a user profile, which should be visible on the registration screen and account management, as well as specify validation

  • Identity Brokering - we're adding support to authenticate with external Identity Providers via OpenID Connect, SAML 2.0 and Kerberos

  • Two-Factor Authentication - currently we only support Google Authenticator or FreeOTP applications for two-factor authentication, but we plan to make it possible to add your own and provide some more out of the box

  • Client Accounts - these will be special user accounts directly linked to a client, allowing a client to access services as itself not just on-behalf of users

  • Client Certificates - support authentication of clients with certificates

  • Client Types - at the moment we have applications and oauth clients, the main difference being oauth clients require users to grant permissions to roles. To simplify the admin console we plan to introduce a single unified view for clients and also introduce new types such as devices

  • Internationalization - internationalization support for login and account management pages

  • SMS - enable SMS to recover passwords, as a 2nd factor authentication mechanism and to be notified about events like login failures

  • OpenID Connect Dynamic Registration -  allows clients to dynamically register with Keycloak. We'll also look at passing the OpenID Connect Interop testing

  • Mapping of users and tokens - custom mapping of user profiles from external identity stores and tokens from external Identity Providers
We also have ideas for some bigger features, but we'll leave those as a surprise for 2015!

Finally, I'd like to wish everyone a Merry Christmas and a Happy New Year.