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.

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

10 comments:

  1. Hi very good blog, can you explain more about : We have built-in support for OpenID Connect and SAML 2.0. We like to use keycloak as a identity broker for saml. But is can not find how to configure this. 

    ReplyDelete
    Replies
    1. I forgot to specify that OpenID Connect and SAML 2.0 brokering, as well as Protocol Mapping, is coming in 1.2.0.Beta1 which is due to be released any day now.

      Delete
  2. HI Stian,

    JBoss Keycloak rocks and its wonderful that more customization is coming .

    George Leon

    ReplyDelete
  3. Hi Stian,
    I am trying to learn the Keycloak and went through lot of documentation and , I am trying to configure the SAML SSO and and authentication through Ldap . I was going through all the documentation , there was no video and documentation how the admin console display all the applications like customer portal and product portal. All I have is videos about the how to generate the keycloak jason and change teh web.xml .

    Is there any clear documentation , how to configure a new application in keycloak and access through SSO . It will help me a lot . Thanks in advance,

    ReplyDelete
  4. Hi Stian,
    I am trying to learn the Keycloak and went through lot of documentation and , I am trying to configure the SAML SSO and and authentication through Ldap . I was going through all the documentation , there was no video and documentation how the admin console display all the applications like customer portal and product portal. All I have is videos about the how to generate the keycloak jason and change teh web.xml .

    Is there any clear documentation , how to configure a new application in keycloak and access through SSO . It will help me a lot . Thanks in advance,

    ReplyDelete
    Replies
    1. Please use our user mailing list for general questions. https://lists.jboss.org/mailman/listinfo/keycloak-user

      Delete
  5. Jayapriya Atheesan16 November 2015 at 21:57

    Hi,
    How can we make an application to access keycloak with different user privileges as admin and an user?

    ReplyDelete
    Replies
    1. Please use our user mailing list for general questions. https://lists.jboss.org/mailman/listinfo/keycloak-user

      Delete
  6. Hi,
    one question regarding user federation, is there an out of the box solution to sync users from a RDBMS? In the UI I can only select between kerberos and ldap.

    ReplyDelete
    Replies
    1. No, you will currently have to implement your own custom provider for it. With the new user storage spi that was introduced in 2.3 this should be significantly simpler than it used to be though. Take a look at the example we have for it.

      Delete

Please only add comments directly associated with the post. For general questions use the Keycloak user mailing list.