Using Keycloak Admin Client

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

Prerequisites

Unresolved directive in security-keycloak-admin-client.adoc - include::{includes}/prerequisites.adoc[]* Keycloak

Creating the Project

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

Unresolved directive in security-keycloak-admin-client.adoc - include::{includes}/devtools/create-app.adoc[]

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

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

Unresolved directive in security-keycloak-admin-client.adoc - include::{includes}/devtools/extension-add.adoc[]

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

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` 端口
<1>  将 Keycloak 管理客户端配置为使用同一个端口

Quarkus Keycloak Admin Client Configuration Reference

Unresolved directive in security-keycloak-admin-client.adoc - include::{generated-dir}/config/quarkus-keycloak-admin-client.adoc[]

References