使用OpenID Connect与Keycloak集中管理Quarkus授权

通过Keycloak Authorization Services，可在Quarkus应用中启用Bearer令牌授权，安全访问受保护资源。

概览

Keycloak授权扩展quarkus-keycloak-authorization在OpenID Connect扩展quarkus-oidc的基础上提供高级授权能力。它使用策略执行器动态管理受保护资源的访问，根据Keycloak中定义的权限实施灵活、动态的基于资源的访问控制。

只有使用Keycloak且启用了Keycloak Authorization Services来处理授权决策时，才使用此扩展。若未使用Keycloak，或未启用其授权服务，则使用quarkus-oidc扩展。

工作方式

此扩展把授权职责集中到Keycloak，提高安全性并简化维护：先由quarkus-oidc验证Bearer令牌，再把已验证的令牌发送给Keycloak Authorization Services，由其根据资源名称、标识符或URI等属性动态评估权限。

将授权决策移出应用后，可以在不修改代码的情况下采用不同访问控制策略，并在安全要求演变时减少重新部署。

兼容性

此扩展仅兼容Quarkus OIDC服务应用，通过动态授权策略补充基于角色的访问控制等显式机制。

主要能力

• 集中管理：把授权决策交给Keycloak，使各应用采用一致的安全策略。
• 动态权限：按资源属性动态定义访问控制。
• 简化维护：访问策略变更时，减少更新和重新部署应用的需要。

准备配置

确保Keycloak实例启用了Authorization Services，且Quarkus应用包含quarkus-keycloak-authorization扩展。详细步骤见OIDC Bearer令牌身份验证指南。

更多资源

授权服务与策略执行器的详细信息见Keycloak官方文档。

前提条件

• 约15分钟。
• 一个IDE。
• 安装JDK 17或更高版本，并正确配置JAVA_HOME。
• Apache Maven 3.9.16。
• 可工作的容器运行时，如Docker或Podman。
• 可选：Quarkus CLI。
• 若要构建原生可执行文件，可选安装并正确配置Mandrel或GraalVM；也可以用Docker进行原生容器构建。
• jq与Keycloak。

架构

示例微服务有两个受保护端点：/api/users/me和/api/admin。

基于令牌的访问控制

访问端点需要有效Bearer令牌：签名正确、未过期、受众合适；微服务还必须信任签发令牌的Keycloak服务器。令牌标识其签发对象，即用户，也依照OAuth 2.0授权服务器标准，标识代表该用户操作的客户端应用。

端点与访问策略

/api/users/me向持有有效令牌且具有user角色的用户开放，返回从令牌提取的用户详情JSON。原文响应示例：

{
  "user": {
    "id": "1234",
    "username": "johndoe",
    "email": "johndoe@example.com"
  }
}

/api/admin仅向持有有效令牌且具有admin角色的用户开放。

授权解耦

示例通过基于角色的访问控制（RBAC）策略保护资源。Keycloak还支持基于属性及自定义策略等多种策略类型，实现细粒度控制。授权策略完全由Keycloak管理，应用可以专注于核心功能。

完整示例

可以按后续步骤逐步创建，也可以直接查看完成的示例。克隆git clone https://github.com/quarkusio/quarkus-quickstarts.git，或下载归档。完整代码位于security-keycloak-authorization-quickstart目录。

创建项目

使用以下命令创建项目。

CLI

quarkus create app org.acme:security-keycloak-authorization-quickstart \
    --extension='oidc,keycloak-authorization,rest-jackson' \
    --no-code
cd security-keycloak-authorization-quickstart

创建Gradle项目时，添加--gradle或--gradle-kotlin-dsl。CLI安装与使用见Quarkus CLI指南。

Maven

mvn io.quarkus.platform:quarkus-maven-plugin:3.40.1:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=security-keycloak-authorization-quickstart \
    -Dextensions='oidc,keycloak-authorization,rest-jackson' \
    -DnoCode
cd security-keycloak-authorization-quickstart

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

命令生成包含keycloak-authorization扩展的新项目。该扩展将Keycloak适配器集成到Quarkus应用，提供与Keycloak服务器交互和进行Bearer令牌授权的能力。

向现有项目添加扩展

在项目根目录运行以下相应命令，添加oidc和keycloak-authorization：

CLI

quarkus extension add oidc,keycloak-authorization

Maven

./mvnw quarkus:add-extension -Dextensions='oidc,keycloak-authorization'

Gradle

./gradlew addExtension --extensions='oidc,keycloak-authorization'

命令会向构建文件添加以下依赖。

pom.xml

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-oidc</artifactId>
</dependency>
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-keycloak-authorization</artifactId>
</dependency>

build.gradle

implementation("io.quarkus:quarkus-oidc")
implementation("io.quarkus:quarkus-keycloak-authorization")

实现/api/users/me端点

以下代码定义返回用户详情的Jakarta REST资源：

package org.acme.security.keycloak.authorization;

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

import org.jboss.resteasy.reactive.NoCache;

import io.quarkus.security.identity.SecurityIdentity;

@Path("/api/users")
public class UsersResource {

    @Inject
    SecurityIdentity identity;

    @GET
    @Path("/me")
    @NoCache
    public User me() {
        return new User(identity);
    }

    public static class User {

        private final String userName;

        User(SecurityIdentity identity) {
            this.userName = identity.getPrincipal().getName();
        }

        public String getUserName() {
            return userName;
        }
    }
}

实现/api/admin端点

接着定义一个要求身份验证的简单Jakarta REST资源：

package org.acme.security.keycloak.authorization;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

import io.quarkus.security.Authenticated;

@Path("/api/admin")
@Authenticated
public class AdminResource {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String admin() {
        return "granted";
    }
}

通过Keycloak进行基于角色的访问控制

代码没有用@RolesAllowed等显式注解实施资源访问控制。扩展会动态映射Keycloak中的受保护资源URI。Keycloak按已配置策略评估每次请求的权限，扩展据此允许或拒绝访问。访问控制逻辑与应用代码解耦后，可以直接在Keycloak中管理和更新访问策略。

配置应用

通过通常位于src/main/resources的application.properties配置OpenID Connect适配器：

# OIDC Configuration
%prod.quarkus.oidc.auth-server-url=https://localhost:8543/realms/quarkus
quarkus.oidc.client-id=backend-service
quarkus.oidc.credentials.secret=secret

# Enable Policy Enforcement
quarkus.keycloak.policy-enforcer.enabled=true

# Import the realm file with Dev Services for Keycloak
# Note: This property is effective only in dev mode, not in JVM or native modes
quarkus.keycloak.devservices.realm-path=quarkus-realm.json

1. auth-server-url指定Keycloak服务器与身份验证realm的URL。
2. client-id标识realm中的客户端应用。
3. credentials.secret定义向Keycloak验证客户端身份所用的密钥。
4. policy-enforcer.enabled启用策略执行器，按所定义权限管理访问控制。
5. realm-path让Dev Services导入指定realm文件，仅在开发模式生效，不用于JVM或原生模式。

启动并配置Keycloak服务器

其他模式可用以下Docker命令启动：

docker run --name keycloak \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  -p 8543:8443 \
  -v "$(pwd)"/config/keycloak-keystore.jks:/etc/keycloak-keystore.jks \
  quay.io/keycloak/keycloak:26.7.4 \
  start --hostname-strict=false --https-key-store-file=/etc/keycloak-keystore.jks

密钥库使用示例config目录中的keycloak-keystore.jks。

访问服务器

在浏览器打开https://localhost:8543，用用户名admin和密码admin登录管理控制台。

导入realm配置

导入realm配置文件创建新realm，具体操作见创建realm文档。导入后打开Clients，选择backend-service客户端，再打开Authorization和Resources选项卡，查看资源权限：

Keycloak在资源权限中的作用

直接在Keycloak配置资源访问权限，应用无需@RolesAllowed注解。集中管理访问控制可以简化应用维护与安全更新。

以开发模式运行

使用相应命令：

CLI

quarkus dev

Maven

./mvnw quarkus:dev

Gradle

./gradlew --console=plain quarkusDev

Keycloak Dev Services会启动容器并导入quarkus-realm.json。打开/q/dev-ui中的Dev UI，点击OpenID Connect卡片中的Provider: Keycloak链接。

测试用户权限

在OpenID Connect Dev UI提供的单页应用中登录：

1. 使用alice／alice。该用户只有访问/api/users/me的User Permission；访问/api/admin返回403，访问/api/users/me返回200。
2. 退出后使用admin／admin。该用户同时具有Admin Permission和User Permission；访问两个端点均返回200。

自定义realm

若启动Dev Services时未导入上述realm文件，会使用不含Keycloak授权策略的默认quarkus realm。点击OpenID Connect卡片中的Keycloak Admin，用admin／admin登录，再按Keycloak Authorization Services文档启用realm中的授权策略。该入口如下：

添加自定义JavaScript策略

若应用使用打包为JAR的JavaScript授权策略，Dev Services可将归档传入Keycloak容器。在application.properties配置：

# Alias the policies archive
quarkus.keycloak.devservices.resource-aliases.policies=/policies.jar
# Map the policies archive to a specific location in the container
quarkus.keycloak.devservices.resource-mappings.policies=/opt/keycloak/providers/policies.jar

1. 为类路径资源/policies.jar建立policies别名。归档也可以位于文件系统。
2. 将其映射到容器的/opt/keycloak/providers/policies.jar。

以JVM模式运行

开发模式体验完成后，可以作为普通Java应用运行。先编译：

CLI

quarkus build

Maven

./mvnw install

Gradle

./gradlew build

再运行：

java -jar target/quarkus-app/quarkus-run.jar

以原生模式运行

无需修改即可将示例编译为原生代码。生成的二进制文件包含运行时并针对较低资源使用量优化，因此生产环境不再需要JVM。原生编译耗时更长，默认关闭；构建时启用native配置。

CLI

quarkus build --native

Maven

./mvnw install -Dnative

Gradle

./gradlew build -Dquarkus.native.enabled=true

构建完成后运行：

./target/security-keycloak-authorization-quickstart-1.0.0-SNAPSHOT-runner

测试应用

开发模式测试见前文。JVM或原生模式可以用curl测试。

获取访问令牌

应用使用Bearer令牌授权。先向Keycloak获取访问令牌：

export access_token=$(\
    curl --insecure -X POST https://localhost:8543/realms/quarkus/protocol/openid-connect/token \
    --user backend-service:secret \
    -H 'content-type: application/x-www-form-urlencoded' \
    -d 'username=alice&password=alice&grant_type=password' | jq --raw-output '.access_token' \
 )

以上请求获得alice的令牌。

访问/api/users/me

持有有效令牌的用户可访问以下端点，收到用户详情JSON：

curl -v -X GET \
  http://localhost:8080/api/users/me \
  -H "Authorization: Bearer "$access_token

访问/api/admin

该端点只允许admin角色。使用前面的alice令牌访问，会得到403 Forbidden：

curl -v -X GET \
  http://localhost:8080/api/admin \
  -H "Authorization: Bearer "$access_token

获取管理员令牌

要访问管理端点，获取admin用户的令牌：

export access_token=$(\
    curl --insecure -X POST https://localhost:8543/realms/quarkus/protocol/openid-connect/token \
    --user backend-service:secret \
    -H 'content-type: application/x-www-form-urlencoded' \
    -d 'username=admin&password=admin&grant_type=password' | jq --raw-output '.access_token' \
 )

注入授权客户端

Keycloak Authorization Client Java API可用于管理资源、直接向Keycloak获取权限等高级任务。向bean注入AuthzClient：

public class ProtectedResource {
    @Inject
    AuthzClient authzClient;
}

映射受保护资源

默认按需从Keycloak懒加载资源，并根据请求URI标识与映射需要保护的应用资源。若要关闭懒加载，改为启动时预加载全部资源，配置：

quarkus.keycloak.policy-enforcer.lazy-load-paths=false

预加载耗时取决于资源数量，可能影响应用初始加载时间。

受保护资源的更多配置

默认由Keycloak管理角色并决定路由访问权限。如需通过@RolesAllowed或application.properties配置受保护路由，参见OIDC Bearer令牌身份验证与Web端点授权。更多信息见Quarkus安全概览。

访问公共资源

若公共资源无需应用quarkus-keycloak-authorization策略，可在application.properties定义permit HTTP策略，见Web端点授权。使用此HTTP策略时，无需再为Keycloak授权策略设置下列禁用检查配置：

quarkus.keycloak.policy-enforcer.paths.1.paths=/api/public
quarkus.keycloak.policy-enforcer.paths.1.enforcement-mode=DISABLED

若需要限制匿名用户对公共资源的访问，可定义强制执行的Keycloak授权策略：

quarkus.keycloak.policy-enforcer.paths.1.paths=/api/public-enforcing
quarkus.keycloak.policy-enforcer.paths.1.enforcement-mode=ENFORCING

需要控制公共资源的匿名访问时，仅使用默认租户配置。

以编程方式检查权限作用域

除资源权限外，还能定义方法作用域。作用域通常代表对资源执行的操作。可以创建包含方法作用域的强制授权策略：

# path policy with enforced scope 'read' for method 'GET'
quarkus.keycloak.policy-enforcer.paths.1.name=Scope Permission Resource
quarkus.keycloak.policy-enforcer.paths.1.paths=/api/protected/standard-way
quarkus.keycloak.policy-enforcer.paths.1.methods.get.method=GET
quarkus.keycloak.policy-enforcer.paths.1.methods.get.scopes=read

# path policies without scope
quarkus.keycloak.policy-enforcer.paths.2.name=Scope Permission Resource
quarkus.keycloak.policy-enforcer.paths.2.paths=/api/protected/programmatic-way,/api/protected/annotation-way

这里要求用户同时具备Scope Permission Resource资源权限和read作用域。Keycloak策略执行器保护/api/protected/standard-way，无需@RolesAllowed等注解。但有些场景需要程序化检查。

可向bean注入SecurityIdentity，或用@PermissionsAllowed注解资源方法。下面三个方法都要求同一个read作用域：

import java.security.BasicPermission;
import java.util.List;

import jakarta.inject.Inject;
import jakarta.ws.rs.ForbiddenException;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

import org.keycloak.representations.idm.authorization.Permission;

import io.quarkus.security.PermissionsAllowed;
import io.quarkus.security.identity.SecurityIdentity;
import io.smallrye.mutiny.Uni;

@Path("/api/protected")
public class ProtectedResource {

    @Inject
    SecurityIdentity identity;

    @GET
    @Path("/standard-way")
    public Uni<List<Permission>> standardWay() {
        return Uni.createFrom().item(identity.<List<Permission>> getAttribute("permissions"));
    }

    @GET
    @Path("/programmatic-way")
    public Uni<List<Permission>> programmaticWay() {
        var requiredPermission = new BasicPermission("Scope Permission Resource") {
            @Override
            public String getActions() {
                return "read";
            }
        };
        return identity.checkPermission(requiredPermission).onItem()
                .transform(granted -> {
                    if (granted) {
                        return identity.getAttribute("permissions");
                    }
                    throw new ForbiddenException();
                });
    }

    @PermissionsAllowed("Scope Permission Resource:read")
    @GET
    @Path("/annotation-way")
    public Uni<List<Permission>> annotationWay() {
        return Uni.createFrom().item(identity.<List<Permission>> getAttribute("permissions"));
    }
}

1. /standard-way依据application.properties要求资源权限与read作用域。
2. /programmatic-way默认只检查资源权限；可使用SecurityIdentity#checkPermission增加作用域等约束。
3. /annotation-way的@PermissionsAllowed同时要求资源权限和read。详见使用注解授权。

多租户

与OIDC多租户类似，可为各租户配置策略执行器：

quarkus.keycloak.policy-enforcer.enabled=true

# Default Tenant
quarkus.oidc.auth-server-url=${keycloak.url:replaced-by-test-resource}/realms/quarkus
quarkus.oidc.client-id=quarkus-app
quarkus.oidc.credentials.secret=secret

quarkus.keycloak.policy-enforcer.enforcement-mode=PERMISSIVE
quarkus.keycloak.policy-enforcer.paths.1.name=Permission Resource
quarkus.keycloak.policy-enforcer.paths.1.paths=/api/permission
quarkus.keycloak.policy-enforcer.paths.1.claim-information-point.claims.static-claim=static-claim

# Service Tenant

quarkus.oidc.service-tenant.auth-server-url=${keycloak.url:replaced-by-test-resource}/realms/quarkus
quarkus.oidc.service-tenant.client-id=quarkus-app
quarkus.oidc.service-tenant.credentials.secret=secret

quarkus.keycloak.service-tenant.policy-enforcer.enforcement-mode=PERMISSIVE
quarkus.keycloak.service-tenant.policy-enforcer.paths.1.name=Permission Resource Service
quarkus.keycloak.service-tenant.policy-enforcer.paths.1.paths=/api/permission
quarkus.keycloak.service-tenant.policy-enforcer.paths.1.claim-information-point.claims.static-claim=static-claim

# WebApp Tenant

quarkus.oidc.webapp-tenant.auth-server-url=${keycloak.url:replaced-by-test-resource}/realms/quarkus
quarkus.oidc.webapp-tenant.client-id=quarkus-app
quarkus.oidc.webapp-tenant.credentials.secret=secret
quarkus.oidc.webapp-tenant.application-type=web-app
quarkus.oidc.webapp-tenant.roles.source=accesstoken

quarkus.keycloak.webapp-tenant.policy-enforcer.enforcement-mode=PERMISSIVE
quarkus.keycloak.webapp-tenant.policy-enforcer.paths.1.name=Permission Resource WebApp
quarkus.keycloak.webapp-tenant.policy-enforcer.paths.1.paths=/api/permission
quarkus.keycloak.webapp-tenant.policy-enforcer.paths.1.claim-information-point.claims.static-claim=static-claim

动态解析租户配置

为避免配置文件出现大量租户条目，可以实现io.quarkus.keycloak.pep.TenantPolicyConfigResolver，在运行时以编程方式定义配置：

package org.acme.security.keycloak.authorization;

import java.util.Map;

import jakarta.enterprise.context.ApplicationScoped;

import io.quarkus.keycloak.pep.TenantPolicyConfigResolver;
import io.quarkus.keycloak.pep.runtime.KeycloakPolicyEnforcerConfig;
import io.quarkus.keycloak.pep.runtime.KeycloakPolicyEnforcerTenantConfig;
import io.quarkus.oidc.OidcRequestContext;
import io.quarkus.oidc.OidcTenantConfig;
import io.smallrye.mutiny.Uni;
import io.vertx.ext.web.RoutingContext;

@ApplicationScoped
public class CustomTenantPolicyConfigResolver implements TenantPolicyConfigResolver {

    private final KeycloakPolicyEnforcerTenantConfig enhancedTenantConfig;
    private final KeycloakPolicyEnforcerTenantConfig newTenantConfig;

    public CustomTenantPolicyConfigResolver(KeycloakPolicyEnforcerConfig enforcerConfig) {
        this.enhancedTenantConfig = KeycloakPolicyEnforcerTenantConfig.builder(enforcerConfig.defaultTenant())
            .paths("/enhanced-config")
            .permissionName("Permission Name")
            .get("read-scope")
            .build();
        this.newTenantConfig = KeycloakPolicyEnforcerTenantConfig.builder()
            .paths("/new-config")
            .claimInformationPoint(Map.of("claims", Map.of("grant", "{request.parameter['grant']}")))
            .build();
    }

    @Override
    public Uni<KeycloakPolicyEnforcerTenantConfig> resolve(RoutingContext routingContext, OidcTenantConfig tenantConfig,
                                                OidcRequestContext<KeycloakPolicyEnforcerTenantConfig> requestContext) {
        String path = routingContext.normalizedPath();
        String tenantId = tenantConfig.tenantId().orElse(null);
        if ("enhanced-config-tenant".equals(tenantId) && path.equals("/enhanced-config")) {
            return Uni.createFrom().item(enhancedTenantConfig);
        } else if ("new-config-tenant".equals(tenantId) && path.equals("/new-config")) {
            return Uni.createFrom().item(newTenantConfig);
        }
        return Uni.createFrom().nullItem();
    }
}

1. 在默认租户配置中定义或更新/enhanced-config路径。
2. 向租户配置添加/new-config，包括以编程方式填充的自定义声明与值。
3. 回退到application.properties或其他SmallRye Config来源中的默认静态租户配置解析。

配置参考

以下配置遵循Keycloak策略执行器配置指南。原页区分构建时固定的配置与可在运行时覆盖的配置；此处保留属性、说明、环境变量、类型及默认值，具体阶段标记仍以原页为准。

其他命名租户

参考资料

• Keycloak文档
• Keycloak Authorization Services
• OpenID Connect
• JSON Web Token
• Quarkus安全概览
• Quarkus Keycloak Admin Client