schema 是授权系统中变化最少、而一旦变化就最容易出问题的部分。在论文中它是命名空间配置:“A namespace configuration specifies its relations as well as its storage parameters”(命名空间配置指定其关系以及存储参数)(§2.3)。Google 有 “more than 1,500 namespaces”(1,500 多个命名空间),其配置文件 “range from tens of lines to thousands of lines, with the median near 500 lines”(从几十行到几千行不等,中位数接近 500 行)(§4)。本页涵盖三件事:论文如何防止一次配置变更把一个请求一分为二,当今的产品如何让你分步移除一个关系,以及如何在上线之前测试模型。
关系配置本身(_this、computed_userset、tuple_to_userset)在关系元组与用户集中解释。本页讨论的是如何修改它们。
论文如何对命名空间配置进行版本管理
配置存放在自己的 Spanner 数据库中:“There is one database to store relation tuples for each client namespace, one database to hold all namespace configurations, and one changelog database shared across all namespaces”(每个客户端命名空间有一个存储关系元组的数据库,有一个存放所有命名空间配置的数据库,还有一个在所有命名空间之间共享的变更日志数据库)(§3)。配置数据库由一张表加一份日志组成:
因此,每个配置版本都有一个提交时间戳,每台服务器都持有某个范围的版本。危险在于会扇出的请求(见架构):如果接收请求的服务器已经加载了新配置,而它委托的服务器还没有,同一次 Check 的两半就会在不同的规则下被评估。论文排除了这种情况:“Zanzibar chooses a single snapshot timestamp for config metadata when evaluating each client request. All aclservers in a cluster use that same timestamp for the same request, including for any subrequests that fan out from the original client request”(Zanzibar 在评估每个客户端请求时,为配置元数据选择单一的快照时间戳。集群中的所有 aclservers 对同一请求都使用相同的时间戳,包括从原始客户端请求扇出的所有子请求)(§3.2.2)。
当集群中的服务器加载了不同的配置版本时,一个请求可以使用哪个时间戳?
注意,新配置并不是一提交就被使用。只有当集群中的每台服务器都能使用它时,它才变得可用。用论文的话说,“each server in a cluster may have access to a different range of config timestamps due to restarts or network latency. Zanzibar must pick a timestamp that is available across all of them. To facilitate this, a monitoring job tracks the timestamp range available to every server and aggregates them, reporting a globally available range to every other server. On each incoming request the server picks a time from this range, ensuring that all servers can continue serving even if they are no longer able to read from the config storage”(由于重启或网络延迟,集群中的每台服务器可访问的配置时间戳范围可能各不相同。Zanzibar 必须选择一个在所有服务器上都可用的时间戳。为此,一个监控作业跟踪每台服务器可用的时间戳范围并加以汇总,向所有其他服务器报告一个全局可用的范围。对于每个到来的请求,服务器从该范围中选择一个时间,从而确保即使服务器无法再从配置存储中读取,所有服务器也都能继续提供服务)(§3.2.2)。
论文到此为止。它没有说明客户端在移除一个关系时如何迁移元组,配置写入是否会对照现有元组进行检查,也没有说明配置时间戳与为同一请求选择的元组快照之间是什么关系。它只说 ⟨namespace⟩ 和 ⟨relation⟩ “are predefined in client configurations”(在客户端配置中预先定义)(§2.1),以及关系是每个元组主键的一部分(§2.1、§3.1.1)。本页的其余部分讨论开源系统如何处理这一缺口。
两个产品中的 schema 版本
文档最完善的两个产品作出了不同的选择。
- SpiceDB 每个部署只有一个当前 schema,用
WriteSchema替换。AuthZed 的文档说 SpiceDB “processes all calls to the WriteSchema in a safe manner: it is not possible to break the type safety of a schema”(以安全的方式处理所有 WriteSchema 调用:不可能破坏 schema 的类型安全),这意味着 “it is not possible to accidentally remove a relation that is still referenced by one or more relationships”(不可能意外移除仍被一个或多个关系引用的关系)(migrating a schema)。AuthZed 2022 年的一篇文章补充说,schema 写入是完全一致的,因此 schema 写入之后的关系写入会按新 schema 评估(online schema migrations)。 - OpenFGA 保留每一个版本。“Authorization Models in OpenFGA are immutable, they are created once and then can no longer be deleted or modified. Each time you write an authorization model, a new version is created.”(OpenFGA 中的授权模型是不可变的,它们创建一次之后就不能再删除或修改。每次写入授权模型,都会创建一个新版本。)请求可以指定一个
authorization_model_id;不指定时,“OpenFGA will use the last created Authorization Model for that store”(OpenFGA 会使用该 store 中最后创建的授权模型)(immutable models)。文档建议在配置中固定该 ID,这也使得在切换之前可以针对新模型进行影子检查。
论文的设计介于两者之间:一份以提交时间戳为键的变更日志,类似 OpenFGA 的版本历史,但服务器总是移向最新版本,类似 SpiceDB。各产品的更多信息:SpiceDB、OpenFGA。
移除一个关系需要三步
添加很容易。在 SpiceDB 中,“Adding a new relation to a definition is always allowed, as it cannot change any existing types or computation”(向 definition 添加一个新的 relation 总是允许的,因为它不会改变任何现有的类型或计算),而修改权限的计算方式也是允许的,只要它引用的是已定义的关系或权限(migrating a schema)。
移除则不然。同一页面写道:“For type safety reasons, any removal of a relation with data, or a relation or permission referenced by another relation or permission is disallowed.”(出于类型安全的原因,不允许移除任何带有数据的 relation,也不允许移除被另一个 relation 或 permission 引用的 relation 或 permission。)一个关系只有在其元组消失后才能移除,而其元组只有在没有任何东西再根据它们计算访问权之后才能安全地移除。因此移除是有顺序的。
以贯穿示例中的 doc 为例,假设它有一个额外的关系 editor,团队想去掉它。用 SpiceDB 的 schema 语言,它起初是这样的:
definition doc {
relation parent: folder
relation owner: user
relation editor: user
relation viewer: user | group#member
permission view = owner + editor + viewer + parent->view
}
每一步改变了什么,为什么每一步都不能跳过?
注意访问权实际改变的位置:在第 1 步,而不是第 3 步。一旦权限不再读取 editor,一个不同时是所有者或查看者的编辑者就会被拒绝,而此时元组仍然在磁盘上。这正是应该停下来观察的时机。AuthZed 的文章对步骤的编号不同,它谈到在删除任何数据之前的这一状态时说:“You can stay at step 2 for as long as desired, in production, to retain your ability to roll back the change”(你可以在生产环境中按需在第 2 步停留任意长的时间,以保留回滚该变更的能力)(online schema migrations):回滚第 1 步是一次 schema 写入,而回滚第 2 步意味着恢复元组。这三个步骤来自 AuthZed 的迁移文档,文档还描述了从关系中移除一种允许的主体类型时的相同模式(先删除那些关系数据,再编辑 schema)。
重命名一个关系就是一次移除加一次添加。SpiceDB 的文档详细讲解了这一过程:添加新关系并把它纳入权限,让应用同时写入两者,回填数据,从权限中去掉旧关系,停止写入旧关系,然后用上面的三个步骤移除它(migrating a schema)。OpenFGA 完成同样工作的方式依赖于不可变模型:写入新模型(一个生产环境尚未使用的新 ID),更新应用,把元组复制到新的关系名下,然后部署指向新模型 ID 的应用(immutable models)。
用断言文件测试模型
两个产品都读取一个 YAML 文件,其中包含一个模型、一些元组以及你期望的答案。下面的示例编码了贯穿示例(Anne 拥有 readme;Beto 属于 eng;eng 的成员可以查看 readme;Chen 可以查看文件夹 A)。它们遵循各产品文档中的格式,但是专为本页编写的,没有运行过。
OpenFGA:.fga.yaml
.fga.yaml 文件包含一个 model(或 model_file)、可选的 tuples 以及 tests;一个测试可以包含 check、list_objects 和 list_users 块,每个块都带有 assertions(testing models)。
name: Running example
model: |
model
schema 1.1
type user
type group
relations
define member: [user]
type folder
relations
define viewer: [user]
type doc
relations
define parent: [folder]
define owner: [user]
define viewer: [user, group#member] or owner or viewer from parent
tuples:
- user: user:anne
relation: owner
object: doc:readme
- user: user:beto
relation: member
object: group:eng
- user: group:eng#member
relation: viewer
object: doc:readme
- user: folder:A
relation: parent
object: doc:readme
- user: user:chen
relation: viewer
object: folder:A
tests:
- name: readme access
check:
- user: user:anne
object: doc:readme
assertions:
owner: true
viewer: true
- user: user:chen
object: doc:readme
assertions:
owner: false
viewer: true
list_objects:
- user: user:beto
type: doc
assertions:
viewer:
- doc:readme
OpenFGA CLI 用 fga model test --tests <filename>.fga.yaml 运行它,并按测试种类分别打印通过数(testing models)。
SpiceDB:验证文件
SpiceDB 验证文件包含一个 schema(或 schemaFile)、作为单个多行字符串而非 YAML 列表的 relationships、带有 assertTrue 和 assertFalse 的 assertions,以及一个可选的 validation 块,即预期关系,列出每个拥有访问权的主体及其获得途径(validation, testing, debugging)。
schema: |-
definition user {}
definition group {
relation member: user
}
definition folder {
relation viewer: user
permission view = viewer
}
definition doc {
relation parent: folder
relation owner: user
relation viewer: user | group#member
permission view = owner + viewer + parent->view
}
relationships: |-
doc:readme#owner@user:anne
group:eng#member@user:beto
doc:readme#viewer@group:eng#member
doc:readme#parent@folder:A
folder:A#viewer@user:chen
assertions:
assertTrue:
- doc:readme#view@user:anne
- doc:readme#view@user:beto
- doc:readme#view@user:chen
assertFalse:
- doc:readme#owner@user:chen
zed validate 运行它时 “using the same parsing logic that the SpiceDB binary uses”(使用与 SpiceDB 二进制文件相同的解析逻辑),并且自 zed v0.25.0 起可以一次接受多个文件(zed validate validations/*)(validation, testing, debugging)。本页省略了 validation 块,因为没有核对它对组用户集的确切输出;文档展示的形式是 "[user:you] is <document:validation-testing-debugging#reader>"。
两种文件测试的都是模型,所针对的是你编造的元组。它们是 schema 的单元测试,而不是对生产数据的检查。
在 CI 中运行它们
在从拉取请求到生产环境的过程中,每种检查各自属于哪个环节?
注意左侧的注释。AuthZed 直言:“a schema write can still fail if a relation is removed and there are still instances of that relation in your database. zed doesn’t know about your data”(如果移除了一个关系,而数据库中仍有该关系的实例,schema 写入仍然可能失败。zed 不知道你的数据)(validation, testing, debugging)。上面的三步移除是一个部署流程,而不是测试文件能够证明的东西。
两个项目都发布了 GitHub Actions。对于 SpiceDB,authzed/action-spicedb-validate 对一个文件运行 zed 的验证;AuthZed 称其 “highly recommended because it can prevent deployments of unverified changes”(强烈推荐,因为它可以阻止未经验证的变更被部署)(文档)。对于 OpenFGA,openfga/action-openfga-test 安装 CLI,并对 test_path 下每个匹配 *.fga.yaml 的文件运行 fga model test(action.yml)。同时包含两者的最小工作流:
name: Authorization model
on:
pull_request:
paths: ["authz/**"]
jobs:
spicedb:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: authzed/action-spicedb-validate@v1
with:
validationfile: authz/spicedb.yaml
openfga:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: openfga/action-openfga-test@v0.1.1
with:
test_path: authz/
对于较大的变更,SpiceDB 还提供一个集成测试服务器(spicedb serve-testing,或 authzed/action-spicedb action),它为每个预共享密钥提供 “an isolated, empty datastore”(一个隔离的空数据存储),使应用测试可以针对同一实例并行运行(文档)。OpenFGA 固定的模型 ID 使影子检查成为可能:在切换之前,把同一检查分别发给旧模型和新模型并比较结果(immutable models)。
论文章节:命名空间配置 §2.3;配置存储 §3.1.3;每个请求一个配置时间戳 §3.2.2;命名空间数量与配置大小 §4。术语见术语表。
来源
- Zanzibar 论文,§2.1、§2.3、§3、§3.1.3、§3.2.2、§4(本站的转录)
- AuthZed,Migrating a Schema in SpiceDB:authzed.com/docs/spicedb/modeling/migrating-schema
- AuthZed 博客,Online Schema Migrations in SpiceDB(2022-02-03):authzed.com/blog/online-schema-migrations
- AuthZed,Validation, Testing, Debugging SpiceDB Schemas:authzed.com/docs/spicedb/modeling/validation-testing-debugging
- OpenFGA,Testing Models:openfga.dev/docs/modeling/testing
- OpenFGA,Immutable Authorization Models:openfga.dev/docs/getting-started/immutable-models
- OpenFGA Model Testing Action,action.yml:github.com/openfga/action-openfga-test
- Carla Urrea Stabile,Continuous Authorization Testing: FGA, GitHub Actions, and CI/CD,Auth0 博客(2025-12-17):auth0.com/blog/continuous-authorization-testing-fga-github-ci-cd