guide:modeling@zh-Hans

指南

建模模式:从重写规则到实际权限

八种常见的授权需求,每一种都写成元组,在可行时写成论文命名空间配置记法中的规则,并分别用 SpiceDB 和 OpenFGA 的 schema 语言写出。

事实核对日期 论文相关章节 §2.1, §2.3.1, §2.4.2, §3.2.3, §5, §6

论文描述了其数据模型和配置语言,但只给出了一个完整的策略示例,即图 1。其结论的主张更进一步:其 “simple yet flexible data model and configuration language support a variety of access control policies from both consumer and enterprise applications”(简单而灵活的数据模型和配置语言支持来自消费级和企业级应用的各种访问控制策略)(§6)。其相关工作一节列出了它所覆盖的模式:“Zanzibar’s data model supports permissions, users, groups, and inheritance”(Zanzibar 的数据模型支持权限、用户、组和继承),即 Multics、UNIX、POSIX ACL 和 VMS 中的那些模式,以及 “a number of Zanzibar clients have implemented RBAC policies on top of Zanzibar’s namespace configuration language”(若干 Zanzibar 客户端已在 Zanzibar 的命名空间配置语言之上实现了 RBAC 策略)(§5)。

本页写出实践中常见的八种需求。每一节给出该模式要回答的问题、元组、在论文能够表达时用图 1 的论文记法写出的规则、用 SpiceDB 的 schema 语言和 OpenFGA 的 DSL 写出的同一规则,以及一张高亮了决定答案的路径的元组图。模式列表沿用 OpenFGA 的建模指南;记法见元组页面。

贯穿全站的示例:Anne、Beto 和 Chen(user:anne、user:beto、user:chen);位于 folder:A 中的文档 doc:readme;组 group:eng。Anne 拥有 readme,Beto 属于 eng,eng 的成员可以查看 readme,Chen 可以查看文件夹 A。

角色与权限

问题:Anne 能否编辑 readme?Beto 呢?角色是授予的东西(owner、editor、viewer)。权限是检查的东西(edit、view)。授予角色、检查权限,可以在角色变化时保持检查不变。

元组:

doc:readme#owner@user:anne
doc:readme#viewer@group:eng#member
group:eng#member@user:beto

在论文记法中,角色是存有元组的关系,权限是规则中没有 _this 的关系,因此谁都无法直接向它们写入元组。只需要 union 和 computed_userset,二者都出自图 1:

name: "doc"

relation { name: "owner" }
relation { name: "editor" }
relation { name: "viewer" }

relation {
 name: "edit"
 userset_rewrite {
  union {
   child { computed_userset { relation: "owner" } }
   child { computed_userset { relation: "editor" } }
} } }

relation {
 name: "view"
 userset_rewrite {
  union {
   child { computed_userset { relation: "viewer" } }
   child { computed_userset { relation: "edit" } }
} } }

图 1 用另一种方式完成同样的事:它把 _this 和更大的角色放在同一个关系里(“All owners are editors, and all editors are viewers”,所有所有者都是编辑者,所有编辑者都是查看者)。两种形式都是重写规则;上面的写法把授予用的名称和检查用的名称分开了。

SpiceDB 在语法上区分这两类:relation 行是可以存储的内容,permission 行是计算出来的。其文档写道 “relations should be named as nouns”(关系应以名词命名)以及 “permissions should be named as verbs or nouns”(权限应以动词或名词命名)(schema 文档)。

definition user {}

definition group {
    relation member: user
}

definition doc {
    relation owner: user
    relation editor: user | group#member
    relation viewer: user | group#member

    permission edit = owner + editor
    permission view = viewer + edit
}

SpiceDB schema;依照 2026-11-13 时的文档语法编写;未运行验证器。

OpenFGA 只有一种关系。方括号中没有类型限制的关系无法被直接写入;OpenFGA 的角色与权限指南把这样的关系(booking_viewer、booking_adder)用作权限,其他指南则为它们加上 can_ 前缀。

model
  schema 1.1

type user

type group
  relations
    define member: [user]

type doc
  relations
    define owner: [user]
    define editor: [user, group#member]
    define viewer: [user, group#member]
    define can_edit: owner or editor
    define can_view: viewer or can_edit

OpenFGA DSL;依照 2026-11-13 时的文档语法编写;未运行验证器。

Anne 的 edit 从何而来?

角色与权限:Anne 的 edituser:anne 有一条已存储的 owner 边指向 doc:readme#owner。一条标有“重写”的虚线箭头从 doc:readme#owner 指向虚线框 doc:readme#edit,另一条从 edit 指向虚线框 doc:readme#view。从 Anne 经 owner 到 edit 的路径被高亮。user:beto 经由组到达 doc:readme#viewer,而 viewer 只有一条指向 view 的虚线箭头。user:anneuser:betodoc:readme#ownerdoc:readme#viewerdoc:readme#editdoc:readme#view元组经由 group:eng重写重写重写
实线箭头是已存储的元组;虚线箭头和虚线框由重写规则计算得出。Anne 能编辑是因为她是所有者;Beto 能到达 view,但到达不了 edit。

注意,edit 和 view 不存放任何元组。新增一个角色,比如 commenter,只需要一个新关系,再在权限规则中多加一个子节点;现有元组都不用改。

关系的数量

对这种风格的一个常见批评针对的是命名。在 Oso 的博客文章 “Google Zanzibar Isn’t Flexible”(Oso 销售一款与之竞争的授权产品)中,Greg Sarjeant 写道 “the literature about ReBAC is rife with “relations” like can_delete and can_archive”(关于 ReBAC 的文献中充斥着 can_delete、can_archive 这样的“关系”),称这 “essentially the same thing as creating a relation for every authorized action”(本质上等同于为每个被授权的操作创建一个关系),并得出结论说这是 “an indication that relations are the wrong abstraction for authorization”(表明关系是不适合授权的抽象)(Oso,2024-11-01,2025-11-07 更新)。

数量确实会增长:应用要检查的每个操作都需要在 schema 中有一个名称。重写规则能让其保持很少的,是已存储元组的数量以及有人写入的关系的数量。在上面的 schema 中,三个关系存放元组(owner、editor、viewer),权限是它们的纯函数,因此新增 can_archive 只改一次 schema,不涉及任何元组。论文自己引入重写的动机也是如此:为每个对象把派生关系存为元组 “would be wasteful and make it hard to make modifications across all objects”(既浪费,又使得跨所有对象的修改变得困难)(§2.3.1)。schema 中的权限名称是成本还是文档,正是 Oso 与 Zanzibar 风格产品意见分歧之处;本页不对此下结论。

父子继承

问题:能查看文件夹 A 的 Chen,能否查看其中的 readme?从容器继承就是 tuple_to_userset 叶节点:读取对象的 parent 元组,然后在每个父对象上询问某个关系。

元组:

doc:readme#parent@folder:A#...
folder:A#viewer@user:chen

论文的图 1 已经包含这条规则,即 viewer 的第三个子节点。把它加到上一节的 view 权限中:

relation { name: "parent" }

relation {
 name: "view"
 userset_rewrite {
  union {
   child { computed_userset { relation: "viewer" } }
   child { computed_userset { relation: "edit" } }
   child { tuple_to_userset {
     tupleset { relation: "parent" }
     computed_userset {
       object: $TUPLE_USERSET_OBJECT  # parent folder
       relation: "viewer"
   } } }
} } }

在 SpiceDB 中,箭头 parent->view 沿着 parent 关系前进,并在找到的对象上询问 view(schema 文档):

definition folder {
    relation parent: folder
    relation viewer: user | group#member
    permission view = viewer + parent->view
}

definition doc {
    relation parent: folder
    relation owner: user
    relation editor: user | group#member
    relation viewer: user | group#member

    permission edit = owner + editor
    permission view = viewer + edit + parent->view
}

SpiceDB schema;依照 2026-11-13 时的文档语法编写;未运行验证器。

在 OpenFGA 中,同样的写法是 X from Y;其父子指南用它使文件夹的编辑者成为其中文档的编辑者。

type folder
  relations
    define parent: [folder]
    define viewer: [user, group#member] or viewer from parent

type doc
  relations
    define parent: [folder]
    define owner: [user]
    define editor: [user, group#member]
    define viewer: [user, group#member] or viewer from parent
    define can_edit: owner or editor
    define can_view: viewer or can_edit

OpenFGA DSL;依照 2026-11-13 时的文档语法编写;未运行验证器。

两个产品的版本还都给 folder 加了一个指向 folder 的 parent,于是文件夹会从上一级文件夹继承,链条的深度由元组决定。论文的图 1 只展示了文档这一侧。

哪些元组决定了 Chen 的访问权?

父子继承:Chen 经由文件夹 A 查看 readmeuser:chen 有一条 viewer 边指向 folder:A;folder:A 有一条 parent 边指向 doc:readme。这两条边和三个节点都被高亮。user:anne 有一条指向 doc:readme 的 owner 边,未被高亮。user:anneuser:chenfolder:Adoc:readmeownerviewerparent
没有任何元组同时提到 Chen 和 readme。parent 元组把关于 readme 的问题变成关于文件夹 A 的问题。

注意,把 readme 移到另一个文件夹只需改动一个元组(删除一个 parent 元组,写入另一个),所有继承来的授权都会随之改变。这正是论文中“new enemy”问题的例 A 所讨论的操作:“document ACLs inherit from folder ACLs”(文档 ACL 继承自文件夹 ACL)(§2.2),因此 ACL 变更与移动的顺序很重要;参见一致性。

组与嵌套组

问题:Beto 属于一个子团队;授予 eng 的权限能到达他吗?贯穿示例的这个变体加入了一个假设的子团队 group:sre,Beto 属于 sre,sre 属于 eng。

元组:

group:sre#member@user:beto
group:eng#member@group:sre#member
doc:readme#viewer@group:eng#member

在论文中,组不需要重写规则。member 是一个普通关系,又因为元组的用户可以是用户集,“a ⟨userset⟩ allows ACLs to refer to groups and thus supports representing nested group membership”(⟨userset⟩ 允许 ACL 引用组,从而支持表示嵌套的组成员关系)(§2.1):

name: "group"

relation { name: "member" }

论文的配置没有说明一个关系接受哪些种类的用户。两个产品都要求在 schema 中写明这一点:只有在 group#member 被列为允许的主体时,嵌套才会生效。

definition group {
    relation member: user | group#member
}

SpiceDB schema;依照 2026-11-13 时的文档语法编写;未运行验证器。

type group
  relations
    define member: [user, group#member]

OpenFGA DSL;依照 2026-11-13 时的文档语法编写;未运行验证器。

授权如何到达 Beto?

嵌套组:Beto 经由 sre 和 eng 到达 readmeuser:beto 有一条 member 边指向虚线用户集 group:sre#member。group:sre#member 有一条 member 边指向虚线用户集 group:eng#member。group:eng#member 有一条 viewer 边指向 doc:readme。整条链都被高亮。user:betogroup:sre#membergroup:eng#memberdoc:readmemembermemberviewer
三个元组,三跳。Check 从 readme 向外追逐用户集,直到找到 Beto。

注意,sre 加入 eng 时,文档的元组并没有改变:组是一个用户集,用与 ACL 相同的元组写成(§2.1),因此成员关系的变化只停留在组内部。同样的间接性也是深或宽的组用指针追逐来检查会很慢的原因;论文的解决办法是 Leopard 索引(§3.2.4)。

黑名单(排除)

问题:eng 的成员可以查看 readme,但有一个人例外。在这个变体中,Beto 在 readme 上被屏蔽。排除从一个集合中去掉另一个集合。

元组:

doc:readme#viewer@group:eng#member
group:eng#member@user:beto
doc:readme#blocked@user:beto

论文把排除列为一个运算符(§2.3.1),也列为 Expand 用户集树中的一种节点(§2.4.5),但图 1 没有展示它的写法。下面的代码块照搬图 1 的形状,用 exclusion 代替 union;这个关键字,以及“第一个子节点是基础、第二个子节点被减去”的规则,是本页的假设,而非论文的语法。

relation { name: "blocked" }

relation {
 name: "can_view"
 userset_rewrite {
  exclusion {
   child { computed_userset { relation: "view" } }
   child { computed_userset { relation: "blocked" } }
} } }

SpiceDB 把排除写作 -(schema 文档)。在 view 之上定义带屏蔽的权限,可以让表达式不需要括号:

definition doc {
    relation parent: folder
    relation owner: user
    relation editor: user | group#member
    relation viewer: user | group#member
    relation blocked: user

    permission edit = owner + editor
    permission view = viewer + edit + parent->view
    permission can_view = view - blocked
}

SpiceDB schema;依照 2026-11-13 时的文档语法编写;未运行验证器。

OpenFGA 把它写作 but not(其 JSON 形式中为 difference);其黑名单指南屏蔽了某团队中的一名成员,使其无法编辑该团队可以编辑的文档。

type doc
  relations
    define parent: [folder]
    define blocked: [user]
    define owner: [user]
    define editor: [user, group#member]
    define viewer: [user, group#member] or viewer from parent
    define can_edit: owner or editor
    define can_view: (viewer or can_edit) but not blocked

OpenFGA DSL;依照 2026-11-13 时的文档语法编写(配置语言页面允许用括号对运算符分组);未运行验证器。

哪个元组起决定作用?

黑名单:Beto 被排除user:beto 有一条 member 边指向虚线用户集 group:eng#member,后者有一条 viewer 边指向 doc:readme。另外,user:beto 有一条 blocked 边直接指向 doc:readme。blocked 边被高亮,它决定了答案:否。user:betogroup:eng#memberdoc:readmememberviewerblocked
Beto 属于 view(经由 eng),也属于 blocked。view 减去 blocked 不包含他,因此 can_view 回答“否”。

注意,有一条通往文档的路径已经不够了:排除必须同时查看两侧。Zanzibar 只在 “when the outcome of one node determines the result of a subtree”(某个节点的结果决定了子树的结果时)才取消子树的其余部分(§3.2.3)。一个“是”就能决定并集;而对于排除,基础一侧的“是”在被减去的一侧确定之前什么也决定不了。还要注意被屏蔽的范围:由于 can_view 是从整个 view 中减去,被屏蔽的所有者也会失去 can_view。

公开访问(通配符)

问题:任何人都能查看一个公开文档吗?论文的记法中没有答案。⟨user⟩ 是 “⟨user_id⟩ | ⟨userset⟩”,而用户 ID “is an integer”(是一个整数)(§2.1);没有表示所有用户的值,论文也没有讨论公开对象。在论文的模型中,最接近的构造是一个包含所有用户的组,这需要每个用户一个元组;Google 如何处理公开共享,论文没有描述。

两个产品都增加了一种通配符主体 user:*,只允许在 schema 列出它的地方使用。元组:

doc:readme#viewer@user:*
definition doc {
    relation viewer: user | user:* | group#member
    permission view = viewer
}

SpiceDB schema;依照 2026-11-13 时的文档语法编写;未运行验证器。

type doc
  relations
    define viewer: [user, user:*, group#member]

OpenFGA DSL;依照 2026-11-13 时的文档语法编写;未运行验证器。

两个项目都对此提出了警告。AuthZed:“Be very careful with wildcard support in your schema!”(在 schema 中支持通配符时要非常小心!)以及 “Only grant it to read permissions, unless you intend to allow for universal writing”(只把它授予读权限,除非你打算允许所有人写入)(schema 文档)。OpenFGA:“type-bound public access is not a wildcard or a regex expression”(类型绑定的公开访问不是通配符或正则表达式);user:* 只能作为用户出现,不能作为对象(document:*),也不能出现在用户集中(org:*#member)(公开访问指南)。

多重限制(交集)

问题:只有同时是文档所属团队成员的所有者才可以发布它。Anne 能发布 readme 吗?交集要求用户属于每一个子节点。

这个变体增加了一个从 readme 指向 group:eng 的 team 关系。元组:

doc:readme#owner@user:anne
doc:readme#team@group:eng#...
group:eng#member@user:beto

与排除一样,论文提到了交集(§2.3.1),但没有展示它的写法。这个代码块照搬图 1 的形状;intersection 这个关键字是假设:

relation { name: "team" }

relation {
 name: "publish"
 userset_rewrite {
  intersection {
   child { computed_userset { relation: "owner" } }
   child { tuple_to_userset {
     tupleset { relation: "team" }
     computed_userset {
       object: $TUPLE_USERSET_OBJECT  # the doc's team
       relation: "member"
   } } }
} } }

SpiceDB 把交集写作 &:

definition doc {
    relation owner: user
    relation team: group
    permission publish = owner & team->member
}

SpiceDB schema;依照 2026-11-13 时的文档语法编写;未运行验证器。

OpenFGA 把它写作 and;其多重限制指南构建了同样的形状:can_delete 为同时是所属组织成员的写入者。

type doc
  relations
    define owner: [user]
    define team: [group]
    define can_publish: owner and member from team

OpenFGA DSL;依照 2026-11-13 时的文档语法编写;未运行验证器。

为什么 Anne 被拒绝?

交集:Anne 是所有者,但不在团队中user:anne 有一条高亮的 owner 边指向 doc:readme。group:eng 有一条 team 边指向 doc:readme。user:beto 有一条 member 边指向 group:eng。一条高亮的注释说明不存在元组 group:eng#member@user:anne。交集的一个子节点满足,另一个不满足,因此答案为否。user:anneuser:betogroup:engdoc:readme不存在元组group:eng#member@user:anneownermemberteam
publish = owner ∩ (team → member)。Anne 属于第一个集合,不属于第二个,因此答案为否。Beto 属于第二个,不属于第一个。

注意,起决定作用的事实是一个缺失的元组。添加 group:eng#member@user:anne 就会使答案变为“是”,而无需改动文档。

自定义角色

问题:管理员在运行时定义了一个新角色“reviewer”,并授予它对 readme 的查看权限。持有该角色的 Chen 能查看吗?固定在 schema 中的角色(owner、editor)只有在 schema 改变时才会变;自定义角色则是数据。

OpenFGA 的自定义角色指南把它们建模为一个单独的类型,“because our roles are going to be dynamic and might change frequently”(因为我们的角色是动态的,可能经常变化):用户以 assignee 关系关联到一个 role 对象,再把该角色的 assignee 作为用户集授予关系(role:media-manager#assignee 作为 asset-category:logos 的 editor)。AuthZed 的用户自定义角色文章(2021-10-27)用 role#member 做了同样的事。

元组(一个变体:Chen 持有一个角色,而不是文件夹授权):

role:reviewer#assignee@user:chen
doc:readme#viewer@role:reviewer#assignee
doc:readme#editor@role:maintainer#assignee

在论文中,这就是换了一个命名空间名称的组模式:role 是一个只有一个普通关系的命名空间,readme 的 viewer 存储一个指向它的用户集。规则无需改动:

name: "role"

relation { name: "assignee" }
definition role {
    relation assignee: user
}

definition doc {
    relation owner: user
    relation editor: user | group#member | role#assignee
    relation viewer: user | group#member | role#assignee

    permission edit = owner + editor
    permission view = viewer + edit
}

SpiceDB schema;依照 2026-11-13 时的文档语法编写;未运行验证器。

type role
  relations
    define assignee: [user]

type doc
  relations
    define owner: [user]
    define editor: [user, group#member, role#assignee]
    define viewer: [user, group#member, role#assignee]
    define can_edit: owner or editor
    define can_view: viewer or can_edit

OpenFGA DSL;依照 2026-11-13 时的文档语法编写;未运行验证器。

运行时定义的角色如何授予访问权?

自定义角色:Chen 经由 reviewer 角色查看user:chen 有一条高亮的 assignee 边指向虚线用户集 role:reviewer#assignee,后者有一条高亮的 viewer 边指向 doc:readme。第二个虚线用户集 role:maintainer#assignee 有一条 editor 边指向 doc:readme,且没有成员。user:chenrole:reviewer#assigneerole:maintainer#assigneedoc:readmeassigneeviewereditor
创建角色、把 Chen 指派给它、在 readme 上授予它,这是三次元组写入;schema 不变。

注意,角色的授权是按对象进行的。如果一个角色要表示“可以在此仓库的任何地方创建和删除 issue”,它的权限集合也需要作为数据存储。AuthZed 的访问控制管理页面展示了这种更细粒度的模式:一个 role 定义,每个权限对应一个通配符关系(relation create_issue: user:*);一个把角色与被授予者关联起来的 role_grant 对象;以及 permission create_issue = role->create_issue & grantee 形式的权限。代价是每个权限对应一个 schema 关系,这又回到了上文的命名问题。

所有权转移

问题:Anne 把 readme 交给 Beto。之后 Beto 必须是所有者而 Anne 不是,且不存在两人同时是或都不是所有者的时刻。这不是一个 schema 模式:三种记法都无法声明“恰好一个所有者”,这里引用的 schema 文档也没有展示任何基数约束。这是一种写入模式。

元组变更:

delete  doc:readme#owner@user:anne
write   doc:readme#owner@user:beto

论文的 Write API 涵盖了这种情况。客户端 “may also modify all tuples related to an object via a read-modify-write process with optimistic concurrency control”(也可以通过带乐观并发控制的读-改-写过程修改与一个对象相关的所有元组):读取该对象的元组,包括每个对象各一个的“lock”元组,然后发送写入,“along with a touch on the lock tuple … with the condition that the writes will be committed only if the lock tuple has not been modified since the read”(连同对锁元组的一次 touch 操作……条件是仅当锁元组自读取以来未被修改时才提交这些写入),否则重试(§2.4.2)。锁元组可以阻止两次并发的转移同时成功。

  • SpiceDB。 WriteRelationships “atomically writes and/or deletes a set of specified relationships”(以原子方式写入和/或删除一组指定的关系),并且 “if any preconditions fail, the entire transaction will be reverted”(任何前置条件不满足时,整个事务都会回滚)(permission_service.proto)。对 doc:readme#owner@user:anne 设置一个 MUST_MATCH 前置条件,就起到论文中锁元组的作用:如果 Anne 已不再是所有者,转移就会失败。
  • OpenFGA。 “You can combine both writes and deletes in a single transactional API request”(可以在单个事务性 API 请求中同时组合写入和删除),并且 “all operations in the request will either succeed together or fail together”(请求中的所有操作要么一起成功,要么一起失败),每个请求最多 100 个元组(更新元组)。同一页面说,写入一个已存在的元组 “would normally cause the whole request to fail”(通常会导致整个请求失败),并为 “deleting tuples that might not exist”(删除可能不存在的元组)提供了 on_missing: "ignore"(OpenFGA v1.10.0 及以后)。这意味着默认情况下删除一个不存在的元组会使请求失败,从而让删除起到锁元组的作用;该页面并没有直接写明这一默认行为,这里也没有实际运行验证。

发生了什么变化?

转移前的所有权user:anne 有一条高亮的 owner 边指向 doc:readme。user:beto 没有边。user:anneuser:betodoc:readmeowner
之前:一个 owner 元组,属于 Anne。
转移后的所有权user:beto 有一条高亮的 owner 边指向 doc:readme。user:anne 没有边。user:anneuser:betodoc:readmeowner
之后:一个 owner 元组,属于 Beto。两处变更要么一起提交,要么都不提交。

注意,所有由所有权派生的东西(edit、view)都随这一个元组一起转移。Anne 仍保留她通过其他路径获得的访问权,例如直接的 viewer 元组或某个组;如果转移应当移除 Anne 的全部访问权,就还得删除那些元组。

来源