配置 SAML 外部连接

查看 Markdown

本教程把企业身份提供方配置为 SAML 2.0 外部连接。Sudomimus 是服务提供方（SP）：它向 IdP 发送 AuthnRequest，验证 IdP 提交到 ACS 的签名 Assertion，再进入与 OIDC 联合登录相同的第一层、第二层和签发流程。

开始之前

你需要：

在 With 门户中拥有一个组织；
有权在 IdP 中创建 SAML 应用；
IdP Entity ID 和用于 SP-initiated 登录的 SSO URL；
IdP 用于签署 Assertion 的公钥 X.509 证书。

Sudomimus 只支持 SP 发起的 SAML 浏览器 SSO。初始 AuthnRequest 使用 HTTP-Redirect binding，响应必须通过 HTTP-POST binding 返回。

1. 在 IdP 创建 SAML 应用

创建一个自定义 SAML 2.0 应用，并注册以下生产环境 SP 值：

IdP 设置	值
SP Entity ID / Audience	`urn:sudomimus:production:federation-sp`
ACS / Reply URL	`https://federation.sudomimus.com/saml/acs`
发起模式	SP-initiated
Response binding	HTTP-POST
Assertion 签名	必须启用

ACS 必须精确匹配，Assertion 中的 audience 必须是上面的 SP Entity ID。配置非生产环境时，请改用该环境连接详情页显示的只读 SP Entity ID 和 ACS。

2. 配置 Subject 与资料属性

稳定的外部身份通常来自 SAML NameID。请让 NameID 在该用户的生命周期内保持稳定，并在这个 IdP 应用中唯一；不要使用可变的显示名称。

你也可以通过 SAML Attribute 释放资料值。记录每个属性的精确名称；如果 IdP 使用 URI 风格名称，也要完整记录：

建议用途	属性名称示例
邮箱	`mail`
名字	`given_name`
姓氏	`family_name`

这些只是示例，不是规定的字面量。在 With 中输入的名称必须与 Assertion 实际发送的 Attribute 名称完全一致。

IdP 提供的邮箱不会自动获得 Sudomimus 信任。只有当该连接所属组织当前持有相应邮箱域名的已验证声明时，它才能用于邮箱所有权和账户匹配。

3. 收集 IdP 配置值

从 IdP 复制：

作为 Assertion issuer 的精确 IdP Entity ID；
接收 AuthnRequest 的 HTTPS IdP SSO URL；
当前有效的 Assertion 签名证书。

请把证书导出为 PEM 编码的 X.509 公钥证书，并保留头尾：

-----BEGIN CERTIFICATE-----
MIIC...
-----END CERTIFICATE-----

不要粘贴私钥。证书轮换期间，请在重叠窗口内同时配置新旧公钥证书，确认新证书生效后再移除旧证书。

4. 在 With 中创建连接

在 With 门户中：

打开你的组织。
打开外部连接并选择新建连接。
选择 SAML 2.0。
输入显示名称、IdP Entity ID、IdP SSO URL 和签名证书。
根据需要输入精确的邮箱、名字和姓氏属性名。
创建连接。

With 门户创建的新 SAML 连接会使用 NameID 作为稳定 subject 来源。协议、IdP Entity ID 和 subject 来源共同定义凭据命名空间，之后不能修改；如需改变其中任意一项，请创建新连接。

连接详情页会再次显示权威的 SP Entity ID 和 ACS。测试之前，请将其与 IdP 中注册的值逐一比较。

5. 使用该连接

选择其中一种或同时使用：

应用级登录添加一条指向该连接的 ENTERPRISE_FEDERATION_APPLICATION_MANAGED 第一层规则。

域级强制 SSO验证域名，将该连接绑定到 SSO_ONLY，并让参与应用允许 ENTERPRISE_FEDERATION_DOMAIN_MANAGED。

协议已经由连接固定，两种第一层规则都不需要额外的 OIDC/SAML 开关。

6. 测试登录

使用一个非管理员测试用户，启动对应的应用级或域级登录流程。

确认：

浏览器把 SP 发起的 AuthnRequest 送到配置的 IdP；
IdP 把响应 POST 到精确的 ACS；
Assertion issuer、audience、recipient 和 InResponseTo 与当前流程匹配；
Assertion 包含一个 AuthnStatement 且处于有效时间窗口；
Assertion 本身由已配置证书签名，而不只是外层 Response；
第二层允许最终得到的身份。

初次协议冒烟测试可以使用 EVERYONE 第二层规则。若使用 EMAIL，要确保映射的邮箱属性存在，而且该邮箱域名已由连接所属组织验证。

Sudomimus 会拒绝重放的请求和 Assertion。浏览器看到的错误会被刻意保持为通用信息，因此排查配置时应先查看 IdP 的 SAML Response 检查工具，并逐项核对上面的清单。

不支持的设置

不要启用 IdP-initiated SSO、加密 Assertion、Single Logout、Artifact Binding、Metadata Import、Requested Authentication Context Policy 或签名 AuthnRequest。当前不会接受这些 profile。