教育联合身份：openDesk Edu 与 DFN-AAI 联合体

愿景： 任何德国大学的学生只需登录一次本地学习平台——就能跨机构访问协作工具、文件存储和视频会议，无需第二个密码。

现实： 联合体很困难。SAML 元数据、eduGAIN 属性映射、SP 注册、证书管理——每个机构都在重复造轮子。

行动号召： 让我们共同建立一个共享的 DFN-AAI 评估实例。一套联合体配置，由多人测试和记录。为社区中的每个机构降低门槛。

DFN-AAI 联合体

DFN-AAI（德国研究网络——认证与授权基础设施）是德国的国家学术身份联合体，通过 SAML 2.0 连接大学、研究机构和服务提供商。它是全球 eduGAIN 互联合体的一部分，这意味着 DFN-AAI 登录可以认证全球参与机构的用户。

对于 openDesk Edu，DFN-AAI 集成不是可选的——它是一个核心需求。德国大学不会为每个平台创建单独的用户帐户。它们通过向 DFN-AAI 注册并与 eduGAIN 联合的机构身份提供商（IdP）进行认证。

没有 DFN-AAI 支持，openDesk Edu 将成为一个孤岛。有了它，它就成为国家研究和教育基础设施的一部分。

我们构建了什么

在 v1.1 发布路线图的第 5 个 Sprint（2026 年 7 月）中，我们为 openDesk Edu 实现了全面的 DFN-AAI 联合体支持。以下是交付成果：

1. Keycloak 作为 SAML 服务提供商代理

核心架构决策：Keycloak 同时充当 SAML SP（面向 DFN-AAI）和 OIDC IdP（面向 openDesk 服务）。 这意味着：

• 外部世界看到一个 SAML SP 实体——简洁、简单、标准
• 内部服务继续使用 OIDC——无需为每个服务配置 SAML
• 属性翻译在一个地方完成——SAML eduGAIN 属性 → OIDC 声明
• 反向通道注销从 DFN-AAI → Keycloak → 套件中的所有服务传播

┌──────────────┐     SAML 2.0     ┌──────────────┐     OIDC      ┌──────────────┐
│  DFN-AAI IdP │◄────────────────►│   Keycloak   │◄────────────►│ openDesk     │
│ (Shibboleth) │    (eduGAIN)     │  (SAML SP)   │   (声明)      │ 服务         │
└──────────────┘                  └──────────────┘               └──────────────┘

2. eduGAIN 属性映射

eduGAIN 定义了一套 IdP 发布关于其用户的标准属性。我们将这些映射到 Keycloak 用户属性和 OIDC 声明：

5 个必需属性（DFN-AAI 注册必需）：

eduGAIN 属性	描述	映射到
eduPersonPrincipalName	唯一用户标识符	eppn
mail	电子邮件地址	email
displayName	完整显示名称	name
givenName	名字	firstName
sn	姓氏	lastName

5 个推荐属性：

eduGAIN 属性	描述	映射到
eduPersonAffiliation	角色（学生/员工/教师）	affiliation
eduPersonScopedAffiliation	带范围的从属关系	scopedAffiliation
eduPersonEntitlement	权限 URN	entitlement
preferredLanguage	语言偏好	locale
schacHomeOrganization	所属机构域名	organization

属性映射是关键路径。如果属性未正确传递，用户将无法认证、角色无法分配、个性化失败。我们记录了每个映射器及其 SAML 属性名称格式（urn:oasis:names:tc:SAML:2.0:attrname-format:uri vs basic），以消除猜测。

3. 服务提供商元数据生成

我们创建了一个元数据生成工作流，生成 DFN-AAI 注册所需的 SAML SP 元数据 XML：

# 生成 SP 元数据
./scripts/generate-saml-metadata.sh \
  --entity-id "urn:auth:opendesk:edu:yourdomain" \
  --acs-url "https://keycloak.yourdomain.de/realms/opendesk/broker/dfn-aai/endpoint" \
  --cert-file /etc/ssl/certs/saml-signing.crt

# 验证元数据
xmllint --valid --noout sp-metadata.xml

4. 测试与故障排除

我们记录了完整的测试工作流程——从测试 IdP 帐户到属性验证再到单点注销传播——涵盖 DFN-AAI 测试联合体环境的测试指南：

环境	元数据来源	注册时间
测试联合体	DFN-AAI 测试联合体：https://www.aai.dfn.de/fileadmin/metadata/DFN-AAI-Test-metadata.xml	1-2 个工作日
生产联合体	您机构的 DFN-AAI 管理员	3-5 个工作日

5. 完整文档套件

DFN-AAI 工作产生了六份文档文件，总计约 4,000 行，涵盖联合体架构、Keycloak 集成、注册、测试、故障排查和生产部署。

挑战：每个机构都在重复造轮子

问题在于：每所想要部署 openDesk Edu（或任何兼容 SAML 平台）的大学都需要：

1. 联系 DFN-AAI 进行联合体注册（1-2 周行政流程）
2. 为其特定部署生成 SAML 元数据
3. 通过其机构 PKI 配置证书签名
4. 与其机构 IdP 管理员协调属性发布
5. 测试完整流程——认证、属性映射、注销传播
6. 独立调试当出现问题时

对于单个机构来说，这是可管理的。但对于 10、20 或 50 个机构来说，重复程度令人震惊。 每个团队都要调试相同的 SAML 错误。每个团队都要搞清楚相同的属性映射。每个团队都要经历相同的 1-2 周注册等待。

更糟糕的是：没有共享的评估环境。 如果您是评估 openDesk Edu 的大学，您无法在不经过完整注册流程的情况下"简单测试"DFN-AAI 集成。您需要一个生产级的 SAML SP，在 DFN-AAI 注册，配备合适的证书和元数据——仅仅是为了决定平台是否适合您。

这就是我们需要共同解决的瓶颈。

行动号召：共享的 DFN-AAI 评估实例

以下是建议：让我们建立一个共享的 DFN-AAI 评估实例，任何社区成员都可以用它来测试联合体集成。

它将是什么

一个由社区管理的单一 Keycloak 实例，配置为 DFN-AAI SAML 服务提供商，在 DFN-AAI 测试联合体中注册，可供多个项目用于评估目的：

┌─────────────────────────────────────────────────────┐
│           共享评估实例                                │
│                                                      │
│  Keycloak (SAML SP) ───── 在 DFN-AAI 注册            │
│       │                                              │
│       ├── Realm: opendesk-eval    (openDesk Edu)     │
│       ├── Realm: lms-eval         (其他 LMS)          │
│       ├── Realm: collab-eval      (协作)             │
│       └── Realm: your-project     (您的项目)          │
│                                                      │
│  共享 SAML 元数据：eval.sp.opendesk-edu.org            │
│  共享证书：社区管理的 PKI                              │
│  共享文档：经过多人实战检验                             │
└─────────────────────────────────────────────────────┘

为什么重要

• 降低评估门槛——无需等待 2 周的注册即可测试联合体集成
• 共享调试知识——当一个社区成员解决 SAML 问题时，所有人受益
• 标准化属性映射——一个经过验证的 eduGAIN 映射器配置，由多个机构验证
• 提供参考实现——"它在共享评估实例上能工作"成为基准
• 加速采购流程——在承诺完整注册流程之前进行评估

如何运作

共享实例将：

1. 轻量级——运行 Keycloak 的单个 VM 或 Kubernetes Pod，在 DFN-AAI 测试联合体中注册
2. 多租户——每个社区项目获得自己独立的 Keycloak realm 进行隔离测试
3. 社区管理——配置和证书公开管理，每次更改都有文档记录
4. 有文档——每个属性映射器、每个端点、每次证书轮换都有记录
5. 默认临时——Realm 仅用于评估；生产部署仍需适当注册

我们需要社区的什么

这只有作为社区努力才能实现。以下是需要的内容：

角色	您贡献什么
基础设施托管	小型 VM 或容器主机（2 CPU，4 GB 内存）——可每月轮换
DFN-AAI 联络人	有现有 DFN-AAI 注册并能注册共享 SP 的人
证书管理员	生成和轮换 SAML 签名证书
测试人员	连接您的 SP 配置并验证属性映射
文档撰写者	记录有效的配置、常见错误和解决方案
用户	使用真实的机构 IdP 凭据进行测试（任何 DFN-AAI 成员）

入门指南

如果您有兴趣贡献或使用共享的 DFN-AAI 评估实例：

1. 开启 GitHub 讨论——让我们评估兴趣并协调：github.com/opendesk-edu/opendesk-edu/discussions
2. 查看 DFN-AAI 文档——了解需要什么：docs/dfn-aai-federation.md
3. 使用现有指南测试——验证我们的 Keycloak 配置是否适用于您的 IdP
4. 分享您的经验——您的机构发布哪些属性？您遇到了哪些错误？您发现了哪些配置特点？

我们已经做了什么

基础已经到位：

• 完整的 Keycloak SAML SP/IdP 配置文档化和审查
• 10 个 eduGAIN 属性映射器（5 个必需 + 5 个推荐）记录了精确的 SAML 属性名称格式
• 带证书支持的 SP 元数据生成脚本
• DFN-AAI 测试联合体的测试指南
• 6 份文档文件（约 4,000 行）涵盖联合体、注册、集成、测试、故障排查和生产部署
• 为所有 openDesk Edu 服务配置的反向通道注销——端到端注销传播正常工作

缺少的是共享基础设施。这正是我们需要您的地方。

下一个机遇：通过 DFN-AAI 实现统一登录

共享评估实例降低了尝试联合体的门槛。但更大的目标是统一登录：通过 DFN-AAI 获得一个联合身份，无需第二密码即可打开每个 openDesk Edu 服务——并通过 eduGAIN 打开合作机构的服务。如今每个服务都位于 Keycloak 客户端之后；同一个 Keycloak 实例已作为 SAML 服务提供商接入 DFN-AAI。剩下的缺口是在联合体边界翻译和路由身份的协议代理。

这个代理就是 SATOSA——由 IdentityPython 维护的 refeds 代理概念的参考实现。SATOSA 位于 Keycloak 之前（或旁边），提供：

• 协议翻译 —— 从任何 DFN-AAI/eduGAIN IdP 的 SAML 2.0 → 供 Keycloak 和 openDesk 服务使用的 OIDC 声明
• 多 IdP 路由（发现） —— 将每个用户路由到其所在机构的 IdP，而非硬编码的单一端点
• 属性归一化 —— 将 200 多所机构各不相同的 eduPerson* 发布内容归一化为一个标准集合
• 注销传播 —— 让单点注销多穿过一跳代理，同时不破坏背信道注销

为什么值得

现在（Keycloak 作为 SAML SP）	使用 SATOSA 代理
单一硬编码的 DFN-AAI IdP	通过发现服务路由到任何联合 IdP
eduGAIN 属性按客户端映射	属性集中归一化一次
边缘仅支持 SAML	SAML 和 OIDC IdP 可互操作
适合单个机构	适合共享/跨机构部署

代价是什么

通过 SATOSA 实现统一登录不是一个小插件——它是一个需要严格测试的真正实现项目：

1. 为 SATOSA 编写 Helm chart —— 该代理目前作为裸 Python 服务（gunicorn/uwsgi）运行；我们需要在 helmfile 结构中提供生产就绪的 chart
2. SAML↔OIDC 翻译 —— 在真实 DFN-AAI 元数据下正确处理断言消费、声明签发和 audience/ACS 处理
3. 发现服务 —— 兼容机构 cookie/IdP 偏好的"您来自哪里"路由
4. 属性归一化 —— 针对真实机构实际发布的异构属性进行测试，而不只是文档中的 5+5
5. 端到端注销 —— 验证 SLO 能经受额外一跳代理，覆盖所有服务
6. 安全审查 —— 身份路径中的代理是极具价值的攻击面；必须审查签名、加密和元数据卫生

这些都不能靠良好意愿偷工减料——联合体 bug 只有在真实 IdP 面前才会暴露。这正是共享评估实例和 DFN-AAI 测试联合体成为构建和加固该功能的正确场所的原因。

我们已有的成果降低了风险

Sprint 5 打下的基础正是 SATOSA 可以接入的部分：

• Keycloak 作为 SAML SP 代理——SATOSA 将前置的代理模式，已记录并审查
• 10 个 eduGAIN 属性映射器（5 个必需 + 5 个推荐），带有精确的 SAML 属性名称格式
• Shibboleth IdP 集成模式（适用于已运行自有 IdP 的大学）
• SP 元数据生成脚本（scripts/dfn-aai-setup/、scripts/saml-metadata-generator/）
• 双语测试联合体指南 + 超过 1,000 行的故障排查手册
• 带有 SAML 断言 fixture 的元数据生成集成测试

缺少的是 SATOSA 代理本身、它的 Helm chart 以及上述测试方案。路线图目前将其置于 v5.0（联合体与多租户） 之下——有了共享评估实例作为试验场，我们可以将其提前。

联合体是团队运动

openDesk Edu 项目建立在教育技术应主权、协作和开放的原则之上。DFN-AAI 联合体体现了所有三点：

• 主权——机构控制自己的身份基础设施
• 协作——联合体连接机构，而不是隔离它们
• 开放——SAML 2.0 和 eduGAIN 是开放标准，不是专有协议

共享评估实例将这一理念延伸到评估过程本身。每个机构不必独自攀登同一座山，我们共同开辟道路——而每个后来者都受益于我们清理出的路径。

加入我们。针对共享实例测试您的联合体设置。贡献您的发现。帮助建设每个机构都需要的评估基础设施。

---

DFN-AAI 联合体工作是 openDesk Edu v1.1 版本的一部分。所有文档可在 openDesk Edu 仓库 中找到。关于共享评估计划的疑问，请开启 GitHub 讨论或联系社区。

openDesk Edu：主权、集成、可投入生产的开源教育技术。