[keycloak-dev] Change in enabling / disabling features

Marko Strukelj mstrukel at redhat.com
Mon Aug 28 09:57:20 EDT 2017

This is a heads up about an upcoming change in how to enable or disable
features in Keycloak.

Keycloak has a notion of features, which makes it possible to disable
certain functionality that is enabled by default, or enable certain
functionality that is disabled by default.

There are four sets of functionality you can enable or disable as features:
impersonation, script,  authorization, and docker. See [1] for more info.

Currently a file called profile.properties can be used to enable / disable
features, or system properties can be used, which override any
configuration inside profile.properties as explained in [1].

This is an aberration from how other configuration is specified on the
server via standalone.xml.

Also, the reason config file is called profile.properties, and not
features.properties is because the set of enabled/disabled features is
different for upstream project (where all but 'docker' are enabled), for
product based on Keycloak - RHSSO (where only 'impersonation' is enabled),
and for technology preview versions of RHSSO.

This additionally complicates things. The idea is to simplify that and
remove the notion of profiles, stop using profile.properties, and move all
configuration to standalone.xml where all the available features will be
listed with default values:

<subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">


    <feature name="authorization" enabled="true" />
    <feature name="impersonation" enabled="true" />
    <feature name="scripts" enabled="true" />
    <feature name="docker" enabled="false" />



This is how configuration would look like in Keycloak distribution. In
product distributions different features would be enabled / disabled - no
more named profiles.

However, in order to allow system properties override the idea is to do it
slightly differently:

    <feature name="authorization"
enabled="${keycloak.feature.authorization:true}" />
    <feature name="impersonation"
enabled="${keycloak.feature.impersonation:true}" />
    <feature name="scripts" enabled="${keycloak.feature.scripts:true}" />
    <feature name="docker" enabled="${keycloak.feature.docker:false}" />

We should probably also facilitate transition for current deployments, and
take old style system properties into account if they are used - converting
them to the new ones before configuration is applied.

Deprecated: -Dkeycloak.profile.feature.impersonation=enabled
New style:    -Dkeycloak.feature.impersonation=true

We don't want to keep support for this indefinitely (maybe for one minor
version?) so if use of deprecated system properties is detected a warning
will be logged.

Also, Stian proposed that features not considered stable yet, should carry
a suffix '-preview' in the name. So the actual feature name, and system
property name may still change for some features.

You can follow progress on JIRA issue [2].


[2] https://issues.jboss.org/browse/KEYCLOAK-4994

More information about the keycloak-dev mailing list