Apereo CAS OpenID Connect 身份保证（Identity Assurance）实战指南：verified_claims、assurance 作用域与验证明细管理

后端认证鉴权单点登录【免费下载链接】casApereo CAS - Identity Single Sign On for all earthlings and beyond.项目地址https://gitcode.com/gh_mirrors/ca/cas点击查看免费下载本指南围绕 Apereo CAS 的 OpenID Connect 身份保证Identity Assurance扩展展开讲解如何为信赖方Relying Party提供经过验证的声明verified claims及其验证状态信息验证什么、如何验证、何时验证、依据何种规则、使用何种证据。读完本文你将掌握assurance内置作用域的配置方法、verified_claims的生成与审计机制以及如何通过 JSON 文件或自定义AssuranceVerificationSource管理身份保证验证记录。文中的实现细节均可对照 docs/cas-server-documentation/authentication/OIDC-Authentication-Identity-Assurance.md 及support/cas-server-support-oidc*系列模块源码进行验证。什么是 OpenID Connect 身份保证Identity Assurance身份保证是 OpenID Connect 的一个扩展规范用于向信赖方提供已验证的声明verified claims并附带关于这些声明验证状态的明确说明——即验证了什么what、如何验证how、何时验证when、依据什么规则according to what rules、使用什么证据using what evidence。在 Apereo CAS 中该特性主要用于需要强身份保证strong assurance的业务场景例如满足反洗钱Anti-Money Laundering等监管合规要求医疗健康数据的访问控制风险缓解risk mitigation与欺诈预防fraud prevention。从源码结构看身份保证功能自 CAS 7.0.0 起在org.apereo.cas.oidc.assurance包中实现核心构件包括AssuranceVerificationSource验证记录verification records的加载源接口AssuranceVerificationJsonSource基于 JSON 文件的默认实现AssuranceVerifiedClaimsProducer与DefaultAssuranceVerifiedClaimsProducer负责将普通声明加工为verified_claims结构。相关实现位于 support/cas-server-support-oidc-core-api/src/main/java/org/apereo/cas/oidc/assurance/Spring 装配逻辑在 OidcConfiguration.java。启用身份保证配置属性一览身份保证功能的配置前缀为cas.authn.oidc.identity-assurance由 CAS 配置属性机制统一管理。完整属性列表可通过 CAS 属性文档中的cas.authn.oidc.identity-assurance分组查询。核心属性如下属性说明cas.authn.oidc.identity-assurance.verification-source.location身份保证验证记录 JSON 文件的路径classpath 或文件系统均可未配置时 CAS 使用空的验证源以测试代码为例AssuranceVerificationJsonSourceTests.java 通过以下属性加载验证记录cas.authn.oidc.identity-assurance.verification-source.locationclasspath:assurance/id-1.json装配逻辑见 OidcConfiguration.java当容器中不存在名为assuranceVerificationSource的 Bean 时CAS 会读取上述位置属性并创建AssuranceVerificationJsonSource若属性为空则回退到AssuranceVerificationSource::empty即不加载任何验证记录。此外服务端发现配置OidcServerDiscoverySettings中还有一组与身份保证配套的开关它们直接决定最终verified_claims的裁剪行为包括verifiedClaimsSupported是否支持已验证声明trustFrameworksSupported支持的信任框架trust framework列表evidenceSupported支持的证据类型列表documentsSupported支持的证件/文档类型列表documentsValidationMethodsSupported/documentsVerificationMethodsSupported支持的文档校验方法与验证方法列表electronicRecordsSupported支持的电子记录类型列表claimsInVerifiedClaimsSupported允许放入verified_claims.claims的声明名列表。这些开关的过滤逻辑在 DefaultAssuranceVerifiedClaimsProducer.java 中体现若发现服务端不声明支持某证据类型、文档类型或校验/验证方法对应证据会被从最终输出中剔除。使用 assurance 作用域获取身份保证声明CAS 预置了一个特殊的内置作用域assurance用于携带身份保证相关声明。为满足某些司法辖区对身份保证的要求该作用域在 OpenID Connect 规范定义的标准声明之外额外携带以下面向终端用户数据的特定声明nationalities国籍birth_family_name出生时的姓氏birth_given_name出生时的名字msisdn移动用户号码place_of_birth出生地以及更多同类声明。要让某个信赖方能够按assurance作用域分组接收这些声明需要在其注册服务定义中显式加入assurance作用域{ class : org.apereo.cas.services.OidcRegisteredService, clientId: ..., clientSecret: ..., serviceId : ..., name: OIDC, id: 1, scopes : [ java.util.HashSet, [ openid, profile, assurance ] ] }要点说明class必须为org.apereo.cas.services.OidcRegisteredService该注册服务类型定义于 support/cas-server-support-oauth-services 模块scopes使用java.util.HashSet包装除标准的openid、profile外将assurance加入集合即完成授权只有被授权作用域覆盖的声明才会进入 ID Token / UserInfo 响应。ID Token 中的 txn 声明与审计跟踪CAS 生成的 ID Token 会携带一个特殊的txn声明用于在 OpenID Connect 事务的各方之间建立审计线索audit trail。CAS 的审计记录会维护与txn声明对应的审计轨迹至少包含以下细节txn事务 IDauthn_methods本次所采用的认证方法生成的 ID Token 本身。需要注意出现在 CAS 审计日志中的 ID Token不会被解包即以明文形式展示或记录其中的声明。ID Token 原样展示且根据信赖方的配置它可能已被签名signed和/或加密encrypted。因此审计日志中看到的是完整的 JWT 串而非可读的 JSON 载荷。通过 JSON 文件配置验证记录身份保证验证记录verification records默认从一个 JSON 文件加载文件路径通过配置属性cas.authn.oidc.identity-assurance.verification-source.location告知 CAS。文件可包含多条验证记录示例结构如下[ { trust_framework: eidas, assurance_level: substantial }, { trust_framework: it_spid, time: 2019-04-20T20:16Z, verification_process: b54c6f-6d3f-4ec5-973e-b0d8506f3bc7, evidence: [ { type: document, validation_method: { type: vcrypt }, verification_method: { type: bvr }, time: 2019-04-20T20:11Z, document_details: { type: passport, issuer: { name: Ministro Affari Esteri, country: ITA }, document_number: 83774554, date_of_issuance: 2011-04-20, date_of_expiry: 2021-04-19 } } ] } ]上述 JSON 中字段含义如下trust_framework信任框架标识如eidas欧盟 eIDAS、it_spid意大利 SPIDassurance_level保证级别如substantial实质性time验证发生时间ISO 8601verification_process验证流程 IDevidence证据数组每条证据包含type如document、validation_method校验方法如vcrypt、verification_method验证方法如bvr、time及document_details证件详情含证件类型、签发机构、证件号码、签发与到期日期。这些字段与org.apereo.cas.oidc.assurance.entity包中的实体类一一对应包括 Verification.java、Evidence.java、DocumentDetails.java、ValidationMethod.java、VerificationMethod.java 等共 13 个实体类覆盖验证记录的全部字段。从 AssuranceVerificationJsonSource.java 源码可以看出 JSON 加载的底层机制构造时通过ResourceUtils.doesResourceExist(resource)检查资源是否存在存在则解析并缓存全部验证记录若资源是文件还会启动一个FileWatcherService监听文件变化文件更新时自动重新加载热更新解析使用 JacksonObjectMapper并支持 HJSON 语法通过JsonValue.readHjson预处理findByTrustFramework按trust_framework进行大小写不敏感匹配返回命中的首条验证记录。对应测试 AssuranceVerificationJsonSourceTests.java 验证了从classpath:assurance/id-1.json加载 8 条验证记录并序列化为 JSON 的完整流程。生成 verified_claims 输出被标记为**可验证verifiable并指定了信任框架trust framework**的声明claim 或 attribute definition在生成 ID Token 或用户信息user profile载荷时会受到特殊处理。首先需要在属性定义中标记 trust framework。以 OIDC-Attribute-Definitions.md 中的示例为准使用OidcAttributeDefinition定义{ class: java.util.TreeMap, mail: { class: org.apereo.cas.oidc.claims.OidcAttributeDefinition, key: mail, structured: false, trustFramework: eidas } }OidcAttributeDefinition支持两个附加设置名称说明structured默认false。当属性名呈层级布局如parent.child.child时将结果编码为层级/结构化属性trustFramework默认空。指定身份保证信任框架名称如eidas强制 CAS 将该声明标记为已验证声明verified claim处理流水线如下ID Token 声明收集器 OidcSimpleIdTokenClaimCollector.java 在conclude阶段遍历所有已收集的声明对每个声明名在AttributeDefinitionStore中查找OidcAttributeDefinition凡trustFramework非空的定义都会触发assuranceVerifiedClaimsProducer.produce(claims, claimName, definition.getTrustFramework())。随后 DefaultAssuranceVerifiedClaimsProducer.java 执行如下逻辑若发现服务不支持已验证声明verifiedClaimsSupportedfalse或指定信任框架不在trustFrameworksSupported列表中直接返回空 Map不产生verified_claims通过assuranceVerificationSource.findByTrustFramework(trustFramework)获取对应验证记录按服务端发现配置过滤证据证据类型、文档类型、校验方法、验证方法、电子记录类型等不支持的条目被移除将验证记录写入verified_claims.verification若声明名在claimsInVerifiedClaimsSupported允许范围内将该声明及其当前值移入verified_claims.claims并从 JWT 顶层移除原声明。最终载荷中已验证声明的轮廓大致如下{ verified_claims: { verification: { trust_framework: eidas, assurance_level: substantial }, claims: { given_name: Max, family_name: Meier, birthdate: 1956-01-28 } } }对应测试 DefaultAssuranceVerifiedClaimsProducerTests.java 覆盖了该生产器的核心行为。自定义验证记录来源如果希望自行设计身份保证验证记录的来源例如从数据库、REST 接口或目录服务读取可以实现AssuranceVerificationSource接口并注册为 Spring Bean替换默认的 JSON 实现Bean public AssuranceVerificationSource assuranceVerificationSource() { return new MyAssuranceVerificationSource(); }AssuranceVerificationSource接口定义于 AssuranceVerificationSource.java其核心方法为ListVerification load()加载全部验证记录必须实现default OptionalVerification findByTrustFramework(String trustFramework)按信任框架查找验证记录默认返回空static AssuranceVerificationSource empty()返回空实现用于未配置来源时的回退。从装配逻辑看只要容器中存在名为assuranceVerificationSource的 BeanConditionalOnMissingBean便会让默认的 JSON 实现让位于自定义 Bean因此实现load()并可选重写findByTrustFramework即可无缝接入 CAS 的verified_claims生成流程。注册自定义配置到 CAS 运行时的更多方式可参阅 Configuration-Management-Extensions 指南。小结本文围绕 Apereo CAS 的 OpenID Connect 身份保证扩展梳理了从配置启用到最终verified_claims输出的完整链路通过cas.authn.oidc.identity-assurance配置 JSON 验证记录来源、在注册服务中开放assurance作用域、为属性定义指定trustFramework再由OidcSimpleIdTokenClaimCollector与DefaultAssuranceVerifiedClaimsProducer在 ID Token / UserInfo 生成阶段完成声明验证与重组同时借助 ID Token 的txn声明建立跨方审计线索。对于有特殊存储需求的部署可通过自定义AssuranceVerificationSourceBean 无缝替换默认的 JSON 加载实现。相关源码集中在 support/cas-server-support-oidc-core-api 与 support/cas-server-support-oidc 模块可结合测试用例进一步验证各环节行为。赞分享后端认证鉴权单点登录【免费下载链接】casApereo CAS - Identity Single Sign On for all earthlings and beyond.项目地址https://gitcode.com/gh_mirrors/ca/cas点击查看免费下载相关推荐Apereo CAS 作为 OpenID Connect 可验证凭证签发者OIDC4VCI Issuer实战指南Apereo CAS 作为 OpenID Connect 可验证凭证签发者OIDC4VCI Issuer实战指南 Apereo CAS 在标准 OpenID后端认证鉴权单点登录Apereo CAS 中 OpenID Connect 的 WebFinger Issuer Discovery 实战指南Apereo CAS 中 OpenID Connect 的 WebFinger Issuer Discovery 实战指南 本篇技术指南围绕 Apereo CA后端认证鉴权单点登录Apereo CAS OpenID Connect Scope Approval作用域授权确认机制与配置指南Apereo CAS OpenID Connect Scope Approval作用域授权确认机制与配置指南 导读 Scope Approval作用域授权确后端认证鉴权单点登录创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考