后端认证鉴权单点登录【免费下载链接】casApereo CAS - Identity Single Sign On for all earthlings and beyond.项目地址https://gitcode.com/gh_mirrors/ca/cas点击查看免费下载本文以 Apereo CAS 官方文档 SAML2 Service Provider Metadata 为核心骨架结合当前仓库中cas-server-support-saml-idp*系列模块的源码实现系统讲解如何管理注册到 CAS 的 SAML2 服务提供方SP元数据。读完本文你将掌握CAS 通过 Actuator 端点监控与操作元数据缓存的方法、元数据聚合Aggregate的双重复核机制与过滤策略、三级缓存过期策略以及 URL / 文件 / 目录 / JSON 四种主流元数据存储方式及其底层解析器实现能够直接落地到真实的 SAML2 单点登录部署中。一、概述CAS 如何认识 SAML2 服务提供方在 Apereo CAS 的 SAML2 身份提供方IdP实现中每一个需要接入的 SP 都以SamlRegisteredService的形式注册在 CAS 的服务注册表Service Registry中。该类型的核心类定义位于 SamlRegisteredService.java它继承了BaseWebBasedRegisteredService并扩展了大量与元数据管理相关的字段metadataLocationSP 元数据的位置URL、文件路径、目录或json://等专用前缀该字段标注了ExpressionLanguageCapable支持 Spring 表达式语言metadataCriteriaDirection/metadataCriteriaPattern/metadataCriteriaEntityAttributes/metadataCriteriaRoles解析元数据时的实体过滤条件metadataExpirationDuration该 SP 元数据的专属缓存过期时长默认值为PT60M60 分钟metadataSignatureLocation元数据签名验证证书或公钥的位置requireSignedRoot是否要求元数据根元素必须签名默认truevalidateMetadataCertificates是否校验元数据中证书的过期情况metadataMaxValidity对元数据根元素validUntil属性的最大有效期限制小于 1 表示不限制。因此元数据管理是 SAML2 接入配置中识别 SP 获取信任材料证书、端点、绑定的关键一环。下面按官方文档的脉络逐层展开。二、Actuator 端点元数据监控与运维入口官方文档首先列出了两个与 SP 元数据直接相关的 Actuator 端点它们是运维 SAML2 接入状态的核心入口。1. health 端点SP 元数据可用性健康检查health端点会暴露一个名为samlRegisteredServiceMetadataHealthIndicator的健康指示器。其实现位于 SamlRegisteredServiceMetadataHealthIndicator.java它会遍历ServicesManager中所有SamlRegisteredService类型的服务对每个服务检查当前元数据解析计划SamlRegisteredServiceMetadataResolutionPlan中注册的所有 resolver 链是否存在至少一个能支撑该服务supports且isAvailable将每个服务的name、id、metadataLocation、serviceId以及availabilityYES/NO写入健康检查明细只要至少一个服务可解析元数据整体状态即为UP只有当服务列表非空且全部服务都不可解析时才报告DOWN。对应测试 SamlRegisteredServiceMetadataHealthIndicatorTests.java 验证了三种场景正常服务返回UP、指向未知位置的元数据返回DOWN、多个服务中仅部分不可用仍返回UP。2. 元数据缓存管理端点samlIdPRegisteredServiceMetadataCache该端点Endpoint(id samlIdPRegisteredServiceMetadataCache, defaultAccess Access.NONE)实现于 SamlRegisteredServiceCachedMetadataEndpoint.java提供查看与失效两类操作GET查看缓存元数据查询参数serviceId必填可为注册服务的数字 id、名称或 serviceId、entityId可选用于定位聚合元数据中的具体 SP、force默认true强制重新解析并刷新缓存、includeMetadata默认true是否在响应中包含 XML 元数据内容。响应中会返回注册服务查找耗时、解析耗时、缓存命中时间cachedInstant及各实体 id 对应的元数据。DELETE失效缓存参数同上若完全不传参则清空整张元数据缓存cachingMetadataResolver.getObject().invalidate()若传入serviceId以及可选的entityId则仅使该服务对应的缓存键失效。对应测试 SamlRegisteredServiceCachedMetadataEndpointTests.java 展示了典型调用方式端点路径为/actuator/samlIdPRegisteredServiceMetadataCache并在测试配置中启用了端点暴露与访问management.endpoints.web.exposure.include* management.endpoint.samlIdPRegisteredServiceMetadataCache.accessUNRESTRICTED实操示例生产环境请按实际安全策略收敛访问权限# 查看某个 SP 的缓存元数据并强制刷新 curl https://cas.example.org/actuator/samlIdPRegisteredServiceMetadataCache?serviceId1entityIdhttps://sp.example.org/samlforcetrue # 仅使特定 SP 的缓存条目失效 curl -X DELETE https://cas.example.org/actuator/samlIdPRegisteredServiceMetadataCache?serviceId1 # 清空全部元数据缓存 curl -X DELETE https://cas.example.org/actuator/samlIdPRegisteredServiceMetadataCache三、元数据聚合Metadata Aggregates双重复核机制CAS 对服务的识别本质上是基于serviceId正则表达式的匹配例如用一个形如https://sp\.example\.org/.*的serviceId模式将某个组织域下的所有应用一次性注册进来。当某个服务注册记录指向的是聚合元数据一份元数据文档中包含多个实体描述符 EntityDescriptor时CAS 会执行双重授权检查先在解析得到的元数据组件集合中查找目标实体 id再检查该实体 id 是否匹配该服务定义中分配的serviceId正则模式。由此可以组合出三种授权策略放开模式将serviceId模式放宽例如.允许元数据中所有被授权的实体通过收窄模式将serviceId模式限制为聚合元数据中选定的少数实体 id —— 这等价于在元数据完整加载解析之后再事后按实体 id 过滤一次解析时过滤在 CAS 读取元数据的过程中通过metadataCriteria*系列条件直接过滤实体 —— 效果等同于强制serviceId模式只匹配指定实体但由于过滤发生在读取阶段加载性能更好。源码层面的过滤实现第三种策略的实现位于 BaseSamlRegisteredServiceMetadataResolver.java 的buildPredicateFilterIfNeeded与buildEntityRoleFilterIfNeeded方法中正则谓词过滤当metadataCriteriaDirection取值为INCLUDE或EXCLUDE与metadataCriteriaPattern正则表达式均非空、且正则合法时CAS 构建 OpenSAML 的PredicateFilter用entityDescriptor.getEntityID().matches(pattern)判定实体去留实体属性过滤当metadataCriteriaEntityAttributes实体属性名到属性值的映射非空时CAS 通过SamlIdPUtils.buildEntityAttributePredicate构造属性谓词同样按INCLUDE/EXCLUDE方向过滤角色过滤metadataCriteriaRoles默认值为SPSSODescriptor.DEFAULT_ELEMENT_NAME即SPSSODescriptor可通过逗号分隔指定多个角色配合metadataCriteriaRemoveEmptyEntitiesDescriptors默认true与metadataCriteriaRemoveRolelessEntityDescriptors默认true构建EntityRoleFilter。一个收窄模式的聚合元数据服务注册示例JSON{ class : org.apereo.cas.support.saml.services.SamlRegisteredService, serviceId : https://aggregate\\.example\\.org/.*, name : SAMLService, id : 10000001, metadataLocation : https://metadata.example.org/aggregate.xml, metadataCriteriaDirection : INCLUDE, metadataCriteriaPattern : https://(app1|app2)\\.example\\.org }四、元数据缓存与解析按需加载与三级过期策略全局缓存模型SP 元数据是按需加载的每个服务的元数据在首次被请求时解析随后缓存在一张全局缓存中缓存时长可配置。后续请求一律先查缓存未命中才真正加载或连接配置的资源。每个注册的 SP 还可以通过metadataExpirationDuration单独覆盖全局默认值。全局缓存的底层实现是 Caffeine 的LoadingCache见 SamlRegisteredServiceDefaultCachingMetadataResolver.java。其构造函数从配置对象读取cacheMaximumSize缓存最大条目数默认10_000cacheExpiration默认缓存过期时长默认PT24H24 小时maximumRetryAttempts解析失败时的最大重试次数默认3设为 0 或负数则禁用重试。同时缓存解析器在拿到缓存结果后会校验解析出的实体描述符是否有效isMetadataResolverAcceptable无效时会主动失效对应缓存键并抛出SamlException从而避免把损坏的元数据长期留在缓存中。过期策略的三级判定顺序缓存条目的实际存活时间由一个自定义的Expiry策略决定实现见 SamlRegisteredServiceMetadataExpirationPolicy.java。其判定顺序与官方文档完全一致SP 元数据内的CacheDuration设置优先尝试在解析结果中定位SPSSODescriptor其次回退到EntityDescriptor的cacheDuration属性取其毫秒值换算为纳秒注册服务定义的过期策略若元数据未声明CacheDuration则使用该服务的metadataExpirationDurationSamlRegisteredService默认值PT60M全局过期策略若服务也未定义则回退到 CAS 全局配置cas.authn.saml-idp.metadata.core.cache-expiration默认PT24H。集群环境注意事项官方文档特别提醒缓存状态归属 CAS 节点自身内存不会在集群中分发。在多节点高可用HA部署下必须绕过负载均衡直接访问目标 CAS 节点才能操作该节点内存中的元数据缓存否则你对某一节点缓存所做的变更对其他节点不可见直到各自缓存条目过期或被强制失效。五、元数据存储四种开箱即用的配置方式注册到 CAS 的 SAML2 SP其元数据可以按以下几种方式提供。5.1 默认方式URL / 文件 / 目录1URLHTTP/HTTPS 发布若 SP 能产出有效元数据可直接将元数据发布为 URL注册记录形如{ class : org.apereo.cas.support.saml.services.SamlRegisteredService, serviceId : the-entity-id-of-the-sp, name : SAMLService, id : 1, metadataLocation : https://url/to/metadata.xml }要点多个位置可用逗号分隔CAS 的 UrlResourceMetadataResolver.java 会逐个尝试加载。本地备份复用CAS 会把下载的元数据在磁盘上保留一份最后已知良好last known good的备份文件备份目录名metadata-backups当远端无法下载时回退使用备份只有禁用强制刷新cas.authn.saml-idp.metadata.http.force-metadata-refreshfalse时才可能在远端可达的情况下直接复用仍有效的备份。签名验证安全红线官方文档强调通过 URL 共享的 SAML2 元数据应当签名以保证完整性与真实性消费方在投入使用前必须验证 XML 签名仅靠 TLS 加密连接请求元数据是不够的。CAS 侧可通过metadataSignatureLocation指定验证证书/公钥并用requireSignedRoot默认true要求根元素已签名。URL 方式相关的配置属性定义于 HttpSamlMetadataProperties.java# 是否强制从 URL 源重新下载元数据、忽略本地缓存副本默认 true cas.authn.saml-idp.metadata.http.force-metadata-refreshtrue # 下载元数据的备份目录未定义时根据磁盘上的元数据位置推算支持 Spring 表达式 cas.authn.saml-idp.metadata.http.metadata-backup-locationfile:/etc/cas/saml/metadata-backups2文件File元数据 XML 文件直接放在文件系统或 classpath上{ class : org.apereo.cas.support.saml.services.SamlRegisteredService, serviceId : the-entity-id-of-the-sp, name : SAMLService, id : 1, metadataLocation : /path/to/metadata.xml }多个位置同样可用逗号分隔。文件方式由 FileSystemResourceMetadataResolver.java 处理它会按逗号拆分metadataLocation逐个构建InMemoryResourceMetadataResolver。也支持以 classpath 前缀如classpath:/metadata/sp.xml指向打包在应用内的资源由ClasspathResourceMetadataResolver处理。metadataLocation字段标注了ExpressionLanguageCapable因此可使用 Spring 表达式语言动态拼装路径例如file:/etc/cas/${#systemProperties[tier]}/metadata.xml。完整语法与预定义变量systemProperties、environmentVars、randomString6等见 Configuration-Spring-Expressions.md。3目录Directory从本地目录按需获取元数据目录内容由运维自行维护且支持在 CAS 运行期间向目录投放新文件新元数据会在首次被请求时自动可见{ class : org.apereo.cas.support.saml.services.SamlRegisteredService, serviceId : ., name : SAMLService, id : 1, metadataLocation : /path/to/metadata/directory }目录方式的文件命名有硬性约定文件必须命名为SP 实体 id 的小写十六进制 SHA-1 摘要 .xml后缀。例如实体 id 为sp1:example的 SP其元数据文件应命名为3494744350abe1fd8efa68c5e2696dbbdca4c33a.xml。从源码看目录模式下FileSystemResourceMetadataResolver.getMetadataResolver会改用 OpenSAML 的LocalDynamicMetadataResolverFilesystemLoadSaveManagerDefaultLocalDynamicSourceKeyGeneratorsource key 生成策略即上述 SHA-1 命名约定实现对目录内元数据的动态加载。5.2 动态元数据saml-sp-metadata.json若待接入的 SP 无法产出 SAML 元数据除了使用第三方在线工具先生成元数据 XML 再按文件方式注册外CAS 还提供了一种更轻量的动态元数据方案在 CAS 元数据制品所在目录放置一个独立的saml-sp-metadata.json文件。该文件位于cas.authn.saml-idp.metadata.file-system.location默认file:/etc/cas/saml见 FileSystemSamlMetadataProperties.java指定的目录下。其内容采用较宽松的 JSONHJSON语法每个条目以 SP 实体 id 为键{ https://example.org/saml: { entityId: https://example.org/saml, certificate: MIIDUj..., assertionConsumerServiceUrl: https://example.org/sso/, binding: urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST } }字段说明entityId为 SP 实体 idcertificate为 SP 的签名证书PEM/DER 内容示例中以MIIDUj...截断表示assertionConsumerServiceUrl为断言消费服务地址binding为断言消费绑定默认即urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST。对应的服务注册记录将metadataLocation指定为专用前缀json://{ class : org.apereo.cas.support.saml.services.SamlRegisteredService, serviceId : https://example.org/saml, name : SAMLService, id : 10000003, metadataLocation : json:// }json://前缀是触发 JSON 动态元数据解析的信号缺一不可。其底层实现是 JsonResourceMetadataResolver.java构造时读取 classpath 上的metadata/sp-metadata-template.xml作为元数据模板并定位saml-sp-metadata.json若文件存在启动一个FileWatcherService监听文件变更变更时自动重读 —— 因此修改 JSON 无需重启 CASresolve阶段按service.getServiceId()在映射中查找条目将模板中的${entityId}、${certificate}、${binding}、${assertionConsumerServiceUrl}占位符替换后在内存中构建InMemoryResourceMetadataResolversupports仅当metadataLocation以json://开头时返回true条目内部类SamlServiceProviderMetadata的字段与上述 JSON 结构一一对应。测试 JsonResourceMetadataResolverTests.java 验证了将saml-sp-metadata.json复制到临时目录后注册serviceIdhttps://example.org/saml、metadataLocationjson://的服务可以成功解析出实体描述符。适用场景对于只提供一个 URL 一张签名证书的 SP这种方案免去了单独创建、维护 XML 元数据文件的负担CAS 会在认证流程中按需动态组装元数据。5.3 高级动态元数据策略除上述方式外CAS 还支持通过以下存储/协议策略管理 SP 元数据官方文档分别给出了专项指南以下链接均已转换为仓库根目录相对路径存储方式说明Metadata Query ProtocolMDQConfiguring-SAML2-DynamicMetadata-MDQ.mdHTTP/HTTPSConfiguring-SAML2-DynamicMetadata-HTTP.mdRESTConfiguring-SAML2-DynamicMetadata-REST.mdGitConfiguring-SAML2-DynamicMetadata-Git.mdMongoDbConfiguring-SAML2-DynamicMetadata-MongoDb.mdRedisConfiguring-SAML2-DynamicMetadata-Redis.mdJPAConfiguring-SAML2-DynamicMetadata-JPA.mdGroovyConfiguring-SAML2-DynamicMetadata-Groovy.mdAmazon S3Configuring-SAML2-DynamicMetadata-AmazonS3.mdDynamoDbConfiguring-SAML2-DynamicMetadata-DynamoDb.md这些策略共同注册在元数据解析计划SamlRegisteredServiceMetadataResolutionPlan的 resolver 链上与前面介绍的健康检查、缓存机制协同工作。六、配置属性速查以下核心属性均位于cas.authn.saml-idp.metadata.*前缀下属性类定义可参见 SamlIdPMetadataProperties.java 及其嵌套子类 CoreSamlMetadataProperties.java、HttpSamlMetadataProperties.java、FileSystemSamlMetadataProperties.java配置项默认值说明cas.authn.saml-idp.metadata.core.cache-maximum-size10000元数据全局缓存的最大条目数cas.authn.saml-idp.metadata.core.cache-expirationPT24H元数据全局缓存过期时长三级过期策略的兜底cas.authn.saml-idp.metadata.core.maximum-retry-attempts3元数据解析失败的最大重试次数0 或负数表示禁用重试cas.authn.saml-idp.metadata.core.fail-fasttrue无效元数据是否在启动解析阶段快速失败cas.authn.saml-idp.metadata.core.require-valid-metadatatrue是否要求解析得到的元数据必须有效cas.authn.saml-idp.metadata.http.force-metadata-refreshtrueURL 源元数据是否强制重新下载、忽略本地备份复用cas.authn.saml-idp.metadata.http.metadata-backup-location空自动推算URL 元数据下载后的磁盘备份目录支持 Spring 表达式cas.authn.saml-idp.metadata.file-system.locationfile:/etc/cas/samlSAML 元数据与签名/加密密钥所在目录也是saml-sp-metadata.json的查找目录cas.authn.saml-idp.metadata.file-system.sign-metadatafalse磁盘上生成的元数据是否用 IdP 签名证书/密钥进行数字签名七、小结Apereo CAS 的 SP 元数据管理能力可以归纳为三条主线识别与授权以serviceId正则识别 SP通过聚合元数据的双重复核先定位实体、再匹配模式实现灵活的 INCLUDE/EXCLUDE 过滤过滤既可事后进行收窄serviceId也可在解析时完成metadataCriteria*性能更优缓存与失效基于 Caffeine 的全局缓存按需加载元数据过期时长遵循SP 元数据CacheDuration→ 服务级metadataExpirationDuration默认PT60M→ 全局cache-expiration默认PT24H的三级顺序health与samlIdPRegisteredServiceMetadataCache两个 Actuator 端点分别负责可用性监控与缓存查看/失效存储多样性URL / 文件 / 目录 /json://四种基础方式开箱即用另有 MDQ、REST、Git、MongoDb、Redis、JPA、Groovy、Amazon S3、DynamoDb 等高级动态元数据策略可按需接入。掌握这些机制你便能在实际部署中准确选择元数据接入方式、合理设置缓存参数并借助 Actuator 端点快速定位和修复 SP 元数据相关的接入问题。赞分享后端认证鉴权单点登录【免费下载链接】casApereo CAS - Identity Single Sign On for all earthlings and beyond.项目地址https://gitcode.com/gh_mirrors/ca/cas点击查看免费下载相关推荐Apereo CAS SAML2 元数据的 Redis 管理动态元数据存储、按服务覆盖与实现解析Apereo CAS SAML2 元数据的 Redis 管理动态元数据存储、按服务覆盖与实现解析 在 Apereo CAS 中充当 SAML2 身份提供者I后端认证鉴权单点登录Apereo CAS SAML2 Git 元数据管理SP 与 IdP 元数据的版本控制实战Apereo CAS SAML2 Git 元数据管理SP 与 IdP 元数据的版本控制实战 本篇技术指南聚焦 Apereo CAS 中 SAML2 元数据的后端认证鉴权单点登录Apereo CAS SAML2 委托认证实战将服务提供商元数据托管到 Amazon S3Apereo CAS SAML2 委托认证实战将服务提供商元数据托管到 Amazon S3 本文将介绍 Apereo CAS 在配置 SAML2 委托认证D后端认证鉴权单点登录创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考