概览
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
身份与准入中的共享设置含义不变。
注册网关
网关提供两个 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。
每个响应的校验内容
只有同时满足以下所有条件,登录才会成功。每一种失败都有各自的拒绝原因。- 它是对此浏览器发起的登录的应答。 已签名的事务 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 指纹:会话与退出登录
会话在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结束。 - 每个网关一个身份提供商。