Keycloak admin client

Using the Keycloak admin client to access the Keycloak Admin REST API

The Keycloak admin client is a Java library that facilitates the access and usage of the Keycloak Admin REST API. The library requires Java 11 or higher at runtime (RESTEasy dependency enforces this requirement). To use it from your application add a dependency on the keycloak-admin-client library. For example using Maven:

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-admin-client</artifactId>
    <version>26.0.6</version>
</dependency>

The following example shows how to use the Java client library to get the details of the master realm:

import org.keycloak.admin.client.Keycloak;
import org.keycloak.representations.idm.RealmRepresentation;
...

Keycloak keycloak = Keycloak.getInstance(
    "http://localhost:8080",
    "master",
    "admin",
    "password",
    "admin-cli");
RealmRepresentation realm = keycloak.realm("master").toRepresentation();

Complete Javadoc for the admin client is available at API Documentation.

Compatibility with Keycloak server

The Keycloak admin client aims to work with multiple versions of the Keycloak server. The admin client may be supported with a newer version of the Keycloak server that is released later than the client and older versions of the Keycloak server that were released earlier. As a result of this change, the Java fields of the underlying "representation" classes, which are representing JSON properties of the request/response body (such as the RealmRepresentation class shown in the previous section) might not be exactly same for the client and the server.

To avoid compatibility issues, ensure that the com.fasterxml.jackson.databind.ObjectMapper class, which is used by the admin client under the covers, is initialized with these two properties:

objectMapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);
objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

If you are using the basic ways of admin client creation as described above, then these properties are added by default as admin client uses by default the org.keycloak.admin.client.JacksonProvider class for creating ObjectMapper, which adds these properties automatically. However if you are injecting your own customJacksonProvider when creating Keycloak object, make sure that object mapper is initialized with the properties above if you want to avoid compatibility issues.

For example, consider the situation that the admin client is instantiated in a way as described below with your own MyCustomJacksonProvider class:

Keycloak.getInstance(
                "http://localhost:8080",
                "master",
                "admin",
                "admin",
                "admin-cli",
                null,
                null,
                new MyCustomJacksonProvider()
        );

In this case, please make sure that your class MyCustomJacksonProvider extends from the class org.keycloak.admin.client.JacksonProvider or make sure to configure the ObjectMapper manually in a way described above. The similar care should be taken when using KeycloakBuilder to create the admin client and the RestEasy client is manually injected and created.

On this page

Edit this guide