打造可靠(且快速)的目录同步
摘要
Firezone 详细阐述了为何放弃业界领先的目录同步标准,转而自研专用引擎,涵盖如何从 Entra、Okta 和 Google 等身份提供方同步用户、群组和成员。文章解释了在应用侧维护组织目录副本并保持其快速与一致的设计挑战。
暂无内容
查看缓存全文
缓存时间: 2026/10/02 08:16
# 构建可靠(且快速!)的目录同步
Source: https://www.firezone.dev/blog/building-reliable-directory-sync
> “你的用户是谁?” —— 主控程序,《Tron》(1982)
如果你的应用依赖用户身份,就需要一套管理机制。通常这指的是用户账号,当有人注册时你就创建它们。
但放任员工随意注册任何感兴趣的 SaaS 应用,对管理层来说是一场噩梦。因此,组织希望能够控制哪些用户存在(或不存在)于你的应用中。
这决定了谁能登录,但他们的权限又该如何控制?
为此你需要角色,或者说**组(groups)**。它们和用户一样,都来自组织的身份提供方 —— Entra、Google、Okta 等。组构成了 Firezone 访问模型的基础,决定了谁可以访问什么。
把用户和组同步到应用中的过程,称为**目录同步(directory sync)**,而要把它做好,出乎意料地棘手。本文将介绍目录同步的确切含义、用于实现它的主流标准,以及我们为何选择完全弃用该标准、从零自建同步引擎。
## 目录同步:入门介绍 (https://www.firezone.dev/blog/building-reliable-directory-sync#directory-sync-a-gentle-primer)
组织的**目录(directory)**是"谁在这里工作、他们被允许访问什么"的清单。它存放在身份提供方中,由三部分构成:
- **用户(Users):**组织中的每一个人。每个用户都有姓名、邮箱,以及"激活"或"暂停"之类的账号状态。
- **组(Groups):**具名的用户集合,比如 `Engineering`(工程)或 `Product`(产品)。通过组,你可以一次性为许多人授权。
- **成员(Members):**谁属于哪个组。一个组的成员可以是用户,也可以是另一个组。用户所拥有的访问权限,来自他所属的每一个组 —— 无论是直接加入还是间接加入。
**目录同步**就是把这份目录复制到你的应用中,并保持它最新。身份提供方是数据源(source of truth),你的应用中保存的只是一份副本。随着时间推移,这份副本需要跟上三类变更:新增的用户和组、改名之类的更新,以及删除。当有人入职、离职或变更团队时,理想情况下你的应用应当能尽快得知。
有必要澄清一点:目录同步**不是**单点登录(SSO)。这听起来似乎显而易见,但很多人会把两者混为一谈。像 OpenID Connect 这样的主流认证标准,完全不涉及如何把用户引入应用。我们所说的目录同步,恰恰指的是引入用户(以及组)的机制,但**不**包括他们如何完成认证(关于后者,请参阅这篇文章:https://www.firezone.dev/blog/the-enterprise-identity-crisis)。
### 一个简单的例子 (https://www.firezone.dev/blog/building-reliable-directory-sync#a-simple-example)
假设你的组织拥有如下目录:
一个包含嵌套组的目录示例——目录中有两个组和两个用户。Product 组有两个成员:用户 Alice 和组 Engineering。Engineering 组有一个成员:用户 Bob。由于 Engineering 是 Product 的成员,Bob 间接地属于 Product。
| 组 / 用户 |
| --- |
| Product |
| Alice |
| Engineering |
| Bob |
在数据库中,它可能长这样:
上述目录示例的数据库表——三张表。Users 表列出 Alice 和 Bob。Groups 表列出 Product 和 Engineering。Members 表包含一个 user 列、一个 group 列和一个 parent_group 列。Alice 是 Product 中的用户;Bob 是 Engineering 中的用户;组 Engineering 位于 Product 中。每一行的第一或第二列有一列是空的,而要回答"Bob 是否在 Product 中",就需要通过递归查询沿父组一路追溯。
| Users | name |
| --- | --- |
| Alice | |
| Bob | |
| Groups | name |
| --- | --- |
| Product | |
| Engineering | |
| Members | user | group | parent_group |
| --- | --- | --- | --- |
| Alice | | Product | |
| Bob | | Engineering | |
| Engineering | | Product | |
要回答应用中"Bob 是否是 Product 的成员?"这类常见访问问题,你必须先查 Product 的成员,再查这些成员中所有组的成员,如此反复,直到找到 Bob。
为了避免这种情况,我们可以**展平(flatten)组**,为每个用户所在的每一个组(无论直接还是间接)都生成一行记录:
展平成员关系后的目录示例——三张表。Users 表列出 Alice 和 Bob。Groups 表列出 Product 和 Engineering。Members 表包含一个 user 列和一个 group 列,用户所在的每个组(直接或间接)都占一行:Alice 在 Product 中,Bob 在 Product 中,Bob 在 Engineering 中。Bob 在 Product 中,是因为 Engineering 嵌套在 Product 之内。嵌套的组不再作为独立行出现,因此询问"Bob 是否在 Product 中"只需一次查找。
| Users | name |
| --- | --- |
| Alice | |
| Bob | |
| Groups | name |
| --- | --- |
| Product | |
| Engineering | |
| Members | user | group |
| --- | --- | --- |
| Alice | Product | |
| Bob | Product | |
| Bob | Engineering | |
现在,同样的问题只需一次简单查询即可得到答案。
好,数据模型就是这样了。接下来我们需要把它从身份提供方搬进数据库,并保持它始终更新。
## SCIM (https://www.firezone.dev/blog/building-reliable-directory-sync#scim)
当然,你不必把所有这些都自己发明一遍。有一套标准就是专门用来做目录同步的,名为 [SCIM](https://datatracker.ietf.org/doc/html/rfc7644),它的自我介绍是这样写的:
> 跨域身份管理系统(System for Cross-domain Identity Management,SCIM)规范是一种基于 HTTP 的协议,通过标准化的服务,让多域场景下的身份管理更容易支持。
在实践中,这意味着你需要在**你的**应用中构建一组 REST 端点,例如:
```
GET /Users
GET /Users/{id}
POST /Users
PUT /Users/{id}
PATCH /Users/{id}
DELETE /Users/{id}
GET /Groups
GET /Groups/{id}
POST /Groups
PUT /Groups/{id}
PATCH /Groups/{id}
DELETE /Groups/{id}
```
然后由身份提供方调用这些端点,以保持目录同步。
SCIM 的承诺——四个身份提供方,Okta、JumpCloud、Entra 和 Google,都向你应用中的同一个 SCIM API 发送 SCIM 请求,由该 API 写入同一个数据库。SCIM 的承诺在于,只要一套标准 API,就能同步任意提供商。
| 身份提供方 | 你的应用 |
| --- | --- |
| Okta | SCIM API |
| JumpCloud | 数据库 |
| Entra | |
| Google | |
SCIM 的承诺:一套 API 即可同步多个提供方。
SCIM 的好处在于,身份提供方是把变更**推送(push)**给你的应用,因此从提供方发生变更到变更落地到你的应用之间,延迟可以远低于那种按计划轮询提供方的拉取(pull)方式。
听起来很美好。但问题出在哪呢?
首先,你的应用必须几乎始终处于运行状态,随时准备接收目录更新。哪怕宕机或过载短短几秒钟,你都可能错过一次关键的目录变更。而且你无法从应用侧主动触发一次全量同步,因此在身份提供方决定再次告诉你之前,这些更新就一直丢失着。
但 SCIM 更烦人的一点在于:它确实把协议(即线上数据格式)标准化得很好,却没有说明这些端点该如何调用、它们对应提供方的哪些生命周期事件,甚至没有说明每类请求里应该包含什么样的数据。
各身份提供方在**如何**实现 SCIM 上大相径庭。以下是几个例子:
- **组成员更新:**[Okta 可以](https://developer.okta.com/docs/api/openapi/okta-scim/guides/scim-20)把新增和删除合并在一次 `PATCH` 中一起发送,而 [Entra 则要求](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/entra-id-scim-api-reference#update-a-group)将它们分开,并且每次 `PATCH` 只允许移除一个成员。
- **即使是同一提供方内部的基础类型也不一致:**Entra 过去会把 `active: "False"` 作为字符串发送,而不是 SCIM 定义的布尔值,后来才[补充了](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/application-provisioning-config-problem-scim-compatibility)一个兼容性标志来切换为合规行为。
- **可选功能各不相同:**Okta 明确[不使用](https://developer.okta.com/docs/concepts/scim/faqs/#unsupported-scim-features)若干 SCIM 能力,包括批量操作、`POST` 搜索、`/ServiceProviderConfig`,以及基于 `meta.lastModified` 的过滤。
而在用户账号停用(deprovisioning)——也就是切断离职员工访问权限这一关键操作上,不一致之处更多:
- **Okta:**顺序很重要:要先取消分配用户,再移除其组成员关系,而且这些成员关系[可能会保留在下游应用中](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/app-assignments-group-push.htm)。
- **Entra:**移除组并不必然导致用户停用:如果另一个已分配的组仍然授予访问权限,他们[仍处于生效范围内](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/how-provisioning-works#assignment-based-scoping)。
- **JumpCloud:**账号停用[可以由解除应用绑定、账号暂停或删除触发](https://docs.jumpcloud.com/new/guides/user-provisioning-with-scim-and-hris/index.html)——并不仅限于从预配组中移除。
- **OneLogin:**删除用户可能触发[删除、暂停,也可能什么都不做](https://developers.onelogin.com/docs/scim/test-your-scim/),具体取决于应用的预配设置。
所有这些归结为一个事实:你最终会得到许多针对不同提供方的 SCIM 代码分支,而不是你原本期望写出的那一套统一实现。
每个身份提供方一套 SCIM 兼容垫片——四个身份提供方,Okta、JumpCloud、Entra 和 Google,各自向你的应用发送 SCIM 请求。它们全部汇集到同一个 SCIM API,这是应用侧唯一的入口。而 API 背后,应用为每个提供方都准备了独立的垫片,因为每个提供方实现 SCIM 的方式都不同,每套垫片最终写入同一个数据库。这套标准并没有消除按提供方开发的工作量,只是把它挪到了 API 背后。
| 身份提供方 | 你的应用 |
| --- | --- |
| Okta | SCIM API → Okta 垫片 |
| JumpCloud | JumpCloud 垫片 |
| Entra | Entra 垫片 |
| Google | Google 垫片 |
| | 数据库 |
SCIM 的现实:需要按提供方编写代码路径来抹平实现差异。
完全有可能,走 SCIM 这条路,你会得到一套更复杂(也更脆弱)的实现,还不如你单独拉取每个提供方 API 来构建的拉取式系统。
这正是我们所做的。
## 拉取式同步 (https://www.firezone.dev/blog/building-reliable-directory-sync#pull-based-sync)
采用拉取式同步时,由你来发起调用。你的服务器按计划(或在用户要求下)访问身份提供方的 API,遍历整个目录,并与你的数据库进行比对(reconcile)。每个提供方的 API 略有不同,但整体结构大同小异,因此大部分工作可以复用。
### 工作原理 (https://www.firezone.dev/blog/building-reliable-directory-sync#how-it-works)
身份提供方都提供了列出用户、组以及某个组成员的 API 端点。完成认证后,一个简单的同步算法可以是:
1. 获取所有组
2. 获取所有组的成员
3. 对于用户成员,获取与这些成员对应的用户记录
4. 对于组成员,回到第(2)步
5. 每 N 分钟重复一次
有几点细节需要注意:
- **分页(Pagination):**每次列表调用只返回一页结果,所以"获取全部"意味着要沿着 next-page 链接一路读取,直到没有更多内容为止。
- **稳定的 ID:**每个用户和组都有一个永不改变的 ID。匹配记录时要用这个 ID,而不是邮箱或姓名,这样改名时就是更新记录,而不是创建一条重复数据(参见[那个 Alice 问题](https://www.firezone.dev/blog/the-enterprise-identity-crisis))。
- **循环引用:**一个组可能最终包含它自身(A 属于 B,B 又属于 A)。要记住已经访问过哪些组,以免第(4)步陷入死循环。
- **展平:**这就是展平表的由来。当你发现 Product 中嵌套着 Engineering 时,Engineering 的每个成员也要在 Product 下得到一行记录。这也意味着删除操作需要重新计算,而不能直接删除,因为 Bob 可能仍然通过其他路径到达 Product。
对像我们例子这样的小型目录来说,这已经足够简单 —— 你可以遍历整个目录,先把所有数据收集起来,再一次性写入数据库。
大一些的目录就没那么轻松了。
### 同步更大的目录 (https://www.firezone.dev/blog/building-reliable-directory-sync#syncing-larger-directories)
目录越大,遍历耗时越长。而遍历时间越久,你成功把数据刷入数据库之前、中途丢失已积累状态的风险就越大。如果部署时机不巧,你就得从头再来,新目录数据进入数据库的时间也随之推迟。
为缓解这个问题,你可以为每次同步引入一个时间戳(epoch),边获取边做检查点(checkpoint),最后删除所有早于该时间戳的记录:
1. 初始化一个起始时间戳。
2. 获取一页数据,并带着该时间戳写入数据库。
3. 对剩余的各页重复第(2)步。
4. 结束时,删除所有早于起始时间戳的记录。
带检查点的全量同步——一张流程图,展示带检查点的全量同步。同步先记录其起始时间。随后依次处理三类实体。对于组:获取一页数据并带着起始时间戳写入数据库,只要还有更多页就重复此过程。对于成员:对每个组的成员做同样的事,只要还有更多组就继续。对于用户:以同样的方式逐页获取这些成员对应的用户记录。最后一条流水线完成后,删除所有早于起始时间的记录。
- 记录起始时间
- Groups(组)→ 获取一页数据 → 带时间戳写入 → 还有更多页?(是 → 循环;否 → 下一项)
- Members(成员)→ 获取某个组的成员 → 带时间戳写入 → 还有更多组?(是 → 循环;否 → 下一项)
- Users(用户)→ 获取一页数据 → 带时间戳写入 → 还有更多页?(是 → 循环;否 → 下一项)
- 删除早于起始时间的记录
带检查点的全量同步:每一页数据一到就写入,最后再统一清理。
规模并不是唯一让这件事变难的因素。随着目录增长,还会出现以下问题:
- **速率限制:**提供方 API 的速率限制可能与客户使用的其他应用共享。调用 API 太频繁,你可能会拖慢客户的其他工具。所以要按提供方要求的节奏来,一旦对方要求你退避(back off),就照做。
- **糟糕的响应:**有时 API 会返回一个看似正常的 `200`,但其中缺失了部分目录数据。如果你的同步把"缺失"当作"已删除",可能会误删大量真实用户。要为单次同步允许删除的数据量设置一个上限,或熔断器(circuit breaker),这可以避免一些严重的意外。
- **嵌套组:**各家提供方对"谁来负责展平"意见不一,有些提供方在你请求展平时返回的还是过时结果。
- **任务重叠:**如果同一个目录的两次同步同时运行,它们可能互相覆盖对方的变更。目录越大,这种情况发生的概率越高,因为上一次同步可能还在运行时,下一次就已经启动了。要确保同一时间只有一个任务在跑(使用带唯一性约束的任务队列或建议锁 advisory lock 效果很好),并且崩溃的任务不会永远阻塞下一次同步。
- **临时错误与永久错误:**超时或 `503` 应该重试。而凭据被吊销则不应该重试,因为重试只是在浪费你的配额,还会掩盖真正的问题。你的同步需要能区分这两类错误,并把后一种情况通知管理员。
### 少请求一些 (https://www.firezone.dev/blog/building-reliable-directory-sync#ask-for-less)
你获取的数据越少,同步就越快。大多数目录中都充斥着与你的应用毫无关系的内容,比如承包商、服务账号,以及用于邮件列表和办公地点的成百上千个组。
在可能的情况下,让提供方来做过滤。只请求分配给你应用的用户和组,而不是拉取全部数据。这意味着要读的页数更少、调用次数更少,同时也减轻了速率限制的压力。
你可以就此打住,带走一个已经相当健壮的目录同步引擎。但如果你像 Firezone 一样用目录来制定访问规则,就可能面临重要更新
相似文章
Unison 怒评
一位开发者将 Unison 作为轻量级替代方案进行评估,用于自托管 KeePass 数据库的同步,以取代重量级同步工具。文中详细记录了配置过程中遇到的挑战以及 Socket 模式的搭建过程。
@deepdotspace: 大多数团队为每个新应用重建相同的基础:认证、数据、存储、支付、部署……我们将这一层做得稳固。
DeepSpace 推出 Blitz,一个 SDK,标准化了常见的应用开发层,如认证、数据和存储,并发布了 30 个开源应用以展示其快速部署能力。
广义同步的局限:架构、权衡与决策因素的分类体系
本论文来自阿尔托大学,提出了同步架构的分类体系,分析了权衡与决策因素,以指导广义同步引擎的设计。
我们应得的代码锻造平台
本文讨论了对GitHub可靠性日益增长的不满,并提出基于AT协议的去中心化Git锻造平台Tangled,作为一个结合了中心化便利性与用户数据所有权的有前途的替代方案。
Active Directory 时代终于结束了
Infisical 认为,Active Directory 的时代已经结束,因为其架构无法应对现代云规模的机器身份,导致组织存在严重的安全盲区,因此需要采用新的身份认证方式。