Using Keycloak Admin Client

Quarkus Keycloak 管理客户端及其响应式双胞胎支持 Keycloak 管理客户端，该客户端可用于配置正在运行的 Keycloak 服务器。 本指南演示了如何利用 Quarkus ArC 将管理客户端注入 Quarkus 应用程序，以及如何在应用程序代码中直接创建管理客户端。 要了解有关 Keycloak 管理客户端的更多信息，请参阅其 reference guide 。

Prerequisites

如要完成本指南，您需要：

  • Roughly 15 minutes

  • An IDE

  • 安装了 JDK 17+，已正确配置 JAVA_HOME

  • Apache Maven ${proposed-maven-version}

  • 如果你想使用 Quarkus CLI, 则可以选择使用

  • 如果你想构建一个本机可执行文件（或如果你使用本机容器构建，则使用 Docker），则可以选择安装 Mandrel 或 GraalVM 以及 configured appropriately

Creating the Project

首先，我们需要一个新项目。使用以下命令创建一个新项目：

CLI
quarkus create app {create-app-group-id}:{create-app-artifact-id} \
    --no-code
cd {create-app-artifact-id}

要创建一个 Gradle 项目，添加 --gradle 或 --gradle-kotlin-dsl 选项。 有关如何安装和使用 Quarkus CLI 的详细信息，请参见 Quarkus CLI 指南。

Maven
mvn {quarkus-platform-groupid}:quarkus-maven-plugin:{quarkus-version}:create \
    -DprojectGroupId={create-app-group-id} \
    -DprojectArtifactId={create-app-artifact-id} \
    -DnoCode
cd {create-app-artifact-id}

要创建一个 Gradle 项目，添加 -DbuildTool=gradle 或 -DbuildTool=gradle-kotlin-dsl 选项。

适用于 Windows 用户：

  • 如果使用 cmd，（不要使用反斜杠 \ ，并将所有内容放在同一行上）

  • 如果使用 Powershell，将 -D 参数用双引号引起来，例如 "-DprojectArtifactId={create-app-artifact-id}"

此命令生成了一个项目，它导入了 keycloak-admin-rest-client 和 rest-jackson 扩展。

如果您已经配置了您的 Quarkus 项目，则可以通过在项目基本目录中运行以下命令向您的项目添加 keycloak-admin-rest-client 和 rest-jackson 扩展：

CLI
quarkus extension add {add-extension-extensions}
Maven
./mvnw quarkus:add-extension -Dextensions='{add-extension-extensions}'
Gradle
./gradlew addExtension --extensions='{add-extension-extensions}'

这会将以下内容添加到构建文件中：

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-keycloak-admin-rest-client</artifactId>
</dependency>
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-rest-jackson</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-keycloak-admin-rest-client")
implementation("io.quarkus:quarkus-rest-jackson")

我们还需要一个带有 Keycloak 的简单资源，将其注入为请求作用域 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 创建一个默认 Keycloak 管理客户端，该客户端可以执行 Keycloak master 领域管理任务（如以 admin-cli 客户端身份添加新领域、客户端和用户）。

创建此 Keycloak 管理客户端所需的唯一配置是 Keycloak 服务器 URL。

例如：

# Quarkus based Keycloak distribution
quarkus.keycloak.admin-client.server-url=http://localhost:8081

或

# WildFly based Keycloak distribution
quarkus.keycloak.admin-client.server-url=http://localhost:8081/auth

如果要注入 Keycloak ，则配置 quarkus.keycloak.admin-client.server-url 非常重要。如果您尝试在未配置此属性的情况下注入 Keycloak ，则注入失败。

注入 Keycloak 管理客户端（而不是在应用程序代码中直接创建它）是一个更简单、更灵活的选择，但您可以在必要时手动创建相同的管理客户端：

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();
        }

}

有关详细信息，请参阅 Keycloak Admin REST API documentation 。

您可以配置 Keycloak 管理客户端以管理其他领域和客户端。它可以使用 password 或 client_credentials 授权来获取访问令牌，以调用需要授权的管理 REST API。

如果您交换用户的凭证以获取访问令牌，则以下是 password 授权类型的示例配置：

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.

使用 client-credentials 授权类型的示例只需要进行轻微调整：

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.

请注意， OidcClient 也可用于获取令牌。

Testing

针对 Keycloak 测试 Keycloak 管理客户端的首选方法是 Dev Services for Keycloak.Dev Services for Keycloak 将启动并初始化一个测试容器。然后，它将创建一个 quarkus 领域和一个 quarkus-app 客户端（ secret 秘钥）并添加 alice （ admin 和 user 角色）以及 bob （user 角色）用户，其中所有这些属性都可以进行定制。

例如，默认情况下，一个测试容器将可用于一个随机分配的端口，但您可以使 Keycloak 管理客户端和容器使用相同的端口，如下所示：

%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 将 Keycloak 容器配置为默认侦听 45180 端口
2 将 Keycloak 管理客户端配置为使用同一个端口

Quarkus Keycloak Admin Client Configuration Reference

Unresolved include directive in modules/ROOT/pages/security-keycloak-admin-client.adoc - include::../../../target/quarkus-generated-doc/config/quarkus-keycloak-admin-client.adoc[]

References