后端认证鉴权单点登录【免费下载链接】casApereo CAS - Identity Single Sign On for all earthlings and beyond.项目地址https://gitcode.com/gh_mirrors/ca/cas点击查看免费下载在 Apereo CAS 作为 SAML2 IdP身份提供方的部署中saml2:NameID是断言中用于标识本次认证用户的核心元素其取值与格式往往直接决定服务提供方SP能否正确识别用户。本文基于 CAS 官方文档 SAML2 NameID Selection 的完整配置示例结合 CAS 源码中 NameID 构建与用户名解析的实际实现路径讲清楚两件事如何为某个已注册的 SAML 服务指定所需的 NameID 格式requiredNameIdFormat以及如何控制 NameID 的最终取值usernameAttributeProvider并覆盖 email、unspecified、transient、persistent 四种典型格式的完整可运行服务定义。核心概念格式与取值是两条独立的配置线每个 SAML 服务SamlRegisteredService可以单独指定一个所需的 NameID 格式required Name ID format。如果未定义CAS 会去查阅 SP 元数据metadata中声明的受支持格式来选定。另一方面NameID 的值始终是认证后的用户名——如果你已经为该服务配置了特定的属性作为返回给该服务的认证用户标识即 PrincipalId 的定制发布参考 CAS 属性发布与 PrincipalId 定制那么该属性值就会连同正确的格式一起用于构造 NameID。从源码结构看这套逻辑集中在 SamlProfileSamlNameIdBuilder 中getSupportedNameIdFormats先从元数据适配器context.getAdaptor().getSupportedNameIdFormats()收集 SP 声明支持的格式若元数据为空则回退使用urn:oasis:names:tc:SAML:2.0:nameid-format:transient作为默认若注册服务上配置了requiredNameIdFormat该格式会被addFirst插入到受支持格式列表的最前面从而优先选用getRequiredNameIdFormatIfAny还会读取 AuthnRequest 中NameIDPolicy声明的格式若该格式不在受支持列表中CAS 会记录告警日志提示请求的格式可能不会被满足并列出元数据中的实际支持集合最终通过SamlAttributeBasedNameIdGenerator按所选格式对用户名进行编码。这意味着服务定义上的requiredNameIdFormat具有强制覆盖语义它排在元数据格式之前被评估第一个能成功编码出 NameID 的格式即胜出。requiredNameIdFormat与skipGeneratingTransientNameId均为 SamlRegisteredService 的一级字段。前者为普通字符串属性后者带有JacksonInject(value skipGeneratingTransientNameId)即在 JSON 服务定义中以顶层布尔字段出现默认false正常生成一次性临时值。requiredNameIdFormat 的合法取值SamlProfileSamlNameIdBuilder.parseAndBuildRequiredNameIdFormat方法对配置值做了大小写不敏感的子串匹配与归一化可识别的格式包括配置值可含子串归一化结果OpenSAML NameIDType 常量...nameid-format:emailAddressurn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress...nameid-format:transienturn:oasis:names:tc:SAML:2.0:nameid-format:transient...nameid-format:persistenturn:oasis:names:tc:SAML:2.0:nameid-format:persistent...nameid-format:entityurn:oasis:names:tc:SAML:2.0:nameid-format:entity...nameid-format:X509Subjecturn:oasis:names:tc:SAML:2.0:nameid-format:X509Subject...nameid-format:WindowsDomainQualifiedNameurn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName...nameid-format:kerberosurn:oasis:names:tc:SAML:1.1:nameid-format:kerberos...nameid-format:encryptedurn:oasis:names:tc:SAML:2.0:nameid-format:encrypted其他 / 空白urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified注意匹配方式是包含即命中Strings.CI.contains因此写全 URN 或只写格式关键片段均可被正确识别无法识别的值一律落到unspecified。此外CAS 在单点登出SLO消息构造中同样会消费该字段SamlIdPProfileSingleLogoutMessageCreator 优先取服务定义中的requiredNameIdFormat作为登出消息里的 NameID 格式保证 SSO 与 SLO 两侧的用户标识格式一致。四种典型格式的服务定义完整示例以下四个 JSON 服务定义均基于 SamlRegisteredService可直接用于 JSON 服务注册文件如services/*.json。1. Email Address 格式使用emailAddress格式并以mail属性值作为最终 NameID 值{ class: org.apereo.cas.services.RegisteredService, serviceId: the-entity-id-of-the-sp, name: SAML Service, metadataLocation: /path/to/sp-metadata.xml, id: 1, requiredNameIdFormat: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress, usernameAttributeProvider : { class : org.apereo.cas.services.PrincipalAttributeRegisteredServiceUsernameProvider, usernameAttribute : mail } }原文档示例中class写为org.apereo.cas.support.saml.services.SamlRegisteredServiceSamlRegisteredService继承自BaseWebBasedRegisteredService具体选择哪个类取决于所用服务注册实现此处保留原文档写法亦可被序列化定制器识别。2. Unspecified 格式带 scope 拼接使用unspecified格式并以sysid属性值为值、example.org为 scope最终 NameID 值为sysid-attribute-valueexample.org{ class: org.apereo.cas.services.RegisteredService, serviceId: the-entity-id-of-the-sp, name: SAML Service, metadataLocation: /path/to/sp-metadata.xml, id: 1, requiredNameIdFormat: urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified, usernameAttributeProvider : { class : org.apereo.cas.services.PrincipalAttributeRegisteredServiceUsernameProvider, usernameAttribute : sysid, scope: example.org } }scope 的拼接逻辑来自 BaseRegisteredServiceUsernameAttributeProvider.scopeUsernameIfNecessary只要设置了scope解析出的用户名就会被格式化为用户名scope的形式。这是为 SP 提供带域名限定标识的低成本手段。3. Transient 格式跳过一次性值生成使用transient格式但跳过按规范生成一次性随机值直接以cn属性的大写形式作为 NameID 值{ class: org.apereo.cas.services.RegisteredService, serviceId: the-entity-id-of-the-sp, name: SAML Service, metadataLocation: /path/to/sp-metadata.xml, id: 1, requiredNameIdFormat: urn:oasis:names:tc:SAML:2.0:nameid-format:transient, skipGeneratingTransientNameId : true, usernameAttributeProvider : { class : org.apereo.cas.services.PrincipalAttributeRegisteredServiceUsernameProvider, usernameAttribute : cn, canonicalizationMode : UPPER } }源码中的行为对照SamlProfileSamlNameIdBuilder.getNameIdValueFromNameFormat当格式为transient且skipGeneratingTransientNameId为true时直接使用认证后的 principal id 作为值否则调用persistentIdGenerator.generate(principalId, entityId)生成一个基于 principal 与 SP entityId 的不可逆一次性标识。canonicalizationMode的取值对应CaseCanonicalizationMode枚举如NONE、LOWER、UPPER、MIXED等在 BaseRegisteredServiceUsernameAttributeProvider.resolveUsername 中于去除模式removePattern与 scope 处理之后应用。4. Persistent 格式Shibboleth 兼容算法使用cn属性值创建 persistent NameID采用 Shibboleth 兼容的生成算法{ class: org.apereo.cas.services.RegisteredService, serviceId: the-entity-id-of-the-sp, name: SAML Service, metadataLocation: /path/to/sp-metadata.xml, id: 1, requiredNameIdFormat: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent, usernameAttributeProvider : { class : org.apereo.cas.services.AnonymousRegisteredServiceUsernameAttributeProvider, persistentIdGenerator : { class : org.apereo.cas.authentication.principal.ShibbolethCompatiblePersistentIdGenerator, salt : aGVsbG93b3JsZA, attribute: cn } } }其中 ShibbolethCompatiblePersistentIdGenerator 的关键实现细节salt 处理salt字段按 Base64 解释示例中aGVsbG93b3JsZA解码即helloworld。若未提供 salt首次生成时会随机产生一个 16 位字符串作为默认值——从源码看这意味着不显式配置 salt 将导致每次部署重启后 salt 变化persistent 标识不再稳定因此生产环境必须显式固定 saltdigest 算法prepareMessageDigest使用MessageDigest.getInstance(SHA)注意是 legacy SHA-1与 Shibboleth 兼容当指定了 service此处为 SP 的 entityId时先写入 service 与 principal 并分别以!分隔再对 salt 做摘要最终 Base64 无换行编码输出attribute 字段determinePrincipalIdFromAttributes优先取attribute指定的属性值示例中为cn参与哈希属性不存在时回退到默认 principal id。AnonymousRegisteredServiceUsernameAttributeProvider作为usernameAttributeProvider的容器负责把内部配置好的persistentIdGenerator挂到服务定义上其用户名解析结果即生成的 persistent id再交由 NameID 编码器以persistent格式包装输出。usernameAttributeProvider 的取值解析链路四个示例中的PrincipalAttributeRegisteredServiceUsernameProvider与AnonymousRegisteredServiceUsernameAttributeProvider都派生自 BaseRegisteredServiceUsernameAttributeProvider共享一组后处理配置项可配合上文示例按需叠加字段默认值作用canonicalizationModeNONE大小写规范化NONE/LOWER/UPPER/MIXEDMIXED为大写姓氏 小写名scope空非空时输出用户名scoperemovePattern空非空时按正则从用户名中剔除匹配片段encryptUsernamefalsetrue时经RegisteredServiceCipherExecutor加密用户名要求服务配置了加密密钥PrincipalAttributeRegisteredServiceUsernameProvider 的取值优先级值得注意usernameAttribute支持逗号分隔的多个属性名按顺序取第一个命中的值优先在属性发布策略attribute release policy解析出的属性集中查找找不到时再退回 principal 原始属性两者都没有时会打印告警日志并回退到默认 principal id而非报错——配置了错误属性名不会让断言构建失败只会静默地改变 NameID 的值排障时应关注Principal [{}] does not have an attribute [{}]这条 info 日志。处理顺序为解析出原始用户名 →removePattern剔除 →scope拼接 → 大小写规范化 →可选加密。这一顺序保证了示例 3 中UPPER规范化发生在 scope 拼接之后若需要仅属性值大写、scope 保持小写可调整属性值本身或通过removePattern等手段控制。与 SP 元数据和 AuthnRequest 的交互完整流程可概括为getSupportedNameIdFormatsSP 元数据声明的格式 如有requiredNameIdFormat置顶元数据无声明时兜底 transientgetRequiredNameIdFormatIfAny读取 AuthnRequest 的NameIDPolicy格式若与受支持集合不符则告警不中断流程请求的格式可能不被满足determineNameId按格式顺序逐个尝试编码第一个成功即返回finalizeNameId按服务定义补充nameIdQualifiernameIdQualifier字段或从 IdP 元数据推断与SPNameQualifierserviceProviderNameIdQualifier字段默认取 SP 的 entityId。这两个字段在 SamlRegisteredService 中定义并分别有skipGeneratingNameIdQualifier、skipGeneratingServiceProviderNameIdQualifier开关或在字段值上写none可以整体关闭用于对接不接受 qualifier 的 SP。测试用例 SamlProfileSamlNameIdBuilderTests 覆盖了上述格式选择与值构造行为可作为回归验证的参考。小结requiredNameIdFormat决定 NameID 的格式且在元数据格式中优先级最高未识别的值会静默落到unspecified。NameID 的值由usernameAttributeProvider决定属性选择含 scope、大小写规范化、正则剔除、加密后处理transient 格式还受skipGeneratingTransientNameId控制是否真正生成一次性值persistent 格式则通过ShibbolethCompatiblePersistentIdGenerator的 salt attribute 组合产生稳定的匿名标识。两条线共同决定了断言中saml2:NameID的最终形态配置时务必同时校验 SP 元数据声明、AuthnRequest 中的NameIDPolicy与服务定义三者的一致性。赞分享后端认证鉴权单点登录【免费下载链接】casApereo CAS - Identity Single Sign On for all earthlings and beyond.项目地址https://gitcode.com/gh_mirrors/ca/cas点击查看免费下载相关推荐Apereo CAS中SAML2 NameID配置详解Apereo CAS中SAML2 NameID配置详解 什么是NameID 在SAML协议中NameID是一个核心概念它代表了认证主体用户的唯一标识符。后端认证鉴权单点登录Apereo CAS 配置 SAML2 UnsolicitedIdP-InitiatedSSO 详解Apereo CAS 配置 SAML2 UnsolicitedIdP InitiatedSSO 详解 Apereo CAS 作为 SAML2 身份提供方I后端认证鉴权单点登录CAS项目SAML2协议中NameID配置详解CAS项目SAML2协议中NameID配置详解 什么是NameID 在SAML2协议中NameID是一个核心概念它用于标识认证主体用户的唯一标识符。Na后端认证鉴权单点登录上一篇洛雪音乐助手架构深度解析现代Electron应用的多源音乐聚合方案下一篇6个实用技巧深度掌握洛雪音乐助手的高效使用方法创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考