Keycloak Reference Guide

The core concept in Keycloak is a Realm. A realm secures and manages security metadata for a set of users and registered clients. Users can be created within a specific realm within the Administration console. Roles (permission types) can be defined at the realm level and you can also set up user role mappings to assign these permissions to specific users.

A client is a service that is secured by a realm. You will often use Client for every Application secured by Keycloak. When a user browses an application's web site, the application can redirect the user agent to the Keycloak Server and request a login. Once a user is logged in, they can visit any other client (application) managed by the realm and not have to re-enter credentials. This also hold true for logging out. Roles can also be defined at the client level and assigned to specific users. Depending on the client type, you may also be able to view and manage user sessions from the administration console.

In admin console there is switch Consent required specified when creating/editing client. When on, the client is not immediately granted all permissions of the user. In addition to requesting the login credentials of the user, the Keycloak Server will also display a grant page asking the user if it is ok to grant allowed permissions to the client. The granted consents are saved and every user can see his granted consents in Account Management UI and he can also revoke them for particular client. Also admin can see and revoke the grants of particular user in Keycloak Admin Console UI.

Keycloak Server has three downloadable distributions.

Although the Keycloak Server is designed to run out of the box, there's some things you'll need to configure before you go into production. Specifically:

In domain mode, you start the server with the "domain" command instead of the "standalone" command. In this case, the Keycloak subsystem is defined in domain/configuration/domain.xml instead of standalone/configuration.standalone.xml. Inside domain.xml, you will see more than one profile. A Keycloak subsystem can be defined in zero or more of those profiles.

To enable Keycloak for a server profile edit domain/configuration/domain.xml. To the extensions element add the Keycloak extension:

<extensions>
    ...
    <extension module="org.keycloak.keycloak-subsystem"/>
</extensions>

Then you need to add the server to the required server profiles. By default WildFly starts two servers in the main-server-group which uses the full profile. To add Keycloak for this profile add the Keycloak subsystem to the profile element with name full:

<profile name="full">
    ...
    <subsystem xmlns="urn:jboss:domain:keycloak:1.0">
        <auth-server name="main-auth-server">
            <enabled>true</enabled>
            <web-context>auth</web-context>
        </auth-server>
    </subsystem>

To configure the server copy standalone/configuration/keycloak-server.json to domain/servers/<SERVER NAME>/configuration. The configuration should be identical for all servers in a group.

The Keycloak server can be installed as the default web application. This way, instead of referencing the server as http://mydomain.com/auth, it would be http://mydomain.com/.

To do this, you need to add a default-web-module attribute in the Undertow subystem in standalone.xml.

<subsystem xmlns="urn:jboss:domain:undertow:1.2">
            <server name="default-server">
                <host name="default-host" alias="localhost" default-web-module="main-auth-server.war">
                    <location name="/" handler="welcome-content"/>
                </host>

main-auth-server is the name of the Keycloak server as defined in the Keycloak subsystem.

To implement an SPI you need to implement it's ProviderFactory and Provider interfaces. You also need to create a provider-configuration file. For example to implement the Event Listener SPI you need to implement EventListenerProviderFactory and EventListenerProvider and also provide the file META-INF/services/org.keycloak.events.EventListenerProviderFactory

For example to implement the Event Listener SPI you start by implementing EventListenerProviderFactory:

{
package org.acme.provider;

import ...

public class MyEventListenerProviderFactory implements EventListenerProviderFactory {

    private List<Event> events;

    public String getId() {
        return "my-event-listener";
    }

    public void init(Config.Scope config) {
        int max = config.getInt("max");
        events = new MaxList(max);
    }

    public EventListenerProvider create(KeycloakSession session) {
        return new MyEventListenerProvider(events);
    }

    public void close() {
        events = null;
    }

}
}

The example uses an imagined MaxList which has a maximum size and is concurrency safe. When the maximum size is reached and new entries are added the oldest entry is removed. Keycloak creates a single instance of EventListenerProviderFactory which makes it possible to store state for multiple requests. EventListenerProvider instances are created by calling create on the factory for each requests so these should be light-weight.

Next you would implement EventListenerProvider:

{
package org.acme.provider;

import ...

public class MyEventListenerProvider implements EventListenerProvider {

    private List<Event> events;

    public MyEventListenerProvider(List<Event> events) {
        this.events = events;
    }

    @Override
    public void onEvent(Event event) {
        events.add(event);
    }

    @Override
    public void close() {

    }

}
}

The file META-INF/services/org.keycloak.events.EventListenerProviderFactory should contain the full name of your ProviderFactory implementation:

org.acme.provider.MyEventListenerProviderFactory

Keycloak can load provider implementations from JBoss Modules or directly from the file-system. Using Modules is recommended as you can control exactly what classes are available to your provider. Any providers loaded from the file-system uses a classloader with the Keycloak classloader as its parent.

Here's a list of the available SPIs and a brief description. For more details on each SPI refer to individual sections.

Run the following command from a terminal:

rhc app create <APPLICATION NAME> http://cartreflect-claytondev.rhcloud.com/github/keycloak/openshift-keycloak-cartridge

Replace <APPLICATION NAME> with the name you want (for example keycloak).

Once the instance is created the rhc tool outputs details about it. Open the returned URL in a browser to open the Keycloak servers homepage.

The Keycloak servers homepage shows the Keycloak logo and Welcome to Keycloak. There is also a link to the Administration Console. Open that and log in using username admin and password admin. On the first login you are required to change the password.

There are two realm roles in the master realm. These are:

To add these roles to a user select the master realm, then click on Users. Find the user you want to grant permissions to, open the user and click on Role Mappings. Under Realm Roles assign any of the above roles to the user by selecting it and clicking on the right-arrow.

Each realm in Keycloak is represented by an application in the master realm. The name of the application is <realm name>-realm. This allows assigning access to users for individual realms. The roles available are:

Manage roles includes permissions to view (for example a user with manage-realm role can also view the realm configuration).

To add these roles to a user select the master realm, then click on Users. Find the user you want to grant permissions to, open the user and click on Role Mappings. Under Application Roles select the application that represents the realm you're adding permissions to (<realm name>-realm), then assign any of the above roles to the user by selecting it and clicking on the right-arrow.

Each realm has a built-in application called realm-management. This application defines roles that define permissions that can be granted to manage the realm.

These are more fine-grain roles you can assign to the user.

Manage roles includes permissions to view (for example a user with manage-realm role can also view the realm configuration).

To add these roles to a user select the realm you want. Then click on Users. Find the user you want to grant permissions to, open the user and click on Role Mappings. Under Application Roles select realm-management, then assign any of the above roles to the user by selecting it and clicking on the right-arrow.

Each adapter supported by Keycloak can be configured by a simple JSON text file. This is what one might look like:

{
  "realm" : "demo",
  "resource" : "customer-portal",
  "realm-public-key" : "MIGfMA0GCSqGSIb3D...31LwIDAQAB",
  "auth-server-url" : "https://localhost:8443/auth",
  "ssl-required" : "external",
  "use-resource-role-mappings" : false,
  "enable-cors" : true,
  "cors-max-age" : 1000,
  "cors-allowed-methods" : "POST, PUT, DELETE, GET",
  "bearer-only" : false,
  "enable-basic-auth" : false,
  "expose-token" : true,
   "credentials" : {
      "secret" : "234234-234234-234234"
   },

   "connection-pool-size" : 20,
   "disable-trust-manager": false,
   "allow-any-hostname" : false,
   "truststore" : "path/to/truststore.jks",
   "truststore-password" : "geheim",
   "client-keystore" : "path/to/client-keystore.jks",
   "client-keystore-password" : "geheim",
   "client-key-password" : "geheim"
}

Some of these configuration switches may be adapter specific and some are common across all adapters. For Java adapters you can use ${...} enclosure as System property replacement. For example ${jboss.server.config.dir}. Also, you can obtain a template for this config file from the admin console. Go to the realm and select the application you want a template for. Go to the Installation tab and this will provide you with a template that includes the public key of the realm.

Here is a description of each item:

To be able to secure WAR apps deployed on JBoss AS 7.1.1, JBoss EAP 6.x, or Wildfly, you must install and configure the Keycloak Subsystem. You then have two options to secure your WARs. You can provide a keycloak config file in your WAR and change the auth-method to KEYCLOAK within web.xml. Alternatively, you don't have to crack open your WARs at all and can apply Keycloak via the Keycloak Subsystem configuration in standalone.xml. Both methods are described in this section.

To be able to secure WAR apps deployed on Tomcat 6, 7 and 8 you must install the Keycloak Tomcat 6, 7 or 8 adapter into your Tomcat installation. You then have to provide some extra configuration in each WAR you deploy to Tomcat. Let's go over these steps.

Keycloak has a separate adapter for Jetty 9.1.x and Jetty 9.2.x that you will have to install into your Jetty installation. You then have to provide some extra configuration in each WAR you deploy to Jetty. Let's go over these steps.

Keycloak has a separate adapter for Jetty 8.1.x that you will have to install into your Jetty installation. You then have to provide some extra configuration in each WAR you deploy to Jetty. Let's go over these steps.

The Keycloak Server comes with a Javascript library you can use to secure HTML/Javascript applications. This library is referencable directly from the keycloak server. You can also download the adapter from Keycloak's download site if you want a static copy of this library. It works in the same way as other application adapters except that your browser is driving the OAuth redirect protocol rather than the server.

The disadvantage of using this approach is that you have a non-confidential, public client. This makes it more important that you register valid redirect URLs and make sure your domain name is secured.

To use this adapter, you must first configure an application (or client) through the Keycloak Admin Console. You should select public for the Client Type field. As public clients can't be verified with a client secret you are required to configure one or more valid redirect uris as well. Once you've configured the application click on the Installation tab and download the keycloak.json file. This file should be hosted in your web-server at the same root as your HTML pages. Alternatively you can either specify the URL for this file, or manually configure the adapter.

Next you have to initialize the adapter in your application. An example on how to do this is shown below.

<head>
    <script src="http://<keycloak server>/auth/js/keycloak.js"></script>
    <script>
        var keycloak = Keycloak();
        keycloak.init().success(function(authenticated) {
            alert(authenticated ? 'authenticated' : 'not authenticated');
        }).error(function() {
            alert('failed to initialize');
        });
    </script>
</head>

To specify the location of the keycloak.json file:

var keycloak = Keycloak('http://localhost:8080/myapp/keycloak.json'));

Or finally to manually configure the adapter:

var keycloak = Keycloak({
    url: 'http://keycloak-server/auth',
    realm: 'myrealm',
    clientId: 'myapp'
});

You can also pass login-required or check-sso to the init function. Login required will redirect to the login form on the server, while check-sso will redirect to the auth server to check if the user is already logged in to the realm. For example:

keycloak.init({ onLoad: 'login-required' })

After you login, your application will be able to make REST calls using bearer token authentication. Here's an example pulled from the customer-portal-js example that comes with the distribution.

<script>
    var loadData = function () {
        document.getElementById('username').innerText = keycloak.username;

        var url = 'http://localhost:8080/database/customers';

        var req = new XMLHttpRequest();
        req.open('GET', url, true);
        req.setRequestHeader('Accept', 'application/json');
        req.setRequestHeader('Authorization', 'Bearer ' + keycloak.token);

        req.onreadystatechange = function () {
            if (req.readyState == 4) {
                if (req.status == 200) {
                    var users = JSON.parse(req.responseText);
                    var html = '';
                    for (var i = 0; i < users.length; i++) {
                        html += '<p>' + users[i] + '</p>';
                    }
                    document.getElementById('customers').innerHTML = html;
                    console.log('finished loading data');
                }
            }
        }

        req.send();
    };

    var loadFailure = function () {
        document.getElementById('customers').innerHTML = '<b>Failed to load data.  Check console log</b>';

    };

    var reloadData = function () {
        keycloak.updateToken().success(loadData).error(loadFailure);
    }
</script>

<button onclick="loadData()">Submit</button>

The loadData() method builds an HTTP request setting the Authorization header to a bearer token. The keycloak.token points to the access token the browser obtained when it logged you in. The loadFailure() method is invoked on a failure. The reloadData() function calls keycloak.onValidAccessToken() passing in the loadData() and loadFailure() callbacks. The keycloak.onValidAcessToken() method checks to see if the access token hasn't expired. If it hasn't, and your oauth login returned a refresh token, this method will refresh the access token. Finally, if successful, it will invoke the success callback, which in this case is the loadData() method.

To refresh the token if it's expired call the updateToken method. This method returns a promise object which can be used to invoke a function on success or failure. This method can be used to wrap functions that should only be called with a valid token. For example the following method will refresh the token if it expires within 30 seconds, and then invoke the specified function. If the token is valid for more than 30 seconds it will just call the specified function.

keycloak.updateToken(30).success(function() {
    // send request with valid token
}).error(function() {
    alert('failed to refresh token');
);

To be able to secure Spring Boot apps you must add the Keycloak Spring Boot adapter JAR to your app. You then have to provide some extra configuration via normal Spring Boot configuration (application.properties). Let's go over these steps.

To to secure an application with Spring Security and Keyloak, add this adapter as a dependency to your project. You then have to provide some extra beans in your Spring Security configuration file and add the Keycloak security filter to your pipeline.

Unlike the other Keycloak Adapters, you should not configure your security in web.xml. However, keycloak.json is still required.

Keycloak provides two special redirect uris for installed applications.

There are multiple ways you can logout from a web application. For Java EE servlet containers, you can call HttpServletRequest.logout(). For any other browser application, you can point the browser at the url http://auth-server/auth/realms/{realm-name}/tokens/logout?redirect_uri=encodedRedirectUri. This will log you out if you have an SSO session with your browser.

Multi Tenancy, in our context, means that one single target application (WAR) can be secured by a single (or clustered) Keycloak server, authenticating its users against different realms. In practice, this means that one application needs to use different keycloak.json files. For this case, there are two possible solutions:

This chapter of the reference guide focus on this second scenario.

Keycloak provides an extension point for applications that need to evaluate the realm on a request basis. During the authentication and authorization phase of the incoming request, Keycloak queries the application via this extension point and expects the application to return a complete representation of the realm. With this, Keycloak then proceeds the authentication and authorization process, accepting or refusing the request based on the incoming credentials and on the returned realm. For this scenario, an application needs to:

An implementation of this feature can be found in the examples.

It's generally not needed to use JAAS for most of the applications, especially if they are HTTP based, but directly choose one of our adapters. However some applications and systems may still rely on pure legacy JAAS solution. Keycloak provides couple of login modules to help with such use cases. Some login modules provided by Keycloak are:

When using Keycloak as an identity broker, users are not forced to provide their credentials in order to authenticate in a specific realm. Instead of that, they are presented with a list of identity providers from where they can pick one and authenticate. You can also configure a hard-coded default broker. In this case the user will not be given a choice, but instead be redirected directly the the parent broker. The following diagram demonstrates the steps involved when using Keycloak to broker an external identity provider:

There are some variations of this flow that we will talk about later. For instance, instead of present a list of identity providers, the service provider can automatically select a specific one to authenticate an user. Or you can tell Keycloak to force the user to provide additional information before federate his identity.

As you may notice, at the end of the authentication process Keycloak will always issue its own token to service providers, what means that service providers are completely decoupled from external identity providers. They don't need to know which protocol (eg.: SAML, OpenID Connect, oAuth, etc) was used or how the user's identity was validated. They only need to know about Keycloak !

The identity broker configuration is all based on identity providers. Identity providers are created for each realm and by default they are enabled for every single application. That means that users from a realm can use any of the registered identity providers when signing in to an application.

In order to create an identity provider, follow these steps:

Identity providers are organized in two main categories:

Although each type of identity provider has its own configuration options, all of them share some very common configuration. Regardless the identity provider you are creating, you'll see the following configuration options avaiable:

On the next sections, we'll see how to configure each type of identity provider individually.

Forcing users to register to your realm when they want to access applications is hard. So is trying to remember yet another username and password combination. Social identity providers makes it easy for users to register on your realm and quickly sign in using a social network. Keycloak provides built-in support for the most common social networks out there, such as Google, Facebook, Twitter and even Github.

Keycloak can broker identity providers based on the SAML v2.0 protocol.

In order to configure a SAML identity provider, follow these steps:

When configuring a SAML identity provider you are presented with different configuration options in order to properly communicate and integrate with the external identity provider. In this case, you must keep in mind that Keycloak will act as an Service Provider that issues authentication requests(AuthnRequest) to the external identity provider.

You can also import all this configuration data by providing a URL or XML file that points to the entity descriptor of the external SAML IDP you want to connect to.

Once you create a SAML provider, there is an EXPORT button that appears when viewing that provider. Clicking this button will export a SAML entity descriptor which you can use to

Keycloak can broker identity providers based on the OpenID Connect v1.0 protocol.

In order to configure a OIDC identity provider, follow these steps:

When configuring an OIDC identity provider you are presented with different configuration options in order to send authentication requests to the external identity provider. In this case, the brokered identity provider must support the Authorization Code Flow (as defined by the specification) in order to authenticate the user and authorize access for the scopes specified in the configuration.

You can also import all this configuration data by providing a URL or file that points to OpenID Provider Metadata (see OIDC Discovery specification)

Keycloak allows you to store tokens and responses from identity providers during the authentication process. For that, you can use the Store Token configuration option, as mentioned before.

It also allows you to retrieve these tokens and responses once the user is authenticated in order to use their information or use them to invoke external resources protected by these tokens. The latter case is usually related with social providers, where you usually need to use their tokens to invoke methods on their APIs.

To retrieve a token for a particular identity provider you need to send a request as follows:

GET /auth/realms/{realm}/broker/{provider_alias}/token HTTP/1.1

Host: localhost:8080

Authorization: Bearer {keycloak_access_token}

In this case, given that you are accessing an protected service in Keycloak, you need to send the access token issued by Keycloak during the user authentication.

By default, the Keycloak access token issued for the application can't be automatically used for retrieve thirdparty token. A user will have to have the broker.read-token role. The client will also have to have that role in its scope. In the broker configuration page you can automatically assign this role to newly imported users by turning on the Stored Tokens Readable switch.

Applications can automatically select an identity provider in order to authenticate an user. In this case, the user will not be presented to the login page but automatically redirected to the identity provider.

Keycloak supports a specific HTTP query parameter that you can use as a hint to tell the server which identity provider should be used to authenticate the user.

For that, you can append the kc_idp_hint as a query parameter to your application url, as follows:

GET /myapplication.com?kc_idp_hint=facebook HTTP/1.1

Host: localhost:8080

In this case, is expected that your realm has an identity provider with an alias facebook.

If you are using keycloak.js adapter, you can also achieve the same behavior:

var keycloak = new Keycloak('keycloak.json');


keycloak.createLoginUrl({

    idpHint: 'facebook'

});

You can import SAML assertion data, OpenID Connect ID Token claims, and Keycloak access token claims into new users that are imported from a brokered IDP. After you configure a broker, you'll see a Mappers button appear. Click on that and you'll get to the list of mappers that are assigned to this broker. There is a Create button on this page. Clicking on this create button allows you to create a broker mapper. Broker mappers can import SAML attributes or OIDC ID/Access token claims into user attributes. You can assign a role mapping to a user if a claim or external role exists. There's a bunch of options here so just mouse over the tool tips to see what each mapper can do for you.

Keycloak provides some useful examples about how to use it as an identity broker. Take a look at {KEYCLOAK_HOME}/examples/broker for more details.

Each example application has its own README file where you can find additional information about how to configure Keycloak and run it.

A theme can support several types to customize different aspects of Keycloak. The types currently available are:

All theme types, except welcome, is configured through Keycloak Admin Console. To change the theme used for a realm open the Keycloak Admin Console, select your realm from the drop-down box in the top left corner. Under Settings click on Theme.

To set the theme for the master Keycloak admin console set the admin console theme for the master realm. To set the theme for per realm admin access control set the admin console theme for the corresponding realm.

To change the welcome theme you need to edit standalone/configuration/keycloak-server.json and add welcomeTheme to the theme element, for example:

"theme": {
    ...
    "welcomeTheme": "custom-theme"
}

Keycloak comes bundled with default themes in standalone/configuration/themes. You should not edit the bundled themes directly. Instead create a new theme that extends a bundled theme.

A theme consists of:

Themes can be deployed to Keycloak by copying the theme directory to ../standalone/configuration/themes or it can be deployed as a module. For a single server or during development just copying the theme is fine, but in a cluster or domain it's recommended to deploy as a module.

To deploy a theme as a module you need to create an jar (it's basically just a zip with jar extension) with the theme resources and a file META/keycloak-themes.json that describes the themes contained in the archive. For example example-theme.jar with the contents:

The contents of META-INF/keycloak-themes.json in this case would be:

[
{
    "themes": [{
        "name" : "example-theme",
        "types": [ "login" ]
    }]
}

As you can see a single jar can contain multiple themes and each theme can support one or more types.

The deploy the jar as a module to Keycloak you can either manually create the module or use jboss-cli. It's simplest to use jboss-cli as it creates the required directories and module descriptor for you. To deploy the above jar jboss-cli run:

[
    KEYCLOAK_HOME/bin/jboss-cli.sh --command="module add --name=org.example.exampletheme --resources=example-theme.jar"

If you're on windows run

KEYCLOAK_HOME/bin/jboss-cli.bat

.

This command creates modules/org/example/exampletheme/main containing example-theme.jar and module.xml.

Once you've created the module you need to register it with Keycloak do this by editing ../standalone/configuration/keycloak-server.json and adding the module to theme/module/modules. For example:

[
"theme": {
    ...
    "module": {
        "modules": [ "org.example.exampletheme" ]
    }
}

If a theme is deployed to ../standalone/configuration/themes and as a module the first is used.

For full control of login forms and account management Keycloak provides a number of SPIs.

To enable Keycloak to send emails you need to provide Keycloak with your SMTP server settings. If you don't have a SMTP server you can use one of many hosted solutions (such as Sendgrid or smtp2go).

To configure your SMTP server, open the Keycloak Admin Console, select your realm from the drop-down box in the top left corner. Then click on Email in the menu at the top.

You are required to fill in the Host and Port for your SMTP server (the default port for SMTP is 25). You also have to specify the sender email address (From). The other options are optional.

The screenshot below shows a simple example where the SMTP server doesn't use SSL or TLS and doesn't require authentication.

Any realm or application level role can be turned into a Composite Role. A Composite Role is a role that has one or more additional roles associated with it. I guess another term for it could be Role Group. When a composite role is mapped to the user, the user gains the permission of that role, plus any other role the composite is associated with. This association is dynamic. So, if you add or remove an associated role from the composite, then all users that are mapped to the composite role will automatically have those permissions added or removed. Composites can also be used to define Client scopes.

Composite roles can be associated with any type of role Realm or Application. In the admin console simple flip the composite switch in the Role detail, and you will get a screen that will allow you to associate roles with the composite.

If you go to the admin console page of Settings->General, you should see a Remember Me on/off switch. Your realm sets a SSO cookie so that you only have to enter in your login credentials once. This Remember Me admin config option, when turned on, will show a "Remember Me" checkbox on the user's login page. If the user clicks this, the realm's SSO cookie will be persistent. This means that if the user closes their browser they will still be logged in the next time they start up their browser.

If you go to the Sesions and Tokens->Timeout Settings page of the Keycloak adminstration console there is a bunch of fine tuning you can do as far as login session timeouts go.

The SSO Session Idle Timeout is the idle time of a user session. If there is no activity in the user's session for this amount of time, the user session will be destroyed, and the user will become logged out. The idle time is refreshed with every action against the keycloak server for that session, i.e.: a user login, SSO, a refresh token grant, etc.

The SSO Session Max Lifespan setting is the maximum time a user session is allowed to be alive. This max lifespan countdown starts from when the user first logs in and is never refreshed. This works great with Remember Me in that it allow you to force a relogin after a set timeframe.

The Access Token Lifespan is how long an access token is valid for. An access token contains everything an application needs to authorize a client. It contains roles allowed as well as other user information. When an access token expires, your application will attempt to refresh it using a refresh token that it obtained in the initial login. The value of this configuration option should be however long you feel comfortable with the application not knowing if the user's permissions have changed. This value is usually in minutes.

The Client login timeout is how long an access code is valid for. An access code is obtained on the 1st leg of the OAuth 2.0 redirection protocol. This should be a short time limit. Usually seconds.

The Login user action lifespan is how long a user is allowed to attempt a login. When a user tries to login, they may have to change their password, set up TOTP, or perform some other action before they are redirected back to your application as an authentnicated user. This value is relatively short and is usually measured in minutes.

Login events:

Account events:

For all events there is a corresponding error event.

Keycloak comes with an Email Event Listener and a JBoss Logging Event Listener. The Email Event Listener sends an email to the users account when an event occurs. The JBoss Logging Event Listener writes to a log file when an events occurs.

The Email Event Listener only supports the following events at the moment:

You can exclude one or more events by editing standalone/configuration/keycloak-server.json and adding for example:

"eventListener": {
    "email": {
        "exclude-events": [ "UPDATE_TOTP", "REMOVE_TOTP" ]
    }
}

Event Store listen for events and is expected to persist the events to make it possible to query for them later. This is used by the admin console and account management to view events. Keycloak includes providers to persist events to JPA and Mongo.

You can specify events to include or exclude by editing standalone/configuration/keycloak-server.json, and adding for example:

"eventsStore": {
    "jpa": {
        "exclude-events": [ "LOGIN", "REFRESH_TOKEN", "CODE_TO_TOKEN" ]
    }
}

To enable persisting of events for a realm you first need to make sure you have a event store provider registered for Keycloak. By default the JPA event store provider is registered. Once you've done that open the admin console, select the realm you're configuring, select Events. Then click on Config. You can enable storing events for your realm by toggling Save Events to ON. You can also set an expiration on events. This will periodically delete events from the database that are older than the specified time.

To configure listeners for a realm on the same page as above add one or more event listeners to the Listeners select box. This will allow you to enable any registered event listeners with the realm.

Keycloak comes with a built-in LDAP/AD plugin. Currently it is set up only to import username, email, first and last name. It supports password validation via LDAP/AD protocols and different user metadata synchronization modes. To configure a federated LDAP store go to the admin console. Click on the Users menu option to get you to the user management page. Then click on the Federation submenu option. When you get to this page there is an "Add Provider" select box. You should see "ldap" within this list. Selecting "ldap" will bring you to the ldap configuration page.

LDAP Federation Provider will automatically take care of synchronization (import) of needed LDAP users into Keycloak database. For example once you first authenticate LDAP user john from Keycloak UI, LDAP Federation provider will first import this LDAP user into Keycloak database and then authenticate against LDAP password.

Federation Provider imports just requested users by default, so if you click to View all users in Keycloak admin console, you will see just those LDAP users, which were already authenticated/requested by Keycloak.

If you want to sync all LDAP users into Keycloak database, you may configure and enable Sync, which is in admin console on same page like the configuration of Federation provider itself. There are 2 types of sync:

In usual cases you may want to trigger full sync at the beginning, so you will import all LDAP users to Keycloak just once. Then you may setup periodic sync of changed users, so Keycloak will periodically ask LDAP server for newly created or updated users and backport them to Keycloak DB. Also you may want to trigger full sync again after some longer time or setup periodic full sync as well.

In admin console, you can trigger sync directly or you can enable periodic changed or full sync.

The keycloak examples directory contains an example of a simple User Federation Provider backed by a simple properties file. See examples/providers/federation-provider. Most of how to create a federation provider is explained directly within the example code, but some information is here too.

Writing a User Federation Provider starts by implementing the UserFederationProvider and UserFederationProviderFactory interfaces. Please see the Javadoc and example for complete details on how to do this. Some important methods of note: getUserByUsername() and getUserByEmail() require that you query your federated storage and if the user exists create and import the user into Keycloak storage. How much metadata you import is fully up to you. This import is done by invoking methods on the object returned KeycloakSession.userStorage() to add and import user information. The proxy() method will be called whenever Keycloak has found an imported UserModel. This allows the federation provider to proxy the UserModel which is useful if you want to support external storage updates on demand.

This is platform dependent. Exact steps depend on your OS and the Kerberos vendor you're going to use. Consult Windows Active Directory, MIT Kerberos and your OS documentation for how exactly to setup and configure Kerberos server.

At least you will need to:

For easier testing with Kerberos, we provided some example setups to test.

One scenario supported by Kerberos 5 is credential delegation. In this case when user receives forwardable TGT and authenticates to the web server, then web server might be able to reuse the ticket and forward it to another service secured by Kerberos (for example LDAP server or IMAP server).

If you have issues, we recommend to enable more logging by:

The realm and user caches can be disabled through configuration or through the management console. To manally disable the realm or user cache, you must edit the keycloak-server.json file in your distribution. Here's what the config looks like initially.

    "realmCache": {
        "provider": "${keycloak.realm.cache.provider:mem}"
    },

    "userCache": {
        "provider": "${keycloak.user.cache.provider:mem}",
        "mem": {
            "maxSize": 20000
        }
    },

You must then change it to:

    "realmCache": {
        "provider": "${keycloak.realm.cache.provider:none}"
    },

    "userCache": {
        "provider": "${keycloak.user.cache.provider:none}"
    },

You can also disable either of the caches at runtime through the Keycloak admin console Realm Settings page. This will not permanently disable the cache. If you reboot the server, the cache will be re-enabled unless you manualy disable the cache in the keycloak-server.json file.

To clear the realm or user cache, go to the Keycloak admin console Realm Settings->Cache Config page. Disable the cache you want. Save the settings. Then re-enable the cache. This will cause the cache to be cleared.

Cache configuration is done within keycloak-server.json. Changes to this file will not be seen by the server until you reboot. Currently you can only configure the max size of the user cache.

    "userCache": {
        "provider": "${keycloak.user.cache.provider:mem}",
        "mem": {
            "maxSize": 20000
        }
    },

If you do not use SSL/HTTPS for all communication between the Keycloak auth server and the clients it secures you will be very vulnerable to man in the middle attacks. OAuth 2.0/OpenID Connect uses access tokens for security. Without SSL/HTTPS, attackers can sniff your network and obtain an access token. Once they have an access token they can do any operation that the token has been given permission for.

Cross-site request forgery (CSRF) is a web-based attack whereby HTTP requests are transmitted from a user that the web site trusts or has authenticated (e.g., via HTTP redirects or HTML forms). Any site that uses cookie based authentication is vulnerable for these types of attacks. These attacks are mitigated by matching a state cookie against a posted form or query parameter.

OAuth 2.0 login specification requires that a state cookie be used and matched against a transmitted state parameter. Keycloak fully implements this part of the specification so all logins are protected.

The Keycloak adminstration console is a pure Javascript/HTML5 application that makes REST calls to the backend Keycloak admin API. These calls all require bearer token authentication and are made via Javascript Ajax calls. CSRF does not apply here. The admin REST API can also be configured to validate CORS origins as well.

The only part of Keycloak that really falls into CSRF is the user account management pages. To mitigate this Keycloak sets a state cookie and also embeds the value of this state cookie within hidden form fields or query parameters in action links. This query or form parameter is checked against the state cookie to verify that the call was made by the user.

With clickjacking, a malicious site loads the target site in a transparent iFrame overlaid on top of a set of dummy buttons that are carefully constructed to be placed directly under important buttons on the target site. When a user clicks a visible button, they are actually clicking a button (such as an "Authorize" button) on the hidden page. An attacker can steal a user's authentication credentials and access their resources.

It would be very hard for an attacker to compromise Keycloak access codes. Keycloak generates a cryptographically strong random value for its access codes so it would be very hard to guess an access token. An access code can only be turned into an access token once so it can't be replayed. In the admin console you can specify how long an access token is valid for. This value should be really short. Like a seconds. Just long enough for the client to make the request to turn the code into an token.

There's a few things you can do to mitigate access tokens and refresh tokens from being stolen. Most importantly is to enforce SSL/HTTPS communication between Keycloak and its clients and applications. Short lifespans (minutes) for access tokens allows Keycloak to check the validity of a refresh token. Making sure refresh tokens always stay private to the client and are never transmitted ever is very important as well.

If an access token or refresh token is compromised, the first thing you should do is go to the admin console and push a not-before revocation policy to all applications. This will enforce that any tokens issued prior to that date are now invalid. You can also disable specific applications, clients, and users if you feel that any one of those entities is completely compromised.

An attacker could use the end-user authorization endpoint and the redirect URI parameter to abuse the authorization server as an open redirector. An open redirector is an endpoint using a parameter to automatically redirect a user agent to the location specified by the parameter value without any validation. An attacker could utilize a user's trust in an authorization server to launch a phishing attack.

Keycloak requires that all registered applications and clients register at least one redirection uri pattern. Any time a client asks Keycloak to perform a redirect (on login or logout for example), Keycloak will check the redirect uri vs. the list of valid registered uri patterns. It is important that clients and applications register as specific a URI pattern as possible to mitigate open redirector attacks.

A brute force attack happens when an attacker is trying to guess a user's password. Keycloak has some limited brute force detection capabilities. If turned on, a user account will be temporarily disabled if a threshold of login failures is reached. The downside of this is that this makes Keycloak vulnerable to denial of service attacks. Eventually we will expand this functionality to take client IP address into account when deciding whether to block a user.

Keycloak does not store passwords in raw text. It stores a hash of them. Because of performance reasons, Keycloak only hashes passwords once. While a human could probably never crack a hashed password, it is very possible that a computer could. The security community suggests around 20,000 (yes thousand!) hashing iterations to be done to each password. This number grows every year due to increasing computing power (It was 1000 12 years ago). The problem with this is that password hashing is a huge performance hit as each login would require the entered password to be hashed that many times and compared to the stored hash. So, its up to the admin to configure the password hash iterations. This can be done in the admin console password policy configuration. Again, the default value is 1 as we thought it might be more important for Keycloak to scale out of the box. There's a lot of other measures admins can do to protect their password databases.

At this point in time, there is no knowledge of any SQL injection vulnerabilities in Keycloak

Using the Scope menu in the admin console for clients, you can control exactly which role mappings will be included within the token sent back to the client application. This allows you to limit the scope of permissions given to the client which is great if the client isn't very trusted and is known to not being very careful with its tokens.

Keycloak doesn't replicate realms and users, but instead relies on all nodes using the same database. This can be a relational database or Mongo. To make sure your database doesn't become a single point of failure you may also want to deploy your database to a cluster.

To reduce number of requests to the database Keycloak caches realm and user data. In cluster mode Keycloak uses an Infinispan invalidation cache to make sure all nodes re-load data from the database when it is changed. Using an invalidation cache instead of a replicated cache reduces the network traffic generated by the cluster, but more importantly prevents sensitive data from being sent.

To enable realm and user cache invalidation open keycloak-server.json and change the realmCache and userCache providers to infinispan:

"realmCache": {
    "provider": "infinispan"
},

"userCache": {
    "provider": "infinispan"
}

To start the server in HA mode, start it with:

# bin/standalone --server-config=standalone-ha.xml

Alternatively you can copy standalone/config/standalone-ha.xml to standalone/config/standalone.xml to make it the default server config.

By default there's nothing to prevent unauthorized nodes from joining the cluster and sending potentially malicious messages to the cluster. However, as there's no sensitive data sent there's not much that can be achieved. For realms and users all that can be done is to send invalidation messages to make nodes load data from the database more frequently. For user sessions it would be possible to modify existing user sessions, but creating new sessions would have no affect as they would not be linked to any access tokens. There's not too much that can be achieved by modifying user sessions. For example it would be possible to prevent sessions from expiring, by changing the creation time. However, it would for example have no effect adding additional permissions to the sessions as these are rechecked against the user and application when the token is created or refreshed.

In either case your cluster nodes should be in a private network, with a firewall protecting them from outside attacks. Ideally isolated from workstations and laptops. You can also enable encryption of cluster messages, this could for example be useful if you can't isolate cluster nodes from workstations and laptops on your private network. However, encryption will obviously come at a cost of reduced performance.

To enable encryption of cluster messages you first have to create a shared keystore (change the key and store passwords!):

# keytool -genseckey -alias keycloak -keypass <PASSWORD> -storepass <PASSWORD> \
 -keyalg Blowfish -keysize 56 -keystore defaultStore.keystore -storetype JCEKS

Copy this keystore to all nodes (for example to standalone/configuration). Then configure JGroups to encrypt all messages by adding the ENCRYPT protocol to the JGroups sub-system (this should be added after the pbcast.GMS protocol):

<subsystem xmlns="urn:jboss:domain:jgroups:2.0" default-stack="udp">
    <stack name="udp">
        ...
        <protocol type="pbcast.GMS"/>
        <protocol type="ENCRYPT">
            <property name="key_store_name">
                ${jboss.server.config.dir}/defaultStore.keystore
            </property>
            <property name="key_password">PASSWORD</property>
            <property name="store_password">PASSWORD</property>
            <property name="alias">keycloak</property>
        </protocol>
        ...
    </stack>
    <stack name="tcp">
        ...
        <protocol type="pbcast.GMS"/>
        <protocol type="ENCRYPT">
            <property name="key_store_name">
                ${jboss.server.config.dir}/defaultStore.keystore
            </property>
            <property name="key_password">PASSWORD</property>
            <property name="store_password">PASSWORD</property>
            <property name="alias">keycloak</property>
        </protocol>
        ...
    </stack>
    ...
</subsystem>

Note that when you run cluster, you should see message similar to this in the log of both cluster nodes:

INFO  [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (Incoming-10,shared=udp)
ISPN000094: Received new cluster view: [node1/keycloak|1] (2) [node1/keycloak, node2/keycloak]

If you see just one node mentioned, it's possible that your cluster hosts are not joined together.

Usually it's best practice to have your cluster nodes on private network without firewall for communication among them. Firewall could be enabled just on public access point to your network instead. If for some reason you still need to have firewall enabled on cluster nodes, you will need to open some ports. Default values are UDP port 55200 and multicast port 45688 with multicast address 230.0.0.4. Note that you may need more ports opened if you want to enable additional features like diagnostics for your JGroups stack. Keycloak delegates most of the clustering work to Infinispan/JGroups, so consult EAP or JGroups documentation for more info.

By default, the servlet web application secured by Keycloak uses HTTP session to store information about authenticated user account. This means that 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. This is useful especially if your application is:

To configure this, you can add this line to configuration of your adapter in WEB-INF/keycloak.json of your application:

"token-store": "cookie"

Default value of token-store is session, hence saving data in HTTP session.

One limitation of cookie store is, that whole info about account is passed in cookie KEYCLOAK_ADAPTER_STATE in each HTTP request. Hence it's not the best for network performance. Another small limitation is limited support for Single-Sign out. It works without issues if you init servlet logout (HttpServletRequest.logout) from this application itself as the adapter will delete the KEYCLOAK_ADAPTER_STATE cookie. But back-channel logout initialized from different application can't be propagated by Keycloak to this application with cookie store. Hence it's recommended to use very short value of access token timeout (1 minute for example).

In many deployment scenarios will be Keycloak and secured applications deployed on same cluster hosts. For this case Keycloak already provides option to use relative URI as value of option auth-server-url in WEB-INF/keycloak.json . In this case, the URI of Keycloak server is resolved from the URI of current request.

For example if your loadbalancer is on https://loadbalancer.com/myapp and auth-server-url is /auth, then relative URI of Keycloak is resolved to be https://loadbalancer.com/auth .

For cluster setup, it may be even better to use option auth-server-url-for-backend-request . This allows to configure that backend requests between Keycloak and your application will be sent directly to same cluster host without additional round-trip through loadbalancer. So for this, it's good to configure values in WEB-INF/keycloak.json like this:

"auth-server-url": "/auth",
"auth-server-url-for-backend-requests": "http://${jboss.host.name}:8080/auth"

This would mean that browser requests (like redirecting to Keycloak login screen) will be still resolved relatively to current request URI like https://loadbalancer.com/myapp, but backend (out-of-bound) requests between keycloak and your app are sent always to same cluster host with application .

Note that additionally to network optimization, you may not need "https" in this case as application and keycloak are communicating directly within same cluster host.

Admin URL for particular application can be configured in Keycloak admin console. It's used by Keycloak server to send backend requests to application for various tasks, like logout users or push revocation policies.

For example logout of user from Keycloak works like this:

Previous section describes how can Keycloak send logout request to proper application node. However in some cases admin may want to propagate admin tasks to all registered cluster nodes, not just one of them. For example push new notBefore for realm or application, 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:

Sending startup registrations and periodic re-registration is disabled by default, as it's main usecase is just cluster deployment. In WEB-INF/keycloak.json of your application, you can specify:

"register-node-at-startup": true,
"register-node-period": 600,

which means that registration is sent at startup (accurately when 1st request is served by the application node) and then it's resent each 10 minutes.

In Keycloak admin console you can specify the maximum node re-registration timeout (makes sense to have it bigger than register-node-period from adapter configuration for particular application). Also you can manually add and remove cluster nodes in admin console, which is useful if you don't want to rely on adapter's automatic registration or if you want to remove stale application nodes, which weren't unregistered (for example due to forced shutdown).

Download the keycloak proxy distribution from the Keycloak download pages and unzip it.

$ unzip keycloak-proxy-dist.zip

To run it you must have a proxy config file (which we'll discuss in a moment).

$ java -jar bin/launcher.jar [your-config.json]

If you do not specify a path to the proxy config file, the launcher will look in the current working directory for the file named proxy.json

Here's an example configuration file.

{
    "target-url": "http://localhost:8082",
    "send-access-token": true,
    "bind-address": "localhost",
    "http-port": "8080",
    "https-port": "8443",
    "keystore": "classpath:ssl.jks",
    "keystore-password": "password",
    "key-password": "password",
    "applications": [
        {
            "base-path": "/customer-portal",
            "error-page": "/error.html",
            "adapter-config": {
                "realm": "demo",
                "resource": "customer-portal",
                "realm-public-key": "MIGfMA0GCSqGSIb",
                "auth-server-url": "http://localhost:8081/auth",
                "ssl-required" : "external",
                "principal-attribute": "name",
                "credentials": {
                    "secret": "password"
                }
            }
            ,
            "constraints": [
                {
                    "pattern": "/users/*",
                    "roles-allowed": [
                        "user"
                    ]
                },
                {
                    "pattern": "/admins/*",
                    "roles-allowed": [
                        "admin"
                    ]
                },
                {
                    "pattern": "/users/permit",
                    "permit": true
                },
                {
                    "pattern": "/users/deny",
                    "deny": true
                }
            ]
        }
    ]
}

When forwarding requests to the proxied server, Keycloak Proxy will set some additional headers with values from the OIDC identity token it received for authentication.

To be able to enter custom attributes in the admin console, take the following steps

To be able to enter custom attributes in the registration page, take the following steps

To be able to manage custom attributes in the user account profile page, take the following steps

Keycloak provides automatic migration of the database. It's highly recommended that you backup your database prior to upgrading Keycloak.

To enable automatic upgrading of the database if you're using a relational database make sure databaseSchema is set to update for connectionsJpa:

"connectionsJpa": {
    "default": {
        ...
        "databaseSchema": "update"
    }
}

For MongoDB do the same, but for connectionsMongo:

"connectionsMongo": {
    "default": {
        ...
        "databaseSchema": "update"
    }
}

When you start the server with this setting your database will automatically be migrated if the database schema has changed in the new version.

You should copy standalone/configuration/keycloak-server.json from the old version to make sure any configuration changes you've done are added to the new installation. The version specific section below will list any changes done to this file that you have to do when upgrading from one version to another.

If you have implemented any SPI providers you need to copy them to the new server. The version specific section below will mention if any of the SPI's have changed. If they have you may have to update your code accordingly.

If you have created a custom theme you need to copy them to the new server. The version specific section below will mention if changes have been made to themes. If there is you may have to update your themes accordingly.

If you deploy applications directly to the Keycloak server you should copy them to the new server. For any applications including those not deployed directly to the Keycloak server you should upgrade the adapter. The version specific section below will mention if any changes are required to applications.