企业官网建设流程全解析

• 后端
• 认证鉴权
• 单点登录

Surrogate 认证（又称模拟/代管认证，即“Web 版 sudo”）允许管理员用户在完成自身凭据校验后，以另一个用户（surrogate 用户）的身份建立单点登录会话。本文聚焦 Apereo CAS 中基于外部 JSON 文件的 Surrogate 账户存储方案，讲解 JSON 文件语法、cas.authn.surrogate.json配置属性、通配符授权、热加载机制与测试验证方式，帮助读者在 WAR overlay 中快速落地一套纯文件式的模拟账户管理方案。

一、JSON 存储在整个 Surrogate 认证体系中的位置

在 CAS 中，Surrogate 认证涉及两个角色：

1. 主用户（primary admin user）：其凭据在认证时被真实校验，是“发起模拟”的人；
2. Surrogate 用户：由主用户在登录后选择，CAS 在校验完主用户凭据后会切换到该身份，并把该身份与单点登录会话绑定。

典型使用场景包括：以某用户身份登录应用执行操作、以某用户身份排查应用认证问题等。

账户存储用于回答“某主用户被允许模拟哪些用户”这一问题。官方文档在 Surrogate-Authentication.md 中列出了 Simple、JSON、LDAP、JDBC、REST、Groovy、Custom 七种存储方式，其中JSON 存储是指把“主用户 → 可模拟用户列表”的映射关系写入一个外部 JSON 文件，由 CAS 配置指定文件路径后动态读取。多个存储可以同时启用、共同参与定位（由ChainingSurrogateAuthenticationService串联），JSON 只是其中之一。

二、JSON 文件语法与完整示例

根据 Surrogate-Authentication-Storage-JSON.md，JSON 文件的顶层是一个对象：键为可发起模拟的主用户 ID，值为该主用户可模拟的 surrogate 用户名数组。官方给出的最小示例如下：

{ "casuser": ["jsmith", "banderson"], "adminuser": ["jsmith", "tomhanks"] }

即：casuser可以模拟jsmith、banderson；adminuser可以模拟jsmith、tomhanks。

仓库自带的真实测试资源 surrogates.json 展示了更完整的形态，还包含一个通配符条目：

{ "casuser": ["jsmith", "banderson"], "casadmin": ["*"], "adminuser": ["jsmith", "tomhanks"] }

其中casadmin: ["*"]表示casadmin拥有特殊权限，可以模拟任意用户（详见下文“通配符授权”一节）。

使用要点：

• 值为空数组[]或文件中不存在的主用户，在查询可模拟账户时会被视为无任何授权（源码中返回空集合）；
• 文件内容必须是合法的 JSON 对象，值必须是字符串数组；
• 同一主用户可以出现在多个键之外，文件本身不要求去重或排序；
• 文件路径通过配置项指定，详见下一节。

三、启用与配置：cas.authn.surrogate.json属性

与 JSON 存储相关的全部配置项以cas.authn.surrogate.json为前缀，核心是location属性，用于指定 JSON 文件的路径。配置示例（application.properties）：

# 指定 surrogate 账户定义文件位置，支持 classpath 与文件系统路径 cas.authn.surrogate.json.location=file:/etc/cas/config/surrogates.json

在测试环境中，官方测试类 JsonResourceSurrogateAuthenticationServiceTests.java 使用 classpath 形式：

cas.authn.surrogate.json.location=classpath:/surrogates.json

从源码看，location 支持两类资源地址：

• file:/absolute/path/surrogates.json：部署环境中的绝对路径文件，推荐生产使用；
• classpath:/surrogates.json：打入 classpath 的资源配置，便于测试与快速验证。

底层装配条件

在 SurrogateAuthenticationConfiguration.java 中，JSON 存储以BeanSupplier形式按条件装配：

• 当cas.authn.surrogate.json.location未配置时，jsonSurrogateAuthenticationService返回null（otherwiseNull()），不启用 JSON 存储；
• 当 location 已配置时，构造JsonResourceSurrogateAuthenticationService并注入到surrogateAuthenticationService聚合链中；
• 该模块整体受@ConditionalOnFeatureEnabled(feature = CasFeatureModule.FeatureCatalog.SurrogateAuthentication)控制。

因此，只需在 overlay 中引入cas-server-support-surrogate-webflow依赖并设置上述 location 属性，即可激活 JSON 账户存储。

四、源码实现：读取、热加载与查询语义

JSON 存储的核心实现类是 JsonResourceSurrogateAuthenticationService.java，它继承自SimpleSurrogateAuthenticationService并实现DisposableBean，整体设计可以归纳为三个要点：

1. Jackson 解析文件为内存 Map

构造函数通过JacksonObjectMapperFactory构建的ObjectMapper把 JSON 文件直接读取为Map<String, List>（MAPPER.readValue(json, Map.class)），并交给父类持有为eligibleAccounts。这意味着 JSON 文件在启动时被一次性载入内存，查询不涉及磁盘 IO。

2. 文件监视器实现无重启热加载

JsonResourceSurrogateAuthenticationService内置了一个FileWatcherService：

this.watcherService = new FileWatcherService(json, this::loadServices); this.watcherService.start(getClass().getSimpleName());

loadServices回调会清空并重读账户 Map：

getEligibleAccounts().clear(); getEligibleAccounts().putAll(readAccountsFromFile(file));

也就是说，修改 JSON 文件后无需重启 CAS，监视器会自动感知文件变更并刷新内存中的授权数据。服务销毁时（destroy()）会关闭监视器。这一机制让运维人员可以随时增删模拟授权而不影响在线会话。

3. 查询语义继承自 Simple 存储

授权判断逻辑位于 SimpleSurrogateAuthenticationService.java：

• canImpersonateInternal(surrogate, principal, service)：若principal.getId()出现在eligibleAccounts中，则判断其值列表是否包含目标 surrogate 用户名；
• getImpersonationAccounts(username, service)：返回该用户名对应的可模拟账户列表，未授权用户返回空列表new ArrayList<>()。

因此 JSON 文件中的键值关系直接决定了“谁可以模拟谁”，查询是纯粹的Map命中判断，简单且高效。

五、通配符授权（*）

SurrogateAuthenticationService接口（接口定义）定义了通配符常量：

String WILDCARD_ACCOUNT = "*";

当某个主用户的值列表仅包含*（即形如"casadmin": ["*"]）时，isWildcardedAccount判定其为通配账户：

default boolean isWildcardedAccount(final Collection<String> accounts, final Optional<? extends Service> service) { return accounts.size() == 1 && accounts.contains(SurrogateAuthenticationService.WILDCARD_ACCOUNT); }

也就是说，列表必须恰好只有一个*元素才被识别为通配授权，casadmin因而可以模拟任意用户。这是 JSON 存储中赋予“超级管理员”能力的最直接手段。

六、模拟会话的认证属性

当一次 Surrogate 认证成功后，CAS 会向应用回传三个属性用于标识“这是一次模拟会话”（见 collectSurrogateAttributes 与 Surrogate-Authentication.md）：

下游应用可依据这些属性识别管理员正在以他人身份操作，从而进行审计或告警。

七、测试验证：仓库如何证明 JSON 存储行为

仓库为 JSON 存储提供了完整的自动化测试，可直接作为行为契约参考：

• 测试类 JsonResourceSurrogateAuthenticationServiceTests.java 通过cas.authn.surrogate.json.location=classpath:/surrogates.json注入配置并装配surrogateAuthenticationServiceBean；
• 共享测试基类 BaseSurrogateAuthenticationServiceTests.java 定义了四类断言场景：
  • 授权通过：casuser能查询到非空的模拟账户列表（对应文件中的jsmith、banderson）；
  • 授权拒绝：unknown-user的模拟账户列表为空；
  • 定向模拟：casuser可模拟banderson，但不能模拟未授权用户（如XXXX），也不能被banderson反向模拟；
  • 通配模拟：casadmin可模拟任意用户，且isWildcardedAccount返回true。

这些测试同时印证了 JSON 键值映射、*通配语义以及未授权用户的空集合行为。

八、REST 协议下的 JSON 存储配合

若启用了 CAS REST 协议（文档说明），Surrogate 认证可扩展到 REST 凭据场景，此时 JSON 存储中的授权关系同样生效，两种传参方式任选其一：

1. 将用户名按[surrogate-userid][分隔符][primary-userid]语法格式化提交；
2. 携带请求头X-Surrogate-Principal，其值为 surrogate 用户名。

换言之，JSON 文件只需维护授权映射，实际的“以谁的身份登录”由客户端在登录请求中指定，并由 CAS 依据 JSON 存储的授权结果校验放行。

九、使用注意事项

• 文件格式严格：JSON 必须是合法对象，解析失败会导致服务启动或热加载失败，建议先本地校验格式；
• 路径权限：采用file:路径时，CAS 进程需对该文件具备读权限，且所在目录需允许监视器访问以完成热加载；
• 多存储并存：JSON、LDAP、JDBC 等存储可同时启用，最终由ChainingSurrogateAuthenticationService按顺序聚合判断，因此 JSON 存储可与现有目录源共存，无需迁移历史授权；
• 通配符语义：*只有在作为列表中唯一元素时才是通配授权，若与其他用户名混用则按普通用户名处理。

综上，JSON 存储以极低的运维成本提供了可热更新的模拟账户管理能力，配合通配符与多存储链，适合中小规模部署或作为临时授权方案的快速落地选择。

• 后端
• 认证鉴权
• 单点登录