跳转到主要内容

概览

protocol: saml 使网关成为 SAML 2.0 服务提供商,而不是 OIDC 客户端。会话、用户路径、组映射、退出登录和登录事件的行为与 OIDC SSO 中的描述完全一致;变化的只是证明一次登录的方式。
  • 每个网关只使用一种协议和一个身份提供商。 使用 protocol: saml 时,OIDC 客户端设置(issuer_url、client_id、client_secret、redirect_url)在 YAML 和环境变量中都不得设置。使用 protocol: oidc 时,任何 saml 设置都不得设置。否则启动会中止。
  • 切换协议会改变每一个主体 ID。 请求日志条目中存储的 ID 由协议、身份提供商和主体推导而来,因此同一个人在切换后会以新的主体出现。
SAML 除 sso 外还需要 saml 授权。与所有已启用的 SSO 配置一样,它采用失败即拒绝(fail closed)策略:缺少任一授权或配置无效时,启动会中止。网关绝不会回退到 OIDC,也不会回退到未受保护的控制台。

配置 SAML

使用环境变量的等效配置,环境变量会覆盖 YAML 中的值:
身份与准入中的共享设置含义不变。

注册网关

网关提供两个 URL,二者都位于已配置的 BASE_PATH 之下:
1

在身份提供商处创建 SAML 2.0 应用

如果提供商支持且网关已在运行,请导入服务提供商元数据 URL。否则请手动填写使用 HTTP-POST 绑定的 ACS URL 和实体 ID(受众)。
2

对断言签名

断言本身必须使用 RSA-SHA256 或更强的算法以及至少 2048 位的 RSA 密钥签名。仅对响应签名是不够的。不要加密断言。网关通过 HTTP-Redirect 发送未签名的请求。
3

发送稳定的主体和所用的属性

请使用持久(persistent)NameID,或将不可变的用户 ID 作为属性发送,并在 principal_attribute 中指定它。请发放用于用户路径的属性;如果使用 admin_groups 或组映射,还需发放组属性,并且只包含网关需要的组。
4

向网关提供身份提供商元数据

设置 idp_metadata_url,或下载元数据并设置 idp_metadata_file。元数据必须只描述一个身份提供商,并包含一个 HTTP-Redirect 登录端点和至少一个签名证书。
5

启动网关并登录

打开 BASE_PATH(如有)下的 /sso/login。如果登录失败,请在登录被拒绝的原因中查找原因。
这些步骤使用通用的 SAML 2.0 术语;不同身份提供商的设置名称各不相同。SAML 登录目前仅在测试用身份提供商上验证过,因此请把与您的提供商的首次上线视为需要测试的集成,而不是经过验证的现成方案。

属性与主体

user_path_claim 和 groups_claim 指定 SAML 属性,既可以直接使用属性的 Name,也可以通过 saml.attributes 中的别名:
  • 别名会遮蔽同名的 SAML 属性。
  • 用户路径属性必须恰好有一个值;其首尾空白会被去除。组的值不去除空白,按发送时的原样精确比较。只有一个空值的组属性表示没有组;在设置了 admin_groups 或组映射时,含有非文本值的组属性会使登录以 claim_mapping_failed 被拒绝。
  • 在设置了 admin_groups 或组映射时,没有组属性、而是携带 Entra ID 的 http://schemas.microsoft.com/claims/groups.link(对属于 150 个以上组的人发送)的断言会以 groups_overage 被拒绝。参见限制。
  • 修改 protocol,或修改 user_path_claim、groups_claim 通过 saml.attributes 对应的属性,会结束现有会话,详见配置变更时。
  • allowed_domains 和默认的 user_path_claim: email 读取名为 email 或别名为 email 的属性。只有在使用 user_path_claim: email 或 user_path_case_insensitive: true 时,用户路径才会被转换为小写。
  • 主体是 NameID;如果设置了 principal_attribute,则为该属性。临时(transient)NameID 每次登录都会变化,除非设置了 principal_attribute,否则会被拒绝。

邮箱信任

trust_email 决定邮箱属性是否被视为已验证的邮箱。它默认为 false,因为 SAML 没有与 OIDC 的 email_verified 对应的机制:签名只能证明身份提供商发送了该地址,不能证明它验证过该地址。用户路径同时也是会话的访问作用域,因此如果用户可以在身份提供商处修改自己的邮箱,某个人就可以填入同事的地址,并以该同事的路径登录。 未设置 trust_email 时,启动会拒绝依赖邮箱的配置:
  • 读取邮箱的 user_path_claim,其中包括默认的 user_path_claim: email;
  • allowed_domains;
  • 在设置了 admin_groups 或组映射时,读取邮箱的 groups_claim。
因此请从以下方式中选择一种:
启动检查只识别名称:email、别名为 email 的属性,以及常见的邮箱属性 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress、http://schemas.xmlsoap.org/claims/EmailAddress、mail、email、EmailAddress、User.Email、urn:oid:0.9.2342.19200300.100.1.3 和 urn:oid:1.2.840.113549.1.9.1,无论直接指定还是通过别名,比较时都不区分大小写。以其他名称携带邮箱或任何其他用户可修改的值的属性,可以通过检查。切勿将用户可以修改的属性用于 user_path_claim 或 groups_claim。

每个响应的校验内容

只有同时满足以下所有条件,登录才会成功。每一种失败都有各自的拒绝原因。
  • 它是对此浏览器发起的登录的应答。 已签名的事务 Cookie(有效期 10 分钟)、RelayState 和 InResponseTo 必须匹配。
  • 它是发给此网关的。 Destination 和 Recipient 等于 acs_url,受众是网关的实体 ID。
  • 它来自已配置的身份提供商。 签发者是元数据中的实体 ID。
  • 断言本身已签名,使用元数据中当前有效的签名证书、RSA-SHA256 或更强的算法以及至少 2048 位的密钥。签名的 KeyInfo 携带证书时必须使用该证书;没有 KeyInfo 的签名会依次用每个受信任证书校验,与证书轮换期间一样。
  • 恰好有一个断言,且未加密。
  • 它处于有效期窗口内,允许 60 秒的时钟偏差。
  • 身份提供商报告成功。
  • 它指明了稳定的主体:非临时的 NameID 或 principal_attribute。
  • 它此前未被使用过。 参见重放保护。
  • 它是体积小且简单的 XML:表单不超过 1 MiB,XML 元素不超过 900 个,不含 DTD、注释或处理指令。
登录使用的每一个断言值(主体、属性,以及受众和有效期窗口等条件)都按断言签名所校验的内容读取,绝不会从文档的其余部分读取。部分检查会将断言签名之外的值与网关的预期进行比较:RelayState 是提交表单中的字段,响应的 Destination、InResponseTo、Issuer 和状态属于响应外层,只有当身份提供商同时对响应签名时才受签名保护。这些值都不会被用作身份。随后的准入规则与 OIDC 相同。

身份提供商元数据

来自文件。 文件只读取一次。无法读取或无效的文件会使启动中止;身份提供商轮换签名证书后,必须替换该文件并重启网关。 来自 URL。 网关在启动时获取元数据,之后每隔 metadata_refresh_interval 再次获取,因此在该 URL 发布的证书轮换无需重启即可生效。刷新失败时会保留最近一次有效的元数据。如果启动时 URL 不可达,网关仍会启动,登录返回 503 和 identity_provider_unavailable,并在后台重试获取(5 秒起,每次翻倍,最长 5 分钟)。设置 require_discovery: true(PRO_SSO_REQUIRE_DISCOVERY=true)可将这种情况改为启动错误。 无论来自哪种来源,元数据在其 validUntil 之后都不再使用;此后登录不可用,直到加载了更新的元数据。

刷新可以改变什么

刷新可以替换签名证书、登录 URL 和 validUntil。它不能改变身份提供商的实体 ID:这样的元数据会被拒绝,当前元数据继续使用,并记录一条错误日志。如需切换到另一个实体 ID,请重启网关。 控制元数据 URL 的人可以发布自己的签名证书。因此,每次改变受信任证书的刷新都会以警告级别记录,并在 added_fingerprints 和 removed_fingerprints 中给出 SHA-256 指纹:
请针对这一行日志设置告警。启动时会记录网关信任的指纹。

证书固定

要阻止证书轮换被自动接受,请列出身份提供商签名证书的 SHA-256 指纹:
指纹为十六进制,不区分大小写,冒号可选。无论使用元数据文件还是 URL,都只信任列出的证书。不包含其中任何证书的元数据会使启动中止;在刷新时则会被拒绝,并继续使用最近一次有效的元数据。 轮换时,请在身份提供商切换之前添加新指纹,并在之后移除旧指纹。每一步都需要重启。

会话与退出登录

会话在 session_ttl 到期时结束;如果断言的 SessionNotOnOrAfter 更早,则在该时间结束。SessionNotOnOrAfter 已过的断言会被拒绝。 退出登录会结束 GoModel 会话,并在设置了 provider_logout_url 时重定向到该地址,与 OIDC 相同;参见跨副本退出登录。

重放保护

每个断言只会被接受一次。网关会在内存和已配置的存储后端中记住已使用断言的 ID,直到断言过期。
  • PostgreSQL 或 MongoDB: 重放的断言会在共享该存储的每个副本上被拒绝。在同一瞬间收到同一断言的两个副本可能都会接受它;这还需要该用户的事务 Cookie。
  • SQLite(默认): 保护仅限于单个实例。与退出登录一样,请只运行一个副本;网关会在启动时记录一条警告。
  • 存储不可用: 登录会以 replay_check_unavailable 被拒绝。

限制

  • 每人约 850 个组。 每个组值是一个 XML 元素,而超过 900 个元素的响应会以 too_many_elements 被拒绝。该上限不可配置。请在身份提供商处进行过滤:只发送分配给应用的组,或 admin_groups 和 group_mappings 中指定的组。
  • Entra ID:一个断言中最多 150 个组。 超过时,Entra ID 会发送 http://schemas.microsoft.com/claims/groups.link 而不是组;在设置了 admin_groups 或组映射时,登录会以 groups_overage 被拒绝。请只发送分配给应用的组。
  • 不支持在身份提供商处发起的登录。 登录必须从网关(BASE_PATH 下的 /sso/login)开始。未经请求的响应会被拒绝。
  • 不支持加密断言。 它们会以 encrypted_assertion 被拒绝。
  • 不支持 SAML 单点登出。 网关不发送 SAML 登出请求,也不处理来自身份提供商的登出请求。退出登录会结束 GoModel 会话;身份提供商的会话只能通过重定向到 provider_logout_url 结束。
  • 每个网关一个身份提供商。
最后修改于 2026年11月18日