<dependency>
<groupId>org.keycloak</groupId>
<artifactId>keycloak-admin-client</artifactId>
<version>26.0.6</version>
</dependency>
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.
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.