返回指南
编辑此页面

使用 Keycloak Admin Client

Quarkus Keycloak Admin Client 及其响应式版本支持 Keycloak Admin Client，可用于配置正在运行的 Keycloak 服务器。

本指南演示了如何利用 Quarkus ArC 将 admin client 注入到您的 Quarkus 应用程序中，以及如何在应用程序代码中直接创建它。

要了解更多关于 Keycloak Admin Client 的信息，请参阅其 参考指南。

先决条件

要完成本指南，您需要

  • 大约 15 分钟

  • 一个 IDE

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

  • Apache Maven 3.9.9

  • 一个正常工作的容器运行时（Docker 或 Podman）

  • 如果您想使用它，可以选择 Quarkus CLI

  • 如果您想构建本机可执行文件（或者如果您使用本机容器构建，则为 Docker），可以选择安装 Mandrel 或 GraalVM 并进行适当的配置

  • Keycloak

创建项目

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

CLI
quarkus create app org.acme:security-keycloak-admin-client \
    --extension='keycloak-admin-rest-client,rest-jackson' \
    --no-code
cd security-keycloak-admin-client

要创建 Gradle 项目，请添加 --gradle 或 --gradle-kotlin-dsl 选项。

有关如何安装和使用 Quarkus CLI 的更多信息，请参阅 Quarkus CLI 指南。

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:3.24.4:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=security-keycloak-admin-client \
    -Dextensions='keycloak-admin-rest-client,rest-jackson' \
    -DnoCode
cd security-keycloak-admin-client

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

对于 Windows 用户

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

  • 如果使用 Powershell，请将 -D 参数括在双引号中，例如 "-DprojectArtifactId=security-keycloak-admin-client"

此命令将生成一个导入 keycloak-admin-rest-client 和 rest-jackson 扩展的 Quarkus 项目。

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

CLI
quarkus extension add keycloak-admin-rest-client,rest-jackson
Maven
./mvnw quarkus:add-extension -Dextensions='keycloak-admin-rest-client,rest-jackson'
Gradle
./gradlew addExtension --extensions='keycloak-admin-rest-client,rest-jackson'

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

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 Admin Client，它可以作为 admin-cli 客户端执行 Keycloak master realm 的管理任务，例如添加新的 realm、client 和 user。

创建此 Keycloak Admin Client 所需的唯一配置是 Keycloak 服务器 URL。

例如

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

或

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

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

将 Keycloak Admin Client 注入而不是直接在应用程序代码中创建它是一个更简单、更灵活的选择，但如有必要，您也可以手动创建相同的 admin client。

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("https://: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 文档。

您可以配置 Keycloak Admin Client 来管理其他 realm 和 client。它可以利用 password 或 client_credentials 授权类型来获取访问令牌，以调用需要授权的 Admin REST API。

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

quarkus.keycloak.admin-client.server-url=https://: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 使用 password 授权类型。

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

quarkus.keycloak.admin-client.enabled=true
quarkus.keycloak.admin-client.server-url=https://: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 使用 client_credentials 授权类型。
请注意，OidcClient 也可用于获取令牌。

配置 TLS

要为 Keycloak Admin Client 配置 TLS 连接，请使用 TLS Registry 扩展并将 Keycloak Admin Client 指向相应的 TLS 配置。例如，您可以这样配置双向 TLS (mTLS)：

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

测试

在 Keycloak Admin Client 的测试中，使用 Dev Services for Keycloak 是首选方法。Dev Services for Keycloak 将启动并初始化一个测试容器。然后，它将创建一个 quarkus realm 和一个 quarkus-app client（secret 密钥），并添加 alice（admin 和 user 角色）和 bob（user 角色）用户，所有这些属性都可以自定义。

例如，默认情况下，测试容器将在一个随机分配的端口上可用，但您可以像下面这样让 Keycloak Admin Client 和容器使用相同的端口：

%test.quarkus.keycloak.devservices.port=${kc.admin.port.test:45180} (1)
%test.quarkus.keycloak.admin-client.server-url=https://:${kc.admin.port.test:45180}/ (2)
1 默认配置 Keycloak 容器监听 45180 端口
2 配置 Keycloak Admin Client 使用相同的端口

Quarkus Keycloak Admin Client 配置参考

构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖

配置属性

类型

默认

quarkus.keycloak.admin-client.enabled

如果支持 Keycloak Admin Client 注入，则设置为 true。

环境变量：QUARKUS_KEYCLOAK_ADMIN_CLIENT_ENABLED

显示更多

布尔值

true

quarkus.keycloak.admin-client.server-url

Keycloak 服务器 URL，例如 https://host:port。当 Keycloak Dev Services 启动且未配置此属性时，Quarkus 会将 'quarkus.keycloak.admin-client.server-url' 配置属性指向已启动的 Keycloak 容器。在其他情况下，如果未设置此属性，则 Keycloak Admin Client 注入将失败 - 请改用 org.keycloak.admin.client.KeycloakBuilder 创建 client。

环境变量：QUARKUS_KEYCLOAK_ADMIN_CLIENT_SERVER_URL

显示更多

字符串

quarkus.keycloak.admin-client.realm

Realm。

环境变量：QUARKUS_KEYCLOAK_ADMIN_CLIENT_REALM

显示更多

字符串

master

quarkus.keycloak.admin-client.client-id

Client id。

环境变量：QUARKUS_KEYCLOAK_ADMIN_CLIENT_CLIENT_ID

显示更多

字符串

admin-cli

quarkus.keycloak.admin-client.client-secret

Client secret。使用 client_credentials 授权类型时需要。

环境变量：QUARKUS_KEYCLOAK_ADMIN_CLIENT_CLIENT_SECRET

显示更多

字符串

quarkus.keycloak.admin-client.username

Username。使用 password 授权类型时需要。

环境变量：QUARKUS_KEYCLOAK_ADMIN_CLIENT_USERNAME

显示更多

字符串

admin

quarkus.keycloak.admin-client.password

Password。使用 password 授权类型时需要。

环境变量：QUARKUS_KEYCLOAK_ADMIN_CLIENT_PASSWORD

显示更多

字符串

admin

quarkus.keycloak.admin-client.scope

OAuth 2.0 访问令牌范围。

环境变量：QUARKUS_KEYCLOAK_ADMIN_CLIENT_SCOPE

显示更多

字符串

quarkus.keycloak.admin-client.grant-type

OAuth Grant Type。

环境变量：QUARKUS_KEYCLOAK_ADMIN_CLIENT_GRANT_TYPE

显示更多

password, client-credentials

密码

quarkus.keycloak.admin-client.tls-configuration-name

要使用的 TLS 配置的名称。

如果配置了名称，它将使用来自 quarkus.tls.<name>.* 的配置。如果配置了名称，但找不到具有该名称的 TLS 配置，则将引发错误。

默认情况下，不使用默认 TLS 配置。

环境变量：QUARKUS_KEYCLOAK_ADMIN_CLIENT_TLS_CONFIGURATION_NAME

显示更多

字符串

参考

相关内容

关于相同主题

Quarkus 是开放的。本项目的所有依赖项均在 Apache Software License 2.0 或兼容许可证下提供。 CC by 3.0

本网站使用 Jekyll 构建，托管在 GitHub Pages 上，并且是完全开源的。如果您想使其更好，请 fork 本网站 并展示您的成果。

导航
关注我们
获取帮助
语言
Quarkus 由社区项目组成
版权所有 © Quarkus。保留所有权利。有关我们的商标详情，请访问我们的 商标政策 和 商标列表。第三方商标属于其各自的持有人，此处提及并不意味着任何认可或关联。