后端认证鉴权单点登录【免费下载链接】casApereo CAS - Identity Single Sign On for all earthlings and beyond.项目地址https://gitcode.com/gh_mirrors/ca/cas点击查看免费下载REST 认证策略是 Apereo CAS 内置的一种可插拔认证策略Authentication Policy它允许 CAS 在认证流程中向外部 REST 端点发送POST请求将已认证的 Principal主体作为 JSON 消息体提交由外部系统对账号状态与登录策略进行裁决。本文围绕 Configuring-Authentication-Policy-REST.md 展开先完整介绍该策略的配置项与 HTTP 响应码语义映射再结合仓库源码剖析其调用链、异常映射与重试机制最后给出可运行的端点示例与测试用例佐证帮助你在实际部署中把账号禁用、锁定、过期、强制改密等业务规则外置到 REST 服务。一、REST 认证策略的作用与定位在 CAS 的认证策略体系中REST 策略属于“外部调用型”策略它本身不校验密码而是在认证事件发生之后对已产生的 Principal 做二次裁决用于检查该账号是否被禁用、锁定、过期、需要强制修改密码等状态。其典型应用场景包括账号状态由独立的用户中心、风控系统或 IAM 平台维护CAS 需要实时查询而非同步本地数据需要对登录行为做更细粒度的策略判断如地域、风险等级由外部系统返回最终放行或拒绝结论希望在不修改 CAS 源码、不重启实例的前提下通过调整外部接口逻辑动态变更登录策略。从源码结构看REST 策略的 Java 实现为RestfulAuthenticationPolicy位于 RestfulAuthenticationPolicy.java它实现自AuthenticationPolicy接口AuthenticationPolicy.java。该接口是 CAS 所有认证策略的公共契约核心方法是isSatisfiedBy(...)返回AuthenticationPolicyExecutionResult表示策略是否满足。二、配置方式与全部参数详解REST 认证策略的配置前缀为cas.authn.policy.rest对应配置模型类RestAuthenticationPolicyPropertiesRestAuthenticationPolicyProperties.java。该类继承自BaseRestEndpointPropertiesBaseRestEndpointProperties.java因此可配置项如下配置项类型默认值说明cas.authn.policy.rest[].urlString无必填REST 端点地址CAS 将向其发送POST请求支持 Spring 表达式语言ExpressionLanguageCapablecas.authn.policy.rest[].basicAuthUsernameString无若端点受 HTTP Basic 认证保护用于认证的用户名cas.authn.policy.rest[].basicAuthPasswordString无若端点受 HTTP Basic 认证保护用于认证的密码cas.authn.policy.rest[].headersMap空随请求发送的额外 HTTP 头会覆盖 CAS 预置的同名请求头cas.authn.policy.rest[].maximumRetryAttemptsint3访问端点失败时的最大重试次数设为 0 或负数则禁用重试cas.authn.policy.rest[].enabledbooleanfalse是否启用该策略实例继承自BaseAuthenticationPolicyPropertiesBaseAuthenticationPolicyProperties.javacas.authn.policy.rest[].nameString无策略名称cas.authn.policy.rest[].orderintOrdered.LOWEST_PRECEDENCE多个策略并存时的执行顺序数值越小优先级越高由于rest字段在配置模型中声明为列表ListRestAuthenticationPolicyProperties见 AuthenticationPolicyProperties.java你可以同时配置多个 REST 端点CAS 会按顺序逐一执行所有端点均返回成功才判定策略满足。2.1 一个最小可用的 YAML 配置示例cas: authn: policy: rest: - url: https://account.example.org/api/authn/policy basicAuthUsername: cas basicAuthPassword: changeit headers: X-Environment: prod maximumRetryAttempts: 2 enabled: true name: central-account-policy order: 10对应的 properties 写法为cas.authn.policy.rest[0].urlhttps://account.example.org/api/authn/policy cas.authn.policy.rest[0].basicAuthUsernamecas cas.authn.policy.rest[0].basicAuthPasswordchangeit cas.authn.policy.rest[0].headers.X-Environmentprod cas.authn.policy.rest[0].maximumRetryAttempts2 cas.authn.policy.rest[0].enabledtrue提示enabled字段默认值在配置模型中是false实际部署时若通过cas.authn.policy.rest列表定义了端点需显式开启url为必填项标注了RequiredProperty缺失会导致配置校验失败。2.2 请求细节方法、请求体与请求头从 RestfulAuthenticationPolicy.java 的源码实现看CAS 向端点发出的请求具有以下特征HTTP 方法POSTHttpMethod.POST请求体当前认证事件的 Principal 经 JacksonObjectMapper序列化后的 JSONMAPPER.writeValueAsString(principal)即端点收到的 body 就是一个 JSON 格式的主体信息对象包含id、attributes等字段默认请求头Content-Type: application/json自定义请求头配置的headers会被追加到请求中且会覆盖 CAS 预置的同名头Basic 认证若配置了basicAuthUsername/basicAuthPassword请求会自动附带 HTTP Basic 认证信息重试请求失败时按maximumRetryAttempts进行重试0 或负数表示不重试。也就是说外部端点可以基于 Principal 中的id用户名和attributes属性如部门、角色、风险评分做任意的账号状态判断并最终通过 HTTP 状态码把结论回传给 CAS。三、响应码语义映射外部接口如何“说话”REST 端点返回的 HTTP 状态码会被 CAS 翻译为具体的账号异常类型这是整个策略的核心契约。原文档给出的映射表如下且与源码中handleResponseStatusCode方法RestfulAuthenticationPolicy.java的实现完全一致HTTP 状态码触发结果源码中的异常类型200认证成功策略满足AuthenticationPolicyExecutionResult.success()403、405账号被禁用AccountDisabledException401登录失败FailedLoginException404账号不存在AccountNotFoundException423账号被锁定AccountLockedException412账号已过期AccountExpiredException428密码必须修改AccountPasswordMustChangeException其他任意状态码登录失败未知状态码FailedLoginException3.1 异常被抛出后的处理路径值得说明的是源码并不是直接返回异常对象而是在非200时把对应异常包装为GeneralSecurityException抛出if (statusCode ! HttpStatus.OK) { val ex handleResponseStatusCode(statusCode, principal); throw new GeneralSecurityException(ex); }随后这些账号级异常会进入 CAS 的 Webflow 异常处理链。以CasCoreWebflowConfigurationCasCoreWebflowConfiguration.java和AuthenticationExceptionHandlerAction为代表的处理机制会把这些异常映射到具体的登录错误页面与提示信息如“账号已禁用”“账号已锁定”“密码已过期”等最终呈现在登录表单上。也就是说外部端点不需要返回任何业务报文仅凭状态码即可驱动 CAS 展示对应的账号状态错误。注意文档表格中未单列401但源码明确将UNAUTHORIZED映射为FailedLoginException“Could not authenticate account for …”上表已据源码补全。同理423在源码中对应LOCKEDAccountLockedException、412对应PRECONDITION_FAILEDAccountExpiredException、428对应PRECONDITION_REQUIREDAccountPasswordMustChangeException与文档完全吻合。四、底层实现原理调用链与关键代码解读4.1 策略执行入口RestfulAuthenticationPolicy.isSatisfiedBy(...)是策略判定的唯一入口其执行流程如下RestfulAuthenticationPolicy.java空值保护若传入的Authentication为null直接返回failure()并记录告警日志序列化主体通过JacksonObjectMapperFactory构建的ObjectMapper关闭 default typing把 Principal 序列化为 JSON 字符串组装请求使用HttpExecutionRequest.builder()设置 URL、Basic 认证、POST方法、JSON 实体、请求头与最大重试次数发送请求调用HttpUtils.execute(exec)执行请求判定结果将响应码转换为HttpStatus200返回success()否则映射为对应账号异常并抛出GeneralSecurityException资源释放在finally块中通过HttpUtils.close(response)关闭响应。4.2 配置可见性该类还实现了toConfiguration()方法把url、basicAuthUsername、basicAuthPassword、maximumRetryAttempts、headers等关键配置以 Map 形式暴露供 CAS 的配置审计、端点信息展示等机制使用RestfulAuthenticationPolicy.java。4.3 与其他策略的组合cas.authn.policy.rest定义于AuthenticationPolicyProperties的rest列表中与groovy、any、all、notPrevented、uniquePrincipal、requiredAttributes等策略并列AuthenticationPolicyProperties.java。CAS 的CoreAuthenticationUtils.newAuthenticationPolicy(props)会将这些配置统一装配为AuthenticationPolicy实例集合REST 策略只是其中一种可组合的判定单元。五、测试用例佐证响应码映射的行为验证仓库中的单元测试 RestfulAuthenticationPolicyTests.java 使用内嵌MockWebServer完整验证了各状态码与异常类型的对应关系可作为对接外部端点时的行为基准assertPolicyFails(9201, HttpStatus.UNAUTHORIZED, FailedLoginException.class); assertPolicyFails(9202, HttpStatus.LOCKED, AccountLockedException.class); assertPolicyFails(9203, HttpStatus.METHOD_NOT_ALLOWED, AccountDisabledException.class); assertPolicyFails(9204, HttpStatus.FORBIDDEN, AccountDisabledException.class); assertPolicyFails(9205, HttpStatus.NOT_FOUND, AccountNotFoundException.class); assertPolicyFails(9206, HttpStatus.PRECONDITION_FAILED, AccountExpiredException.class); assertPolicyFails(9207, HttpStatus.PRECONDITION_REQUIRED, AccountPasswordMustChangeException.class); assertPolicyFails(9208, HttpStatus.INTERNAL_SERVER_ERROR, FailedLoginException.class);同时verifyAllowedOperation()验证了端点返回200时策略判定成功。此外CoreAuthenticationUtilsTests.java 中的verifyAuthnPolicyRest()验证了RestAuthenticationPolicyProperties能被正确装配并完成序列化。这些测试从侧面确认只要端点按上述状态码契约响应CAS 侧的异常映射即告成立。六、外部端点实现示例伪代码/参考实现以下给出一个兼容 CAS REST 认证策略契约的参考端点实现以 Java Spring 为例仅作示意RestController public class AuthenticationPolicyController { PostMapping(value /api/authn/policy, consumes MediaType.APPLICATION_JSON_VALUE, produces MediaType.APPLICATION_JSON_VALUE) public ResponseEntityVoid checkAccountPolicy(RequestBody Principal principal) { String userId principal.getId(); Account account accountService.findByUserId(userId); if (account null) { // 账号不存在 → CAS 抛出 AccountNotFoundException return ResponseEntity.status(HttpStatus.NOT_FOUND).build(); } if (account.isDisabled()) { // 账号禁用 → CAS 抛出 AccountDisabledException return ResponseEntity.status(HttpStatus.FORBIDDEN).build(); } if (account.isLocked()) { // 账号锁定 → CAS 抛出 AccountLockedException return ResponseEntity.status(HttpStatus.LOCKED).build(); } if (account.isExpired()) { // 账号过期 → CAS 抛出 AccountExpiredException return ResponseEntity.status(HttpStatus.PRECONDITION_FAILED).build(); } if (account.isPasswordExpired()) { // 密码必须修改 → CAS 抛出 AccountPasswordMustChangeException return ResponseEntity.status(HttpStatus.PRECONDITION_REQUIRED).build(); } // 一切正常 → 认证成功 return ResponseEntity.ok().build(); } }实现时需注意不要自定义业务响应码只有文档与源码列出的状态码会被正确映射其他状态码一律落入FailedLoginException请求体是 JSON 序列化的 Principal端点应使用 JSON 反序列化来读取id与attributes状态码优先于报文CAS 不解析响应体内容异常提示信息由 CAS 端模板与国际化资源决定。七、常见问题与排查建议端点总是返回登录失败FailedLoginException检查端点返回的状态码是否落入了上表未覆盖的范围同时确认url配置正确、端点可达以及maximumRetryAttempts未导致请求被过度重试。自定义请求头未生效headers中的键值会覆盖 CAS 预置头确认 YAML/Properties 中 Map 写法无误如headers.X-Environmentprod。REST 端点受 Basic 认证保护务必配置basicAuthUsername/basicAuthPassword否则端点返回401会被映射为FailedLoginException而非预期的账号异常。策略未生效检查enabled: true是否显式设置并确认cas.authn.policy.rest的列表项缩进/下标与配置格式一致。八、相关文档与源码索引策略总览Configuring-Authentication-Policy.md其中 REST 策略为一行入口认证组件总览Configuring-Authentication-Components.md策略实现RestfulAuthenticationPolicy.java配置模型RestAuthenticationPolicyProperties.java、BaseRestEndpointProperties.java、AuthenticationPolicyProperties.java策略接口AuthenticationPolicy.java单元测试RestfulAuthenticationPolicyTests.java、CoreAuthenticationUtilsTests.java赞分享后端认证鉴权单点登录【免费下载链接】casApereo CAS - Identity Single Sign On for all earthlings and beyond.项目地址https://gitcode.com/gh_mirrors/ca/cas点击查看免费下载相关推荐Apereo CAS 基于 Groovy 脚本的认证策略Authentication Policy配置指南Apereo CAS 基于 Groovy 脚本的认证策略Authentication Policy配置指南 导读 本文围绕 Apereo CAS 的 cas后端认证鉴权单点登录Apereo CAS 必选属性认证策略Required Attributes Authentication Policy配置指南Apereo CAS 必选属性认证策略Required Attributes Authentication Policy配置指南 导读 在 Apereo C后端认证鉴权单点登录Apereo CAS Required 认证策略Required Authentication Policy详解与源码实现Apereo CAS Required 认证策略Required Authentication Policy详解与源码实现 导读 本文围绕 Apereo C后端认证鉴权单点登录创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考