Using Keycloak Admin Client
The Quarkus Keycloak Admin Client and its reactive twin support Keycloak Admin Client which can be used to configure a running Keycloak server.
This guide demonstrates how you can leverage the Quarkus ArC and inject the admin client to your Quarkus application, as well as how to create it directly in the application code.
To learn more about the Keycloak Admin Client, please refer to its reference guide.
Prerequisites
To complete this guide, you need:
-
Roughly 15 minutes
-
An IDE
-
JDK 11+ installed with
JAVA_HOME
configured appropriately -
Apache Maven 3.8.8
-
A working container runtime (Docker or Podman)
-
Optionally the Quarkus CLI if you want to use it
-
Optionally Mandrel or GraalVM installed and configured appropriately if you want to build a native executable (or Docker if you use a native container build)
Creating the Project
First, we need a new project. Create a new project with the following command:
This command generates a project which imports the keycloak-admin-client-reactive
and resteasy-reactive-jackson
extensions.
If you already have your Quarkus project configured, you can add the keycloak-admin-client-reactive
and resteasy-reactive-jackson
extensions
to your project by running the following command in your project base directory:
quarkus extension add 'keycloak-admin-client-reactive,resteasy-reactive-jackson'
./mvnw quarkus:add-extension -Dextensions='keycloak-admin-client-reactive,resteasy-reactive-jackson'
./gradlew addExtension --extensions='keycloak-admin-client-reactive,resteasy-reactive-jackson'
This will add the following to your build file:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-keycloak-admin-client-reactive</artifactId>
</dependency>
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-resteasy-reactive-jackson</artifactId>
</dependency>
implementation("io.quarkus:quarkus-keycloak-admin-client-reactive")
implementation("io.quarkus:quarkus-resteasy-reactive-jackson")
We also are going to need a simple resource with a Keycloak
injected as request scoped CDI bean.
package org.acme.keycloak.admin.client;
import org.keycloak.admin.client.Keycloak;
import org.keycloak.representations.idm.RoleRepresentation;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import java.util.List;
@Path("/api/admin")
public class RolesResource {
@Inject
Keycloak keycloak; (1)
@GET
@Path("/roles")
public List<RoleRepresentation> getRoles() {
return keycloak.realm("quarkus").roles().list();
}
}
1 | Create a default Keycloak Admin Client which can perform Keycloak master realm administration tasks as an admin-cli client, such as adding new realms, clients and users. |
The only configuration which is required to create this Keycloak Admin Client is a Keycloak server URL.
For example:
# Quarkus based Keycloak distribution
quarkus.keycloak.admin-client.server-url=http://localhost:8081
or
# WildFly based Keycloak distribution
quarkus.keycloak.admin-client.server-url=http://localhost:8081/auth
It is important that |
Injecting Keycloak Admin Client instead of creating it directly in the application code is a simpler and more flexible option but you can create the same admin client manually if necessary:
package org.acme.keycloak.admin.client;
import org.keycloak.admin.client.Keycloak;
import org.keycloak.admin.client.KeycloakBuilder;
import org.keycloak.representations.idm.RoleRepresentation;
import jakarta.annotations.PostConstruct;
import jakarta.annotations.PreConstruct;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import java.util.List;
@Path("/api/admin")
public class RolesResource {
Keycloak keycloak;
@PostConstruct
public void initKeycloak() {
keycloak = KeycloakBuilder.builder()
.serverUrl("http://localhost:8081")
.realm("master")
.clientId("admin-cli")
.grantType("password")
.username("admin")
.password("admin")
.build();
}
@PreDestroy
public void closeKeycloak() {
keycloak.close();
}
@GET
@Path("/roles")
public List<RoleRepresentation> getRoles() {
return keycloak.realm("quarkus").roles().list();
}
}
For more details consult Keycloak Admin REST API documentation.
You can configure Keycloak Admin Client to administer other realms and clients. It can use either a password
or client_credentials
grant to acquire an access token to call the Admin REST API which requires authorization.
If you exchange user’s credentials for the access token, here is an example configuration for the password
grant type:
quarkus.keycloak.admin-client.server-url=http://localhost:8081
quarkus.keycloak.admin-client.realm=quarkus
quarkus.keycloak.admin-client.client-id=quarkus-client
quarkus.keycloak.admin-client.username=alice
quarkus.keycloak.admin-client.password=alice
quarkus.keycloak.admin-client.grant-type=PASSWORD (1)
1 | Use password grant type. |
An example using the client-credentials
grant type needs only a minor adjustments:
quarkus.keycloak.admin-client=true
quarkus.keycloak.admin-client.server-url=http://localhost:8081
quarkus.keycloak.admin-client.realm=quarkus
quarkus.keycloak.admin-client.client-id=quarkus-client
quarkus.keycloak.admin-client.client-secret=secret
quarkus.keycloak.admin-client.username= # remove default username
quarkus.keycloak.admin-client.password= # remove default password
quarkus.keycloak.admin-client.grant-type=CLIENT_CREDENTIALS (1)
1 | Use client_credentials grant type. |
Note that the OidcClient can also be used to acquire tokens. |
Quarkus Keycloak Admin Client Configuration Reference
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Type |
Default |
|
---|---|---|
Set to true if Keycloak Admin Client injection is supported. Environment variable: |
boolean |
|
Keycloak server URL, for example, Environment variable: |
string |
|
Realm. Environment variable: |
string |
|
Client id. Environment variable: |
string |
|
Client secret. Required with a Environment variable: |
string |
|
Username. Required with a Environment variable: |
string |
|
Password. Required with a Environment variable: |
string |
|
OAuth 2.0 Access Token Scope. Environment variable: |
string |
|
OAuth Grant Type. Environment variable: |
|
|