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.
先决条件
完成这个指南，你需要:
-
大概15分钟
-
编辑器
-
JDK 17+ installed with
JAVA_HOMEconfigured appropriately -
Apache Maven 3.9.9
-
A working container runtime (Docker or Podman)
-
如果你愿意的话，还可以选择使用Quarkus CLI
-
如果你想构建原生可执行程序，可以选择安装Mandrel或者GraalVM，并正确配置(或者使用Docker在容器中进行构建)
创建项目
首先，我们需要一个新的工程项目。用以下命令创建一个新项目：
For Windows users:
-
If using cmd, (don’t use backward slash
\and put everything on the same line) -
If using Powershell, wrap
-Dparameters in double quotes e.g."-DprojectArtifactId=security-keycloak-admin-client"
This command generates a project which imports the keycloak-admin-rest-client and rest-jackson extensions.
If you already have your Quarkus project configured, you can add the keycloak-admin-rest-client and rest-jackson extensions
to your project by running the following command in your project base directory:
quarkus extension add keycloak-admin-rest-client,rest-jackson./mvnw quarkus:add-extension -Dextensions='keycloak-admin-rest-client,rest-jackson'./gradlew addExtension --extensions='keycloak-admin-rest-client,rest-jackson'这将在您的构建文件中添加以下内容：
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-keycloak-admin-rest-client</artifactId>
</dependency>
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-rest-jackson</artifactId>
</dependency>implementation("io.quarkus:quarkus-keycloak-admin-rest-client")
implementation("io.quarkus:quarkus-rest-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.
例如：
# Quarkus based Keycloak distribution
quarkus.keycloak.admin-client.server-url=http://localhost:8081or
# 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.annotation.PostConstruct;
import jakarta.annotation.PreDestroy;
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.enabled=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. |
Configuring TLS
To configure a TLS connection for the Keycloak Admin Client, use the TLS Registry extension and point the Keycloak Admin Client to respective TLS configuration. For example, you can configure mutual TLS (mTLS) like this:
quarkus.keycloak.admin-client.tls-configuration-name=kc-mtls
quarkus.tls.kc-mtls.key-store.p12.path=client-keystore.p12
quarkus.tls.kc-mtls.key-store.p12.password=secret
quarkus.tls.kc-mtls.trust-store.p12.path=client-truststore.p12
quarkus.tls.kc-mtls.trust-store.p12.password=secret测试
The preferred approach for testing Keycloak Admin Client against Keycloak is Dev Services for Keycloak.
Dev Services for Keycloak will start and initialize a test container.
Then, it will create a quarkus realm and a quarkus-app client (secret secret) and add alice (admin and user roles) and bob (user role) users, where all of these properties can be customized.
For example, by default, a test container will be available at a randomly allocated port but you can make both Keycloak Admin Client and the container use the same port as follows:
%test.quarkus.keycloak.devservices.port=${kc.admin.port.test:45180} (1)
%test.quarkus.keycloak.admin-client.server-url=http://localhost:${kc.admin.port.test:45180}/ (2)| 1 | Configure the Keycloak container to listen on the 45180 port by default |
| 2 | Configure the Keycloak Admin Client to use the same port |
Quarkus Keycloak Admin Client Configuration Reference
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Configuration property |
类型 |
默认 |
|---|---|---|
Set to true if Keycloak Admin Client injection is supported. Environment variable: Show more |
boolean |
|
Keycloak server URL, for example, Environment variable: Show more |
string |
|
Realm. Environment variable: Show more |
string |
|
Client id. Environment variable: Show more |
string |
|
Client secret. Required with a Environment variable: Show more |
string |
|
Username. Required with a Environment variable: Show more |
string |
|
Password. Required with a Environment variable: Show more |
string |
|
OAuth 2.0 Access Token Scope. Environment variable: Show more |
string |
|
OAuth Grant Type. Environment variable: Show more |
|
|
The name of the TLS configuration to use. If a name is configured, it uses the configuration from The default TLS configuration is not used by default. Environment variable: Show more |
string |
