Keycloak 3.4.2.Final Released

We've just released Keycloak 3.4.2.Final.

To download the release go to the Keycloak homepage.

The full list of resolved issues is available in JIRA.

Upgrading

Before you upgrade remember to backup your database and check the upgrade guide for anything that may have changed.

Keycloak 3.4.1.Final Release

We've just released Keycloak 3.4.1.Final.

To download the release go to the Keycloak homepage.

The full list of resolved issues is available in JIRA.

Upgrading

Before you upgrade remember to backup your database and check the upgrade guide for anything that may have changed.

Keycloak 3.4.1.CR1 released

We've just released Keycloak 3.4.1.CR1.

To download the release go to the Keycloak homepage.

Highlights

Cross DC

A lot of work has gone into finishing the Cross DC support and it should now be ready to use.

Database Replication

We're now testing database replication with MySQL Galera and Oracle RAC. This is related to Cross DC support which requires a master node in each DC.

Loads more..

• Loads and loads of fixes

The full list of resolved issues is available in JIRA.

Upgrading

Before you upgrade remember to backup your database and check the upgrade guide for anything that may have changed. Release candidates are not recommended in production and we do not support upgrading from release candidates.

Keycloak 3.4.0.Final released

We've just released Keycloak 3.4.0.Final.

To download the release go to the Keycloak homepage.

The full list of resolved issues is available in JIRA.

Upgrading

Before you upgrade remember to backup your database and check the upgrade guide for anything that may have changed.

Keycloak 3.4.0.CR1 released

We've just released Keycloak 3.4.0.CR1.

To download the release go to the Keycloak homepage.

Highlights

Token exchange

The token exchange service allows clients to exchange tokens for different tokens. There's quite a few options available so check out the docs for more details.

Fine-grained permissions for admin endpoints

By leveraging our authorization services we've made it possible to control permissions in the admin endpoints almost exactly how you want. For more details check the docs.

Cross DC

A lot more work has gone into this release around cross DC support. Docs are still not ready and there's still some minor polish left. This will come soon.

Upgraded to WildFly 11 Final

We've upgraded the underlying container to WildFly 11 Final.

Support MySQL and PostgreSQL in main Keycloak Docker image

We used to have separate Docker images for MySQL and PostgreSQL, but now we have one that supports them all.

AsciiDoctor

Our docs used to be built and hosted on GitBook. We've recently moved to using pure AsciiDoctor to build the docs. The main reason behind this move was to closer align with how we build documentation for the productized version of Keycloak (RH-SSO).

Loads more..

• Script based protocol mapper for OIDC - thanks to thomasdarimont
• Blacklisted password policy- thanks to thomasdarimont
• Login with PayPal - thanks to petlys
• Almost 200 - we almost resolved 200 issues for this one (197!)

The full list of resolved issues is available in JIRA.

Upgrading

Before you upgrade remember to backup your database and check the upgrade guide for anything that may have changed. Release candidates are not recommended in production and we do not support upgrading from release candidates.

Keycloak 3.3.0.Final released

We've just released Keycloak 3.3.0.Final.

The release contains upgrade of Keycloak server to Wildfly 11.0.0.Final. There are also few bugfixes there.

To download the release go to the Keycloak homepage.

The full list of resolved issues is available in JIRA.

Upgrading

Before you upgrade remember to backup your database and check the migration guide.

X.509 and Smartcard Authentication with Keycloak

If you want to do X.509 and Smartcard authentication with Keycloak check out this blog post from Stephen Higgs. It walks you through how to setup X.509 authentication with Keycloak and a Yubikey Neo device.

Keycloak 3.3.0.CR2 Released

We've just released Keycloak 3.3.0.CR2.

There's not much here except a few bug fixes. We're still waiting for WildFly 11 Final to be release before we release Keycloak 3.3.0.Final.

To download the release go to the Keycloak homepage.

The full list of resolved issues is available in JIRA.

Upgrading

Before you upgrade remember to backup your database and check the migration guide. Release candidates are not recommended in production and we do not support upgrading from release candidates.

Cross-Datacenter support in Keycloak

In Keycloak 3.3.0.CR1 we added basic setup for cross-datacenter (cross-site) replication. This blogpost covers some details about it. It consists of 2 parts:

• Some technical details and challenges, which we needed to address
• Example setup

If you're not interested in too much details, but rather want to try things, feel free to go directly to the example. Or viceversa :-)

Here is the picture with the basic example architecture

Technical details

In typical scenario, end user's browser sends HTTP request to the frontend loadbalancer server. This is usually HTTPD or Wildfly with mod_cluster, NGinx, HA Proxy or other kind of software or hardware loadbalancer. Loadbalancer then forwards HTTP requests to the underlying Keycloak instances, which can be spread among multiple datacenters (sites). Loadbalancers typically offer support for sticky sessions, which means that loadbalancer is able to forward HTTP requests from one user always to the same Keycloak instance in same datacenter.

There are also HTTP requests, which are sent from client applications to the loadbalancer. Those HTTP requests are backchannel requests. They are not seen by end user's browser and can't be part of sticky session between user and loadbalancer and hence loadbalancer can forward the particular HTTP request to any Keycloak instance in any datacenter. This is challenging as some OpenID Connect or SAML flows require multiple HTTP requests from both user and application. Because we can't reliably rely on sticky sessions, it means that some data need to be replicated between datacenters, so they are seen by subsequent HTTP requests during particular flow.

Authentication sessions

In Keycloak 3.2.0 we did some refactoring and introduced authentication sessions. There is separate infinispan cache authenticationSessions used to save data during authentication of particular user. This cache usually involves just browser and Keycloak server, not the application. Hence we usually can rely on sticky sessions and authenticationSessions cache content usually doesn't need to be replicated among datacenters.

Action tokens

In 3.2.0 we introduced also action tokens, which are used typically for scenarios when user needs to confirm some actions asynchronously by email. For example during forget password flow. The actionTokens infinispan cache is used to track metadata about action tokens (eg. which action token was already used, so it can't be reused second time) and it usually needs to be replicated between datacenters.

Database

Keycloak uses RDBMS to persist some metadata about realms, clients, users etc. In cross-datacenter setup, we assume that either both datacenters talk to same database or every datacenter has it's own database, but both databases are synchronously replicated. In other words, when Keycloak server in site 1 persists any data and transaction is commited, those data are immediatelly visible by subsequent DB transactions on site 2.

Details of DB setup are out-of-scope of Keycloak, however note that many RDBMS vendors like PostgreSQL or MariaDB offers replicated databases and synchronous replication. Databases are not shown in the example picture above just to make it a bit simpler.

Caching and invalidation of persistent data

Keycloak uses infinispan for cache persistent data to avoid many unecessary requests to the database. Caching is great for save performance, however there is one additional challenge, that when some Keycloak server updates any data, all other Keycloak servers in all datacenters need to be aware of it, so they invalidate particular data from their caches. Keycloak uses local infinispan caches called realms, users and authorization to cache persistent data.

We use separate cache work, which is replicated among all datacenters. The work cache itself doesn't cache any real data. It is defacto used just for sending invalidation messages between cluster nodes and datacenters. In other words, when some data is updated (eg. user "john" is updated), the particular Keycloak node sends the invalidation message to all other cluster nodes in same datacenter and also to all other datacenters. Every node then invalidates particular data from their local cache once it receives the invalidation message.

User sessions

There are infinispan caches sessions and offlineSessions, which usually need to be replicated between datacenters. Those caches are used to save data about user sessions, which are valid for the whole life of one user's browser session. The caches need to deal with the HTTP requests from the end user and from the application. As described above, sticky session can't be reliably used, but we still want to ensure that subsequent HTTP requests can see the latest data. Hence the data are replicated.

Brute force protection

Finally loginFailures cache is used to track data about failed logins (eg. how many times user john filled the bad password on username/password screen etc). It is up to the admin if he wants this cache to be replicated between datacenters. To have accurate count of login failures, the replication is needed. On the other hand, avoid replicating this data can save some performance. So if performance is more important then accurate counts of login failures, the replication can be avoided.

Communication details

Under the covers, there are multiple separate infinispan clusters here. Every Keycloak node is in the cluster with the other Keycloak nodes in same datacenter, but not with the Keycloak nodes in different datacenters. Keycloak node doesn't communicate directly with the Keycloak nodes from different datacenters. Keycloak nodes use external JDG (or infinispan server) for communication between datacenters. This is done through the Infinispan HotRod protocol.

The infinispan caches on Keycloak side needs to be configured with the remoteStore, to ensure that data are saved to the remote cache, which uses HotRod protocol under the covers. There is separate infinispan cluster between JDG servers, so the data saved on JDG1 on site 1 are replicated to JDG2 on site 2.

Finally the receiver JDG server then notifies Keycloak servers in it's cluster through the Client Listeners, which is feature of HotRod protocol. Keycloak nodes on site 2 then update their infinispan caches and particular userSession is visible on Keycloak nodes on site 2 too.

Example setup

This is the example setup simulating 2 datacenters site 1 and site 2 . Each datacenter (site) consists of 1 infinispan server and 2 Keycloak servers. So 2 infinispan servers and 4 Keycloak servers are totally in the testing setup.

• Site1 consists of infinispan server jdg1 and 2 Keycloak servers node11 and node12 .
• Site2 consists of infinispan server jdg2 and 2 Keycloak servers node21 and node22 .
• Infinispan servers jdg1 and jdg2 forms cluster with each other and they are used as a channel for communication between 2 datacenters. Again, in production, there is also clustered DB used for replication between datacenters (each site has it's own DB), but that's not the case in the example, which would just use single DB.
• Keycloak servers node11 and node12 forms cluster with each other, but they don't communicate with any server in site2 . They communicate with infinispan server jdg1 through the HotRod protocol (Remote cache).
• Same applies for node21 and node22 . They have cluster with each other and communicate just with jdg2 server through the HotRod protocol.

Example setup assumes all 6 servers are bootstrapped on localhost, but each on different ports. It also assumes that all 4 Keycloak servers talk to same database, which can be either locally set MySQL, PostgreSQL, MariaDB or any other. In production, there will be rather separate synchronously replicated databases between datacenters.

Infinispan Server setup

1) Download Infinispan 8.2.6 server and unzip to some folder

2) Add this into JDG1_HOME/standalone/configuration/clustered.xml into cache-container named clustered :

<cache-container name="clustered" default-cache="default" statistics="true">
        ...
        <replicated-cache-configuration name="sessions-cfg" mode="ASYNC" start="EAGER" batching="false">        
            <transaction mode="NON_XA" locking="PESSIMISTIC"/>               
        </replicated-cache-configuration>                                
       
        <replicated-cache name="work" configuration="sessions-cfg" />    
        <replicated-cache name="sessions" configuration="sessions-cfg" />       
        <replicated-cache name="offlineSessions" configuration="sessions-cfg" />        
        <replicated-cache name="actionTokens" configuration="sessions-cfg" />        
        <replicated-cache name="loginFailures" configuration="sessions-cfg" />
                
</cache-container>

3) Copy the server into the second location referred later as JDG2_HOME

4) Start server jdg1:

cd JDG1_HOME/bin
./standalone.sh -c clustered.xml -Djava.net.preferIPv4Stack=true \
-Djboss.socket.binding.port-offset=1010 -Djboss.default.multicast.address=234.56.78.99 \
-Djboss.node.name=jdg1

5) Start server jdg2:

cd JDG2_HOME/bin
./standalone.sh -c clustered.xml -Djava.net.preferIPv4Stack=true \
-Djboss.socket.binding.port-offset=2010 -Djboss.default.multicast.address=234.56.78.99 \
-Djboss.node.name=jdg2

6) There should be message in the log that nodes are in cluster with each other:

Received new cluster view for channel clustered: [jdg1|1] (2) [jdg1, jdg2]

Keycloak servers setup

1) Download Keycloak 3.3.0.CR1 and unzip to some location referred later as NODE11

2) Configure shared database for KeycloakDS datasource. Recommended to use MySQL, MariaDB or PostgreSQL. See Keycloak docs for more details

3) Edit NODE11/standalone/configuration/standalone-ha.xml :

3.1) Add attribute site to the JGroups UDP protocol:

<stack name="udp">
    <transport site="${jboss.site.name}" socket-binding="jgroups-udp" type="UDP">

3.2) Add output-socket-binding for remote-cache into socket-binding-group element:

<socket-binding-group ... >
    ...
    <outbound-socket-binding name="remote-cache">
        <remote-destination host="localhost" port="${remote.cache.port}">
        </remote-destination>
    </outbound-socket-binding>
    
</socket-binding-group>    

3.3) Add this module attribute into cache-container element of name keycloak :

 <cache-container jndi-name="infinispan/Keycloak" module="org.keycloak.keycloak-model-infinispan" name="keycloak">

3.4) Add the remote-store into work cache:

<replicated-cache mode="SYNC" name="work">
    <remote-store cache="work" fetch-state="false" passivation="false" preload="false" 
          purge="false" remote-servers="remote-cache" shared="true">    
        <property name="rawValues">true</property>
        <property name="marshaller">org.keycloak.cluster.infinispan.KeycloakHotRodMarshallerFactory</property>
    </remote-store>
</replicated-cache>

3.5) Add the store like this into sessions cache:

<distributed-cache mode="SYNC" name="sessions" owners="1">
    <store class="org.keycloak.models.sessions.infinispan.remotestore.KeycloakRemoteStoreConfigurationBuilder" 
      fetch-state="false" passivation="false" preload="false" purge="false" shared="true">   
        <property name="remoteCacheName">sessions</property> 
        <property name="useConfigTemplateFromCache">work</property>
    </store>
</distributed-cache>

3.6) Same for offlineSessions and loginFailures caches:

<distributed-cache mode="SYNC" name="offlineSessions" owners="1">
    <store class="org.keycloak.models.sessions.infinispan.remotestore.KeycloakRemoteStoreConfigurationBuilder" 
      fetch-state="false" passivation="false" preload="false" purge="false" shared="true">   
        <property name="remoteCacheName">offlineSessions</property> 
        <property name="useConfigTemplateFromCache">work</property>
    </store>
</distributed-cache>


<distributed-cache mode="SYNC" name="loginFailures" owners="1">
    <store class="org.keycloak.models.sessions.infinispan.remotestore.KeycloakRemoteStoreConfigurationBuilder" 
      fetch-state="false" passivation="false" preload="false" purge="false" shared="true">   
        <property name="remoteCacheName">loginFailures</property> 
        <property name="useConfigTemplateFromCache">work</property>
    </store>
</distributed-cache>

3.7) The configuration of distributed cache authenticationSessions and other caches is left unchanged.

3.8) Optionally enable DEBUG logging into logging subsystem:

<logger category="org.keycloak.cluster.infinispan">
    <level name="DEBUG">
</level></logger>
<logger category="org.keycloak.connections.infinispan">
    <level name="DEBUG">
</level></logger>
<logger category="org.keycloak.models.cache.infinispan">
    <level name="DEBUG">
</level></logger>
<logger category="org.keycloak.models.sessions.infinispan">
    <level name="DEBUG">
</level></logger>

4) Copy the NODE11 to 3 other directories referred later as NODE12, NODE21 and NODE22.

5) Start NODE11 :

cd NODE11/bin
./standalone.sh -c standalone-ha.xml -Djboss.node.name=node11 -Djboss.site.name=site1 \
-Djboss.default.multicast.address=234.56.78.100 -Dremote.cache.port=12232 -Djava.net.preferIPv4Stack=true \
-Djboss.socket.binding.port-offset=3000

6) Start NODE12 :

cd NODE12/bin
./standalone.sh -c standalone-ha.xml -Djboss.node.name=node12 -Djboss.site.name=site1 \
-Djboss.default.multicast.address=234.56.78.100 -Dremote.cache.port=12232 -Djava.net.preferIPv4Stack=true \
-Djboss.socket.binding.port-offset=4000

The cluster nodes should be connected. This should be in the log of both NODE11 and NODE12:

Received new cluster view for channel hibernate: [node11|1] (2) [node11, node12]

7) Start NODE21 :

cd NODE21/bin
./standalone.sh -c standalone-ha.xml -Djboss.node.name=node21 -Djboss.site.name=site2 \
-Djboss.default.multicast.address=234.56.78.101 -Dremote.cache.port=13232 -Djava.net.preferIPv4Stack=true \
-Djboss.socket.binding.port-offset=5000

It shouldn't be connected to the cluster with NODE11 and NODE12, but to separate one:

Received new cluster view for channel hibernate: [node21|0] (1) [node21]

8) Start NODE22 :

cd NODE22/bin
./standalone.sh -c standalone-ha.xml -Djboss.node.name=node22 -Djboss.site.name=site2 \
-Djboss.default.multicast.address=234.56.78.101 -Dremote.cache.port=13232 -Djava.net.preferIPv4Stack=true \
-Djboss.socket.binding.port-offset=6000

It should be in cluster with NODE21 :

Received new cluster view for channel server: [node21|1] (2) [node21, node22]

9) Test:

9.1) Go to http://localhost:11080/auth/ and create initial admin user

9.2) Go to http://localhost:11080/auth/admin and login as admin to admin console

9.3) Open 2nd browser and go to any of nodes http://localhost:12080/auth/admin or http://localhost:13080/auth/admin or http://localhost:14080/auth/admin . After login, you should be able to see the same sessions in tab Sessions of particular user, client or realm on all 4 servers

9.4) After doing any change (eg. update some user), the update should be immediatelly visible on any of 4 nodes as caches should be properly invalidated everywhere.

9.5) Check server.logs if needed. After login or logout, the message like this should be on all the nodes NODEXY/standalone/log/server.log :

2017-08-25 17:35:17,737 DEBUG [org.keycloak.models.sessions.infinispan.remotestore.RemoteCacheSessionListener] 
(Client-Listener-sessions-30012a77422542f5) Received event from remote store. 
Event 'CLIENT_CACHE_ENTRY_REMOVED', key '193489e7-e2bc-4069-afe8-f1dfa73084ea', skip 'false'

Conclusion

This is just a starting point and the instructions are subject to change. We plan various improvements especially around performance. If you have any feedback regarding cross-dc scenario, please let us know on keycloak-user mailing list referred from Keycloak home page .

Keycloak 3.3.0.CR1 Released

We've just released Keycloak 3.3.0.CR1.

To download the release go to the Keycloak homepage.

Highlights

Upgraded to WildFly 11 CR1

We've upgraded the underlying container to WildFly 11 CR1.

Cross DC Support

We've done loads of work to support multiple data centers. It's not 100% completed yet, but we'd love it if folks could give it a go and let us know what works well and what doesn't. There will be a blog post soon on how to try this out.

More Social

We've added support for social login with BitBucket and Gitlab.com.

Loads more..

• Dutch translation - thanks to gedejong and Jacob van Lingen
• Pass login_hint to identity brokers - thanks to dmnboutin

The full list of resolved issues is available in JIRA.

Upgrading

Before you upgrade remember to backup your database and check the migration guide. Release candidates are not recommended in production and we do not support upgrading from release candidates.

Keycloak 3.2.1.Final released

Keycloak 3.2.1.Final has just been released.

This release doesn't contain any new features. However there are few fixed bugs related to Authorization services and new permissions for Admin REST API.

To download the release go to the Keycloak homepage .

The full list of resolved issues is available in JIRA .

Upgrading

Before you upgrade remember to backup your database and check the migration guide .

Keycloak 3.2.0.Final Released

Keycloak 3.2.0.Final has just been released.

To download the release go to the Keycloak homepage.

The full list of resolved issues is available in JIRA.

Upgrading

Before you upgrade remember to backup your database and check the migration guide.

Keycloak 3.2.0.CR1

We've just released Keycloak 3.2.0.CR1.

To download the release go to the Keycloak homepage.

Highlights

Fine grained admin permissions

This is something that we've wanted to add for a long time! Through our authorization services it's now possible to finely tune permissions for admins. This makes it possible to limit what clients, users, roles, etc. admins have access to. Documentation is missing for this at the moment, but will be added in time for 3.2.0.Final.

Docker Registry support

It's not possible to secure a Docker Registry with a standard OAuth or OpenID Connect provider. For some strange reason they have only partially followed the specifications and the Docker Registry maintainers refuse to fix this! Fear not, thanks to cainj13 who contributed this we now have a special Docker Registry protocol that can be enabled in Keycloak.

Authentication sessions and access tokens

In the effort to provide support for running Keycloak in multiple data centers we've done a large amount of work around user sessions. We've introduced authentication sessions that are special sessions used primarily during the authentication flows. There are two main reasons for this. Authentication flows can fairly easily be fixed to a specific node within a specific data center and there is no need to replicate this to other data centers. They are also more write heavy than the user sessions. The introduction of access tokens makes it possible to detach actions (for example verify email) from a user session, which has a number of benefits. More will come in future 3.x releases and by the end of the year we aim to fully support replicating Keycloak cross multiple data centers.

Authorization Service improvements

There's been a lot of work done to the authorization services in this release. Way to many to list here so check out JIRA for details.

QuickStarts

We've introduced new QuickStarts with the aim to make it even simpler for you to get started securing your applications and services with Keycloak. The QuickStarts have proper tests as well, which can serve as a reference on how to tests your own applications and services secured with Keycloak. Check out the new QuickStarts in the keycloak-quickstarts GitHub repository.

Upgraded AngularJS and JQuery

We've upgraded the versions we use of AngularJS and JQuery as there where a number of known vulnerabilities. We're fairly certain neither of the known vulnerabilities affect Keycloak, but to be on the safe side we decided to upgrade.

Updated Password Hashing Algorithms

We're still using PBKDF2, but we've added support for SHA256 and SHA512. PBKDF2 with SHA256 is now used by default.

Spring Boot QuickStarter

We've added a new Spring Boot QuickStarter that makes it super simple to get started securing your Spring Boot applications. For more details check out the blog post about it.

Loads more..

• Partial export of realms in the admin console
• Redirect URI rewrite rules for adapters
• Test email settings in the admin console
• Initial access tokens now persisted to the db

The full list of resolved issues is available in JIRA.

Upgrading

Before you upgrade remember to backup your database and check the migration guide. Release candidates are not recommended in production and we do not support upgrading from release candidates.

Easily secure your Spring Boot applications with Keycloak

What is Keycloak?

Although security is a crucial aspect of any application, its implementation can be difficult. Worse, it is often neglected, poorly implemented and intrusive in the code. But lately, security servers have appeared which allow for outsourcing and delegating all the authentication and authorization aspects. Of these servers, one of the most promising is Keycloak, open-source, flexible, and agnostic of any technology, it is easily deployable/adaptable in its own infrastructure. Moreover, Keycloak is more than just an authentication server, it also provides a complete Identity Management system, user federation for third parties like LDAP and a lot more ... Check it out on here. The project can also be found on Github

Criticial vulnerability fixed in Keycloak Node.js adapters

A criticial vulnerability was discovered in Keycloak Node.js adapters. We highly recommend everyone upgrades to version 3.1.0 of the adapter immediately. This adapter will work with Keycloak 2 and upwards.

For more details see CVE-2017-7474.

Keycloak 3.1.0.Final Released

Keycloak 3.1.0.Final has just been released.

To download the release go to the Keycloak homepage.

The full list of resolved issues is available in JIRA.

Upgrading

Before you upgrade remember to backup your database and check the migration guide.

Keycloak 3.1.0.CR1 Released

Keycloak 3.1.0.CR1 has just been released.

To download the release go to the Keycloak homepage.

Highlights

• X509 Certificate user authentication - Thanks to Peter Nalyvayko for the contribution
• Proof Key for Code Exchange by OAuth Public Clients - Thanks to Takashi Norimatsu for the contribution
• WildFly Elytron adapters - Adapters for Elytron, a new security subsystem coming in WildFly 11 and EAP 7.1
• TypeScript type definitions for keycloak.js - Simplifies using keycloak.js from TypeScript
• Identity Provider for Openshift - Thanks to Bartosz Majsak for the contribution

The full list of resolved issues is available in JIRA.

Upgrading

Before you upgrade remember to backup your database and check the migration guide. Release candidates are not recommended in production and we do not support upgrading from release candidates.

How to Setup MS AD FS 3.0 as Brokered Identity Provider in Keycloak

This document guides you through initial setup of Microsoft Active Directory Federation Services 3.0 as a brokered identity provider Keycloak.

Prerequisites

• Two server hosts:
• Microsoft Windows Server 2012 with Active Directory Federation Services (AD FS) installed. The AD domain will be named DOMAIN.NAME in this post.
• Keycloak server. This can be generally placed anywhere but here it is expected to be running on separate host
• DNS setup:
• The Windows host name will be fs.domain.name in this post
• The Keycloak host name will be kc.domain.name in this post

Setup Keycloak Server

Keycloak server has configured for SSL/TLS transport - this is mandatory for AD FS to communicate with it. This comprises two steps:

• Setup keycloak for incoming HTTPS connections - steps are provided in Server Installation guide.
• Export AD FS certificate into a Java truststore to enable outgoing HTTPS connections:
• In the AD FS management console, go to Service → Certificates node in the tree and export the Service communications certificate.
• Import the certificate into a Java truststore (JKS format) using Java keytool utility.
• Setup the truststore in Keycloak as described in Server Installation guide.

Setup Identity Provider in Keycloak

Setup Basic Properties of Brokered Identity Provider

In the Identity Providers, create a new SAML v2.0 identity provider. In this post, the identity provider will be known under alias adfs-idp-alias.

Now scroll to the bottom and enter the AD FS descriptor URL into Import from URL field. For AD FS 3.0, this URL is https://fs.domain.name/FederationMetadata/2007-06/FederationMetadata.xml. Once you click “Import”, check the settings. Usually, you would at least enable Validate signature option.

If the authentication requests sent to the AD FS instance are expected to be signed, which is also usually the case, you have to enable Want AuthnRequests Signed option. Importantly, then the SAML Signature Key Name field that shows after enabling the Want AuthnRequests Signed option has to be set to CERT_SUBJECT as AD FS expects the signing key name hint to be the subject of the signing certificate.

The AD FS will be set up in the next step to respond with name ID in Windows Domain Qualified Name format, hence set the NameID Policy Format field accordingly.

Setup Mappers

In the steps setting AD FS below, AD FS will be set up to send email and group information in SAML assertion. To transform these details from SAML document issued by AD FS to Keycloak user store, we’ll need to set up two corresponding mappers in the Mappers tab of Identity Provider:

• Mapper named Group: managers will be of type SAML Attribute to Role, and will map attribute named http://schemas.xmlsoap.org/claims/Group, if that has attribute value managers, to role manager.

• Mapper named Attribute: email will be of type Attribute Importer, and will map attribute named http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress into user attribute named email.

Obtain information for the AD FS configuration

Now we determine SAML service provider descriptor URI that will be used in AD FS setup from the Redirect URI field in the identity provider detail by adding “/descriptor” to the URI in this field. The URI will be similar to https://kc.domain.name:8443/auth/realms/master/broker/adfs-idp-alias/endpoint/descriptor. You can check whether you got the URI right by entering the URI into the browser - you should receive a SAML service provider XML descriptor.

Setup Relying Party Trust in AD FS

Setup Relying Party

In AD FS Management console, right-click Trust relationships → Relying Party Trusts and select Add Relying Party Trust from the menu:

At the beginning of the wizard, enter the SAML descriptor URL obtained in the previous step into the Federation metadata address field, and let AD FS import the settings. Proceed with the wizard, and adjust the settings where appropriate. Here we use only the default settings. Note that you will need to edit the claim rules so when asked to do so at the last page of the wizard, you can leave the checkbox checked on.

Setup Claim Mapping

Now the SAML protocol would proceed correctly, AD FS would be able to correctly authenticate the users according to requests from Keycloak, but the requested name ID format is not yet recognized and SAML response would not contain any additional information like e-mail. It is hence necessary to map claims from AD user details into SAML document.

We will set up three rules: one for mapping user ID, second for mapping standard user attributes, and third for a user group. All start by clicking the Add Rule button in the Edit Claim Rules for kc.domain.name window:

The first rule will map user ID in Windows Qualified Domain name to the SAML response. In the Add Transform Claim Rule window, select Transform an incoming claim rule type:

The example above targets windows account name ID format. Other name ID formats are supported but out of scope of this post. See e.g. this blog on how to setup name IDs for persistent and transient formats.

The second rule will map user e-mail to the SAML response. In the Add Transform Claim Rule window, select Send LDAP attributes as Claims rule type. You can add other attributes as needed:

The third rule would send a group name if the user is member of a named group. Start again in the Add Transform Claim Rule window, and select Send Group Membership as a Claim rule type. Then enter the requested values in the field:

This setup would send an attribute named Group in the SAML assertion with value managers if the authenticated user is member of the DOMAIN\Managers group.

Troubleshooting

As a first-hand tool, you should check SAML messages sent back and forth between Keycloak and AD FS in your browser. The SAML decoders are available as browser extensions (e.g. SAML Tracer for Firefox, SAML Chrome Panel for Chrome). From the captured communication, you might see error status codes as well as the actual attribute names and values in SAML assertion necessary for setting up mappers. For example, if name ID format is not recognized, AD FS would return a SAML response containing urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy status code.

As a second resort, check the logs. For AD FS, the logs are available in the Event viewer under Applications and Services Logs → AD FS → Admin. In Keycloak, you can enable tracing of the SAML processing by connecting to the running Keycloak instance via jboss-cli.sh and entering the following commands:

/subsystem=logging/logger=org.keycloak.saml:add(level=DEBUG)

/subsystem=logging/logger=org.keycloak.broker.saml:add(level=DEBUG)

Then you will be able to find the SAML messages and broker-related SAML processing messages in the Keycloak server log.

Common issues

Q: I cannot log out! When I click logout in my app, it seems I’m logged out from Keycloak but when I return to the app, AD FS login form never displays and I’m redirected back authenticated as the same user as previously!

A: Don’t panic. This is not a Keycloak issue, rather AD FS settings of authentication policy. Try disabling Windows Authentication before reporting an issue.

Q: While using AD FS in Windows 2016, the following error appeared in Keycloak log after importing the descriptor from URL: RESTEASY002010: Failed to execute: javax.ws.rs.NotFoundException: RESTEASY003210: Could not find resource for full path: https://kc.domain.name/auth/realms/master/broker/adfs-idp-alias/endpoint/descriptor/FederationMetadata/2007-06/FederationMetadata.xml. Does it cause any harm?
A: It is harmless. It seems that Windows 2016 version first checks for AD FS-like descriptor URL by adding FederationMetadata/2007-06/FederationMetadata.xml to the entered URL. Such resource does not exist in Keycloak, so it reports error. AD FS however seems to import using the entered URL when this happens. Please see also the original email discussion on this issue. 

Conclusion

If you get stuck, do not hesitate to write a question to keycloak-user mailing list.

As there is always room for improvement, if you find any issue or have any suggestion on this text, feel free to leave a comment!

Keycloak 3.0.0.Final released

Keycloak 3.0.0.Final is released.

To download the release go to the Keycloak homepage.

The full list of resolved issues is available in JIRA.

Upgrading

Before you upgrade remember to backup your database and check the migration guide.

Keycloak 3.0.0.CR1 released

Keycloak 3.0.0.CR1 is released. Even though we've been busy wrapping up Keycloak 2.5 we've managed to include quite a few new features.

To download the release go to the Keycloak homepage.

This release is the first that comes without Mongo support.

Highlights

• No import option for LDAP - This option allows consuming users from LDAP without importing into the Keycloak database
• Initiate linking of identity provider from application - In the past adding additional identity brokering accounts could only be done through the account management console. Now this can be done from your application
• Hide identity provider - It's now possible to hide an identity provider from the login page
• Jetty 9.4 - Thanks to reneploetz we now have support for Jetty 9.4
• Swedish translations - Thanks to Viktor Kostov for adding Swedish translations
• Checksums for downloads - The website now has md5 checksums for all downloads
• BOMs - We've added BOMs for adapters as well as Server SPIs

The full list of resolved issues is available in JIRA.

Upgrading

Before you upgrade remember to backup your database and check the migration guide.

Keycloak 2.5.5.Final Released

Keycloak 2.5.5.Final is out. There's nothing much except a handful bug fixes, but it's still worth upgrading.

To download the release go to the Keycloak homepage.

Highlights

• A few bug fixes

The full list of resolved issues is available in JIRA.

Upgrading

Before you upgrade remember to backup your database and check the migration guide.

Keycloak 2.5.4.Final Released

Keycloak 2.5.4.Final is out. There's nothing much except a handful bug fixes, but it's still worth upgrading.

To download the release go to the Keycloak homepage.

Highlights

• A few bug fixes

The full list of resolved issues is available in JIRA.

Upgrading

Before you upgrade remember to backup your database and check the migration guide.

Removing Mongo support from Keycloak

At times you have to make hard decisions and this has been one of those. We have decided to remove Mongo support from Keycloak. The primary motivation behind this decision is that we simply don't have the resources to maintain and further develop the back-end for both relational databases and Mongo. Further, there are some fundamental issues with our current use of Mongo that would require a large amount of work to become fully production ready. This primarily boils down to the lack of ACID transactions in Mongo.

We hope that this decision won't result in too much trouble for those of you that are currently using Mongo as the back-end for Keycloak. It should be relatively painless to migrate to a relational database with our export/import feature. If you do run into issues with this please let us know on the mailing list and we will do whatever we can to help make the transition as smooth as possible.

If anyone from the community would like to take over the Mongo support and maintain it as a separate extension please let us know. We can help with extracting the code and work together in making it easy to install it as an extension.

Migrating from Mongo to relational database

First step is to export the full database. You can do this by stopping the Keycloak server and running:

bin/standalone.sh -Dkeycloak.migration.action=export -Dkeycloak.migration.provider=dir -Dkeycloak.migration.dir=backup

This will export all data from Mongo to JSON files within the directory backup. For full details refer to the Server Administration Guide.

Next step is to install a relational database and configure it in Keycloak. Take your pick we support quite a few. For full details refer to the Server Installation Guide.

Once you have the relational database ready and configured, you can start Keycloak and import the data exported from Mongo. To do this run Keycloak with:

bin/standalone.sh -Dkeycloak.migration.action=import -Dkeycloak.migration.provider=dir -Dkeycloak.migration.dir=backup

Hopefully you're now up and running with all your realms and users migrated to the relational database. If not, let us know on the user mailing list and we'll help you out as soon as possible.