跳到主内容

Quarkus

Quarkus Casdoor Auth 扩展将 Quarkus 应用连接到 Casdoor。它是 Quarkiverse 的一部分,后者是社区 Quarkus 扩展的托管平台。

该扩展基于 Quarkus 自身的 quarkus-oidc 构建,由后者处理登录和令牌验证,而本扩展增加了 Casdoor 特有的功能:

  • 用户的 Casdoor roles 转换为 Quarkus 角色,因此 @RolesAllowed 可以正常工作;
  • @PermissionsAllowed("resource:action") 会根据 Casdoor permissions 并使用 Enforce API 进行检查;
  • 名为 casdoor 的 HTTP 安全策略会将请求路径和方法与 Casdoor 权限进行检查。

0.1.0 版本基于 Quarkus 3.40 构建,需要 Java 17 或更高版本。

步骤 1:在 Casdoor 中创建应用​

  1. 在 Casdoor UI 中,打开 Applications 并在你的组织中添加一个应用。
  2. 将应用的回调 URL(例如 http://localhost:8080/)添加到 Redirect URLs。
  3. 复制 Client ID 和 Client secret。

步骤 2:添加扩展​

使用 Maven:

<dependency>
<groupId>io.quarkiverse.casdoor-auth</groupId>
<artifactId>quarkus-casdoor-auth</artifactId>
<version>0.1.0</version>
</dependency>

使用 Gradle:

implementation("io.quarkiverse.casdoor-auth:quarkus-casdoor-auth:0.1.0")

该扩展已引入 quarkus-oidc,因此你无需单独添加它。

步骤 3:配置登录​

在 application.properties 中将 quarkus-oidc 指向你的 Casdoor 服务器:

quarkus.oidc.auth-server-url=https://door.casdoor.com
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Client secret>
# web-app: redirect users to the Casdoor sign-in page
# service (the default): accept bearer tokens only, e.g. for a REST API called by a frontend
quarkus.oidc.application-type=web-app

Casdoor 在 /.well-known/openid-configuration 发布其 OIDC 发现文档,因此无需其他配置。有关所有 quarkus.oidc 选项,请参阅 Quarkus 关于 authorization code flow 和 bearer tokens 的指南。

安全身份包含两个属性:casdoor.organization 和 casdoor.username,它们分别从令牌的 owner 和 name(或 preferred_username)声明中读取。

步骤 4:使用 Casdoor 角色​

用户 Casdoor 角色的名称会被添加到身份中:

@GET
@Path("/admin")
@RolesAllowed("admin")
public String admin() {
return "admin";
}

使用默认的 JWT token format 时,角色包含在令牌中。JWT-Standard 格式的令牌不包含角色,因此扩展会从 UserInfo 响应中读取它们;启用方法如下:

quarkus.oidc.authentication.user-info-required=true

Casdoor 组位于标准的 groups 声明中,quarkus-oidc 已经将其映射为角色。

步骤 5:检查 Casdoor 权限​

@PermissionsAllowed("data1:read") 向 Casdoor 发送 Casbin 请求 ["<organization>/<username>", "data1", "read"],如果您的某个 Casdoor 权限允许该调用,则执行操作:

@GET
@Path("/data1")
@PermissionsAllowed("data1:read")
public String data1() {
return "data1";
}

例如,在组织 my-org 中,一个具有角色 my-org/admin、资源 data1 和操作 read 的权限,使用如下模型:

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act

允许 admin 角色的每个成员使用 @PermissionsAllowed("data1:read")。

默认情况下,会检查用户所在组织的所有权限。要检查单个权限、模型、资源或 enforcer,请设置以下项之一:

quarkus.casdoor.authorization.permission-id=my-org/my-permission
# quarkus.casdoor.authorization.model-id=my-org/my-model
# quarkus.casdoor.authorization.resource-id=my-resource
# quarkus.casdoor.authorization.enforcer-id=my-org/my-enforcer

扩展程序使用应用的客户端 ID 和密钥调用 Enforce API,因此权限、模型或 enforcer 必须属于应用所在的组织。

基于路径的授权​

casdoor HTTP 安全策略发送 ["<organization>/<username>", "<path>", "<method>"],例如 ["my-org/alice", "/api/orders", "GET"],因此具有资源 /api/orders 和操作 GET 的 Casdoor 权限控制该端点。将其应用于路径:

quarkus.http.auth.permission.casdoor.paths=/api/*
quarkus.http.auth.permission.casdoor.policy=casdoor

或者通过 @AuthorizationPolicy(name = "casdoor") 应用于端点。匿名请求将被拒绝。

缓存​

每次检查都会调用 Casdoor,因此权限更改会立即生效。若要缓存结果,请设置例如 quarkus.casdoor.authorization.cache-ttl=30S。

配置参考​

PropertyDefaultDescription
quarkus.casdoor.endpointquarkus.oidc.auth-server-urlCasdoor server URL used for the Enforce API
quarkus.casdoor.client-idquarkus.oidc.client-idClient ID used to call the Casdoor API
quarkus.casdoor.client-secretquarkus.oidc.credentials.secretClient secret used to call the Casdoor API
quarkus.casdoor.roles.enabledtrueAdd the user's Casdoor roles to the identity
quarkus.casdoor.authorization.enabledtrueCheck @PermissionsAllowed with Casdoor
quarkus.casdoor.authorization.permission-idPermission to enforce, as <organization>/<name>
quarkus.casdoor.authorization.model-idModel whose permissions are enforced
quarkus.casdoor.authorization.resource-idResource whose permissions are enforced
quarkus.casdoor.authorization.enforcer-idEnforcer to use
quarkus.casdoor.authorization.cache-ttl0SHow long an enforce result is cached
quarkus.casdoor.authorization.timeout10STimeout of a call to the Casdoor API