lakeFS Java SDK 的 Policy 权限策略模型:属性结构、Statement 组成与 AuthApi 实战用法
lakeFS Java SDK 的 Policy 权限策略模型:属性结构、Statement 组成与 AuthApi 实战用法
本文围绕 lakeFS 官方 Java SDK(clients/java,包名 io.lakefs.clients.sdk)中的 Policy 模型类展开,完整解析其三个属性(id、creationDate、statement)的含义与约束,并结合同目录的 Statement 模型、AuthApi 的增删改查接口,以及后端 Go 侧的实现源码,讲清一条访问控制策略从"构造 JSON"到"服务端鉴权求值"的完整链路。读完本文,你将能在 Java 工程中直接构造、创建、查询、更新与删除 lakeFS 策略,并理解条件表达式在服务端是如何被解释执行的。
一、Policy 在 lakeFS 权限体系中的位置
lakeFS 的身份与访问管理(Auth)采用与 AWS IAM 高度相似的模型:用户(User)与组(Group)通过被**附加(attach)**策略(Policy)获得权限;策略由若干条 Statement(语句) 组成,每条语句声明对某些资源(Resource)允许或拒绝某些动作(Action)。Policy 是这一模型在 OpenAPI 与各语言 SDK 中的核心数据载体。
本文所讲的模型文档位于 clients/java/docs/Policy.md,对应的自动生成 Java 源码为 Policy.java;它与 Statement.md、AuthApi.md、PolicyList.md 共同构成策略相关的 SDK 使用面。其 OpenAPI 契约定义在仓库根目录的 api/swagger.yml(components/schemas/Policy,L1226 起)。
二、Policy 属性详解
依据 Policy.md 的 Properties 表,Policy 模型共包含 3 个属性:
| Name | Type | Description | Notes |
|---|---|---|---|
| id | String | 策略的唯一标识(显示名) | 必填 |
| creationDate | Long | Unix Epoch 秒级时间戳 | 可选(optional) |
| statement | List<Statement> | 策略包含的语句列表 | 必填 |
2.1 id:策略的唯一标识
id 是策略在系统中的唯一键,创建后不可更改。在 REST 层它同时充当路径参数(如 GET /auth/policies/{policyId}),因此要求全局唯一;创建时若 id 已存在,服务端将返回 409 Conflict(见 api/swagger.yml 中 createPolicy 的响应定义)。从后端 Go 结构看,它对应 pkg/auth/model/model.go 中 Policy.DisplayName,存储时作为 KV 键 policies/<displayName> 的组成部分(PolicyPath 函数)。
在 Java SDK 中,id 是必填字段:Policy.openapiRequiredFields 静态集合中同时包含 "id" 与 "statement",任何缺少其中之一的 JSON 在反序列化(validateJsonElement)时都会抛出 IllegalArgumentException,提示缺少必填字段。
2.2 creationDate:创建时间(可选)
creationDate 以 Long 存储,单位是 Unix Epoch 秒(注意不是毫秒)。它由服务端在创建策略时自动填充,通常无需客户端手动设置,因此在 SDK 中该字段被标注为 @Nullable(对应 OpenAPI 定义里 format: int64 的可选属性 creation_date,见 api/swagger.yml L1234-L1237)。
从后端实现看,创建时间来自 pkg/auth/model/model.go 中 Policy.CreatedAt(time.Time),在序列化与 Protobuf 转换(ProtoFromPolicy)时写入 PolicyData.CreatedAt。
2.3 statement:语句列表(必填)
statement 是 List<Statement>,至少包含一条语句——OpenAPI 定义中 minItems: 1,SDK 生成的 validateJsonElement 也会强制校验 statement 必须为 JSON 数组。它是策略真正表达"允许/拒绝什么"的地方,下一节详述。
此外,SDK 生成的 Policy 类还支持未声明属性的透传:通过 putAdditionalProperty 保存 OpenAPI 中未声明的扩展字段,并在序列化/反序列化时自动保留(参见 Policy.java 的 CustomTypeAdapterFactory)。这一机制让策略对象能兼容服务端未来新增的字段而不破坏既有代码。
三、Statement 结构:策略的"规则单元"
每条 Statement 由 Statement.md 定义,共 4 个属性:
| Name | Type | Description | Notes |
|---|---|---|---|
| effect | EffectEnum | 允许还是拒绝 | 必填 |
| resource | String | 规则作用的资源(ARN 或通配符) | 必填 |
| action | List<String> | 动作列表(如 fs:ReadObject) |
必填 |
| condition | Map<String, Map<String, List<String>>> | 规则生效的可选条件 | 可选 |
3.1 effect:允许或拒绝
EffectEnum 只有两个取值,对应 JSON 中的小写字符串:
| Name | Value |
|---|---|
| ALLOW | "allow" |
| DENY | "deny" |
Java SDK 中该枚举定义在 Statement.java(EffectEnum),通过 Gson 的 TypeAdapter 与字符串互相转换;传入未知值时抛出 IllegalArgumentException。后端 Go 侧同样维护这两个常量:StatementEffectAllow = "allow"、StatementEffectDeny = "deny"(见 pkg/auth/model/model.go)。
3.2 resource:资源 ARN
resource 是字符串,通常采用 lakeFS 的 ARN 格式 arn:lakefs:fs:::repository/<repo>/<path>,支持以 * 通配资源路径(如 arn:lakefs:fs:::repository/my-repo/*)。服务端通过 pkg/auth/arn.go 中的 ParseARN 解析该字符串为 5 段(partition/service/region/account/resource),再由 ArnMatch 进行分段匹配:partition、service、account 必须严格相等,而 resource 段支持通配符匹配(wildcard.Match,* 匹配任意多字符)。资源还支持 JSON 数组形式的简写(如 ["arn:.../a", "arn:.../b"]),由 ParsePolicyResourceAsList 展开为多条资源逐一匹配。
3.3 action:动作列表
action 是一个至少含 1 个元素的字符串数组(minItems: 1),取值形如 fs:ReadObject、fs:WriteObject、auth:CreatePolicy 等。动作全集定义在 pkg/permissions/actions.go,主要分两大类:
- fs 服务:仓库与对象操作,如
fs:CreateRepository、fs:ReadObject、fs:CreateCommit、fs:CreateBranch、fs:ReadBranch、fs:ListObjects、fs:ImportFromStorage等; - auth 服务:身份与策略管理,如
auth:ReadUser、auth:CreatePolicy、auth:AttachPolicy、auth:DetachPolicy、auth:ListPolicies等。
动作同样支持通配,例如 "fs:*" 表示所有 fs 操作。
3.4 condition:可选生效条件
condition 的嵌套类型为 Map<String, Map<String, List<String>>>,采用 AWS IAM 风格的"操作符 → 字段 → 取值列表"结构。当前服务端支持的四个操作符定义在 pkg/auth/condition.go:
| 操作符 | 语义 |
|---|---|
IpAddress |
来源 IP 命中条件中的 IP/CIDR 列表(命中即通过) |
NotIpAddress |
来源 IP 不在列表中(取反) |
StringLike |
字段值匹配通配符模式(* 多字符、? 单字符) |
StringNotLike |
字段值不匹配通配符模式(取反) |
以 IP 限制为例,JSON 形如:
{
"IpAddress": {
"SourceIp": ["203.0.113.0/24", "198.51.100.25/32"]
}
}
其求值逻辑(condition.go 的 EvaluateConditions)遵循两条规则:多个操作符之间是 AND(全部通过才算通过),同一操作符内多个字段是 AND、单个字段的多个取值是 OR。IpAddress 同时支持 CIDR 网段(net.ParseCIDR 后 ipNet.Contains)与单 IP(ParseIP 后 Equal)两种写法,上下文中的来源 IP 由服务端通过 NewConditionContext(clientIP) 注入 SourceIp 字段。相关求值行为在 pkg/auth/condition_test.go 中有系统性测试(单 IP 命中/未命中、CIDR 命中、多值 OR、非法格式报错等用例)。
四、Policy 的完整 JSON 形态
综合 Policy 与 Statement 的结构,一条完整策略的 JSON 如下(与 pkg/auth/model/model.go 中 Statement 的 json 标签 Effect/Action/Resource/Condition 保持一致):
{
"id": "my-policy",
"creation_date": 1700000000,
"statement": [
{
"effect": "allow",
"action": ["fs:ReadObject", "fs:ListObjects"],
"resource": "arn:lakefs:fs:::repository/example-repo/*",
"condition": {
"IpAddress": {
"SourceIp": ["10.0.0.0/8", "192.168.1.1"]
}
}
},
{
"effect": "deny",
"action": ["fs:DeleteObject"],
"resource": "arn:lakefs:fs:::repository/example-repo/archive/*"
}
]
}
注意:creation_date 为可选字段,创建策略时通常不传;effect、resource、action 在每条 statement 中均必填。
五、通过 AuthApi 在 Java 中操作 Policy
Policy 模型的生命周期操作全部集中在 AuthApi.md 的 AuthApi 类中。以下是与 Policy 直接相关的接口对照(详见 api/swagger.yml):
| SDK 方法 | HTTP 端点 | 说明 |
|---|---|---|
createPolicy(policy) |
POST /auth/policies |
创建策略,成功返回 201 及 Policy 对象 |
getPolicy(policyId) |
GET /auth/policies/{policyId} |
按 id 查询策略,404 表示不存在 |
updatePolicy(policyId, policy) |
PUT /auth/policies/{policyId} |
整体更新策略内容 |
deletePolicy(policyId) |
DELETE /auth/policies/{policyId} |
删除策略,成功返回 204 |
listPolicies().prefix(..).after(..).amount(..) |
GET /auth/policies |
分页列出策略,返回 PolicyList |
attachPolicyToUser(userId, policyId) |
PUT /auth/users/{userId}/policies/{policyId} |
将策略附加给用户 |
detachPolicyFromUser(userId, policyId) |
DELETE /auth/users/{userId}/policies/{policyId} |
从用户解除策略 |
attachPolicyToGroup(groupId, policyId) |
PUT /auth/groups/{groupId}/policies/{policyId} |
将策略附加给组 |
detachPolicyFromGroup(groupId, policyId) |
DELETE /auth/groups/{groupId}/policies/{policyId} |
从组解除策略 |
5.1 创建一条策略
import io.lakefs.clients.sdk.ApiClient;
import io.lakefs.clients.sdk.ApiException;
import io.lakefs.clients.sdk.Configuration;
import io.lakefs.clients.sdk.auth.*;
import io.lakefs.clients.sdk.model.Policy;
import io.lakefs.clients.sdk.model.Statement;
import io.lakefs.clients.sdk.model.Statement.EffectEnum;
import java.util.List;
import java.util.Map;
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("http://localhost:8000");
// 使用 access key / secret key 配置 Basic 认证
defaultClient.setUsername("YOUR_ACCESS_KEY_ID");
defaultClient.setPassword("YOUR_SECRET_ACCESS_KEY");
AuthApi apiInstance = new AuthApi(defaultClient);
Statement readStmt = new Statement()
.effect(EffectEnum.ALLOW)
.action(List.of("fs:ReadObject", "fs:ListObjects"))
.resource("arn:lakefs:fs:::repository/example-repo/*")
.condition(Map.of("IpAddress",
Map.of("SourceIp", List.of("10.0.0.0/8"))));
Policy policy = new Policy()
.id("example-readonly")
.statement(List.of(readStmt));
try {
Policy result = apiInstance.createPolicy(policy).execute();
System.out.println(result);
} catch (ApiException e) {
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getResponseBody());
}
5.2 查询、更新与删除
// 查询
Policy p = apiInstance.getPolicy("example-readonly").execute();
// 整体更新(替换全部 statement)
Policy updated = new Policy()
.id("example-readonly")
.statement(List.of(readStmt, denyStmt));
apiInstance.updatePolicy("example-readonly", updated).execute();
// 删除
apiInstance.deletePolicy("example-readonly").execute();
// 分页列出(prefix 过滤 + after 游标 + amount 页大小)
PolicyList list = apiInstance.listPolicies()
.prefix("example-")
.after("")
.amount(100)
.execute();
5.3 将策略附加到主体
apiInstance.attachPolicyToUser("alice", "example-readonly").execute();
apiInstance.attachPolicyToGroup("data-team", "example-readonly").execute();
一个主体(用户或组)可以附加多条策略;实际鉴权时,服务端会汇总主体自身及所属组的全部策略进行求值(见 pkg/auth/service.go 的 Service 接口中策略管理与 Authorizer.Authorize 的设计)。
六、从 SDK 到服务端:Policy 如何被鉴权
一条策略从 Java 构造到真正生效,经历如下链路:
- SDK 侧:
Policy/Statement对象经 Gson 序列化为 JSON(字段名id、creation_date、statement、effect、action、resource、condition),通过AuthApi.createPolicy提交到POST /auth/policies。 - OpenAPI 契约校验:服务端按 api/swagger.yml 的 Schema 校验必填字段(
id、statement;statement 内effect、resource、action),非法输入返回 400 ValidationError。 - 存储:后端将策略以
PolicyData(Protobuf)形式存入 KV 存储,键为policies/<id>(前缀定义见 pkg/auth/model/model.go 的policiesPrefix)。 - 求值:用户每次访问资源时,服务端汇总其有效策略,逐条 statement 匹配:
ArnMatch校验 resource(含通配),动作与权限点对照(见 pkg/permissions/actions.go),若语句带condition则调用EvaluateConditions结合请求上下文(来源 IP 等)求值,最终按"显式 deny 优先、无匹配则拒绝"的规则返回授权结果。
值得留意的是,SDK 生成的 Statement 中 condition 的三层 Map 结构(操作符 → 字段 → 值列表)正是为对齐后端 pkg/auth/condition.go 的 EvaluateConditions(conditions map[string]map[string][]string, ctx) 签名而设计,两层 SDK 模型与 Go 实现保持严格一致。
七、总结与延伸阅读
Policy 是 lakeFS 权限体系中"最小但最完整"的模型:id 定位策略、creationDate 记录生命周期、statement 承载真正的授权规则;每条 statement 又以 effect + action + resource + condition 四元组精确表达"何时、对谁、允许做什么"。在 Java 工程中,配合 AuthApi 的创建/查询/更新/删除/附加接口即可完成完整的策略治理闭环。
如需继续深入,建议按以下路径查阅仓库源码:
- 模型契约:api/swagger.yml(
PolicyL1226、StatementL1203) - Java SDK 模型:Policy.java、Statement.java
- API 文档:AuthApi.md、PolicyList.md
- 后端结构与存储:pkg/auth/model/model.go
- ARN 解析与资源匹配:pkg/auth/arn.go
- 条件求值器与测试:pkg/auth/condition.go、pkg/auth/condition_test.go
- 动作全集:pkg/permissions/actions.go