The Keycloak admin client is a Java library that facilitates the access and usage of the Keycloak Admin REST API. It is available for either Jackson 2 or Jackson 3, both sharing the same API.
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 admin client with Jackson 2 requires Java 11 or higher.
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>999.0.0-SNAPSHOT</version>
</dependency>The Keycloak admin client aims to work with multiple versions of the Keycloak server. For the details about supported Keycloak server versions, see Upgrading the Keycloak Client Libraries.
Due the fact that multiple Keycloak server versions might be supported with the Keycloak admin client, 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.
The admin client with Jackson 3 requires Java 17 or higher.
It is a drop-in replacement for applications that already use Jackson 3.
To use it from your application replace the keycloak-admin-client dependency with keycloak-admin-client-jackson3:
<dependency>
<groupId>org.keycloak</groupId>
<artifactId>keycloak-admin-client-jackson3</artifactId>
<version>999.0.0-SNAPSHOT</version>
</dependency>The same compatibility considerations apply here.
With Jackson 3, the equivalent tools.jackson.databind.json.JsonMapper configuration is:
JsonMapper mapper = JsonMapper.builder()
.changeDefaultPropertyInclusion(v -> JsonInclude.Value.construct(
JsonInclude.Include.NON_NULL, JsonInclude.Include.NON_NULL))
.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
.build();If you are injecting a custom Jackson provider as described in the Jackson 2 section, extend org.keycloak.admin.client.jackson3.JacksonProvider3 instead of org.keycloak.admin.client.JacksonProvider.