零信任平台Cas协议对接指南

本文档指导第三方应用系统通过 CAS 协议接入零信任平台的 SSO 单点登录服务。
适用于所有需要接入 SSO 单点登录的 Web 应用（包括经过网关的应用和 SaaS 应用直连）。

一、整体架构

1.1 场景选择

请根据你的部署方式选择对应场景：

场景	描述	适用情况
场景一：经过网关	应用部署在网关后面，用户流量经过网关反向代理	内网应用、私有化部署
场景二：SaaS 直连	应用独立部署，用户浏览器直接访问应用域名	SaaS 应用、公网独立部署

两种场景的 API 调用方式完全一致，区别仅在于网络链路是否经过网关。
阅读时请关注与你场景匹配的架构图和流程图即可。

1.2 角色说明

CAS 协议对接涉及以下角色：

角色	说明	示例
资源拥有者	终端用户（在 SSO 上拥有账号）	员工张三
零信任网关（场景一）	反向代理，用户流量经过网关	`gateway.example.com`
SSO 授权服务	CAS 认证中心 (IdP)	`sso.example.com`
应用系统	需要接入 SSO 的第三方 Web 应用	`app.example.com`

1.3 网络架构

场景一：经过网关

                                    ┌──────────────────────────────────┐
                                    │         零信任网关               │
                                    │  ┌────────────────────────────┐  │
  ┌──────────┐     HTTPS            │  │      SSO 授权服务          │  │
  │  用户浏览器 │ ◄──────────────────► │  │   sso.example.com         │  │
  └──────────┘                      │  └────────────────────────────┘  │
                                    │  ┌────────────────────────────┐  │
                                    │  │   应用域名反向代理          │  │
                                    │  │   app.example.com ──► 10.x:8080 │
                                    │  └────────────────────────────┘  │
                                    └──────────────────────────────────┘
                                                    │
                                                    │ 内网
                                                    ▼
                                             ┌─────────────┐
                                             │  应用后端服务  │
                                             │ 10.x.x.x:8080│
                                             └─────────────┘

用户的所有请求都经过零信任网关。网关将 app.example.com 的流量代理到内网的应用后端。

场景二：SaaS 直连（不经过网关）

  ┌──────────┐     HTTPS      ┌─────────────────┐
  │  用户浏览器 │ ◄────────────► │    应用系统       │
  └──────────┘               │ app.example.com  │
       │                      └───────┬─────────┘
       │                              │ HTTPS（后端服务器间通信）
       │     HTTPS                    ▼
       └──────────────────►  ┌─────────────────┐
                             │  SSO 授权服务    │
                             │ sso.example.com  │
                             └─────────────────┘

SaaS 应用直接暴露在公网，用户浏览器直接访问应用域名，不经过零信任网关。
应用后端直接通过 HTTPS 与 SSO 服务通信。

1.4 创建应用与配置

在应用系统对接前，必须先在管理后台完成应用发布并配置正确的接入参数。完整流程如下：

选择资源发布、应用发布：在后台中心进入相关发布模块。

基本配置：根据实际场景，选择对应的应用类型（场景一选择内网应用，场景二选择 SaaS 应用）。

SSO 配置：在 SSO 配置协议中选定 CAS。

填写应用回调地址：填写应用接收 ticket 的地址。（注意： 在应用向 IdP 发起请求时，系统会验证 service 参数中的域名是否和此处配置的应用回调地址中的域名一致）。

二、CAS 协议对接流程

2.1 流程图（场景一：经过网关）

2.2 流程图（场景二：SaaS 直连，不经过网关）

两种场景的核心逻辑相同： 浏览器 302 → SSO 登录认证 → ticket 回调 → 后端验证 ticket → 获取用户信息。
区别仅在于场景一的每一步都经过网关代理，场景二则由浏览器直接与应用/SSO 通信。

2.3 流程分步说明

以下步骤编号对应场景一流程图。场景二的逻辑相同，只是去掉了网关中转。

步骤	发起方	说明
①	用户	用户通过浏览器访问应用域名 `app.example.com`
②③④	应用	应用检测到用户未登录，302 重定向浏览器到 SSO 登录页 `sso.example.com/cas/login?service=...`
⑤～⑧	用户/SSO	用户在 SSO 页面上完成身份认证（输入账号密码等）
⑨～⑫	SSO	认证通过后，SSO 生成 `ticket` 票据，302 重定向回应用的回调地址并携带 `ticket` 参数
⑬⑭	网关/应用	携带 `ticket` 的回调到达应用后端（场景一经网关代理，场景二直达）
⑮	应用后端	后端用 `ticket` + `service` 直接调用 SSO 的 `serviceValidate` 接口验证票据
⑯	SSO	SSO 返回 XML 格式的认证结果，包含用户详细信息
⑰⑱	应用	应用解析 XML 响应中的用户信息，完成本地登录（创建会话、设置 Cookie 等）

核心概念： 步骤 ⑮⑯ 是服务器间通信——应用后端直接请求 SSO 服务的 HTTPS 接口，
ticket 验证过程不经过浏览器，保证了认证的安全性。

CAS 与 OAuth 的关键区别：
CAS 协议不需要 client_id / client_secret，认证凭据更简单
CAS 使用一次性 ticket（而非 code + access_token 两步换取）
CAS 的用户信息在 serviceValidate 接口直接返回 XML 格式（而非 JSON）
CAS 的 service 参数类似于 OAuth 的 redirect_uri，必须与后台配置一致

三、API 接口详细说明

以下 API 两种场景通用，调用方式完全一致。

3.1 获取 ticket 票据

此请求由用户浏览器发起（302 重定向跳转），应用系统引导用户走向 SSO 登录中心。

接口地址： https://sso.example.com/cas/login
请求方式： GET

请求参数：

参数	必填	类型	示例	说明
`service`	✅	string	`https://app.example.com/cas/callback`	应用的回调地址，需要进行 urlencode，系统会验证该地址合法性。

完整请求示例：

https://sso.example.com/cas/login?service=https%3A%2F%2Fapp.example.com%2Fcas%2Fcallback

响应示例：

用户在 SSO 完成认证后，SSO 中心会将请求 302 重定向到配置的 callback 地址，并附带 ticket 票据：

302 重定向到 https://app.example.com/cas/callback?ticket=ST-hd67cYLohcJOiwTUs7ba6HUazO7h

3.2 票据换取用户信息

此请求由应用后端发起，为了确保安全性，应用后端利用收到的 ticket 直接通过服务器之间调用 SSO。

接口地址： https://sso.example.com/cas/serviceValidate
请求方式： GET

请求参数：

参数	必填	类型	示例	说明
`ticket`	✅	string	`ST-hd67cYLohcJOiwTUs7ba6HUazO7h`	传入回调接口中接收到的 ticket 票据
`service`	✅	string	`https://app.example.com/cas/callback`	必须与获取 ticket 时的 service 保持完全一致，且同样需 urlencode

完整请求示例：

https://sso.example.com/cas/serviceValidate?ticket=ST-hd67cYLohcJOiwTUs7ba6HUazO7h&service=https%3A%2F%2Fapp.example.com%2Fcas%2Fcallback

成功响应示例（XML）：

当 ticket 校验成功时，将返回如下 XML 格式包含用户详细信息的响应包：

<cas:serviceResponse xmlns:cas="http://www.yale.edu/tp/cas">
    <cas:authenticationSuccess>
        <cas:user>zhangsan</cas:user>
        <cas:attributes>
            <cas:surname>张</cas:surname>
            <cas:cname>张三</cas:cname>
            <cas:givenname>三</cas:givenname>
            <cas:mail>zhangsan@example.com</cas:mail>
            <cas:mobile>+8619046547896</cas:mobile>
        </cas:attributes>
    </cas:authenticationSuccess>
</cas:serviceResponse>

失败响应示例（XML）：

若 ticket 不存在或已失效，认证中心将返回错误消息：

<cas:serviceResponse xmlns:cas="http://www.yale.edu/tp/cas">
    <cas:authenticationFailure cas:code="INVALID_TICKET">ticket not exist</cas:authenticationFailure>
</cas:serviceResponse>

注意： 解析 XML 后，应用可提取 <cas:user> 或其 attributes 节点的内容与本地账户体系映射，完成最后的单点登录并控制授权访问。

3.3 完成本地登录

获取到用户信息后，应用系统应执行本地登录逻辑：

根据 <cas:user> 中的用户名在本地数据库中查找对应用户

如果用户存在 → 创建本地会话（Session / JWT / Cookie）

如果用户不存在 → 自动创建本地账号，或返回"用户不存在"错误

将浏览器重定向到应用首页或用户之前访问的页面

四、代码示例

📌 代码说明
以下代码示例完整展示了 CAS 协议对接的核心逻辑，可直接用于开发参考。
Java 示例：展示 Spring Boot Controller 核心代码，需在已有 Spring Boot 项目中使用。
Go 示例：完整可运行程序，直接 go run main.go 启动。
Python 示例：完整可运行程序，pip install flask requests 后直接启动。
所有示例中的 sso.example.com、app.example.com 等配置需替换为实际值。
内网环境使用自签证书时，示例已包含跳过 TLS 校验的配置。

4.1 Java（Spring Boot）

4.2 Go

4.3 Python（Flask）

五、SSO 故障逃生机制

⛔ 安全风险警告
启用逃生机制（降级到本地密码登录）意味着绕过了 SSO 的统一认证和多因素验证（MFA）。
这可能带来以下安全风险：
本地账号密码不受零信任策略保护（无 MFA、无设备检查、无地理围栏）
如果本地密码泄露，攻击者可直接登录，不会被 SSO 侧的异常检测拦截
审计日志中将缺少 SSO 登录事件，可能影响安全审计的完整性
使用建议：
1.
逃生机制仅限 SSO 完全不可用时的应急使用，恢复后应立即关闭
2.
本地管理员账号应设置高强度密码并定期轮换
3.
建议记录所有本地登录事件并设置告警，确保逃生期间的操作可审计

当 SSO 服务不可用时（网络故障、SSO 服务宕机等），应用系统需要有降级登录方案，否则所有用户都将无法访问系统。

5.1 设计思路

用户访问 → 检查 SSO 状态 → SSO 可用？
                              ├── 是 → 正常 CAS SSO 登录
                              └── 否 → 降级到本地账号密码登录

5.2 SSO 健康检查

在显示登录页面之前，先探测 SSO 服务是否可用：

建议加缓存： 健康检查结果缓存 60 秒，避免每个用户请求都去探测 SSO：

5.3 前端降级逻辑

5.4 管理后台手动关闭 SSO

在管理后台提供一个"禁用 SSO"开关。当 SSO 故障时，管理员可以：

通过管理后台关闭 SSO（设置 integration_configs.enabled = 0）

或直接操作数据库：

所有用户立即降级为本地账号密码登录

SSO 恢复后，重新启用即可

5.5 保留管理员本地账号

最佳实践： 无论是否启用了 SSO，始终保留至少一个 本地管理员账号（有密码），
确保在 SSO 完全不可用时，仍有人可以登录系统进行故障处理。

六、集成检查清单

在上线前，逐项检查以下内容：

6.1 配置检查

应用已在管理后台完成发布，SSO 配置中已选择 CAS 协议

应用回调地址已正确配置（与代码中 service 参数的域名一致）

后端可以通过 HTTPS 访问 SSO 服务地址（内网需配 DNS 或 hosts）

6.2 代码检查

登录入口正确构建了 sso.example.com/cas/login?service=... 跳转 URL

service 参数已做 URL 编码

回调接口正确从 URL 中提取 ticket 参数

serviceValidate 接口的 service 参数与获取 ticket 时完全一致

XML 响应解析逻辑正确处理了 authenticationSuccess 和 authenticationFailure 两种情况

HTTP 客户端已配置 TLS 证书跳过（内网自签证书）

6.3 安全检查

ticket 验证在后端完成，不暴露给前端 JavaScript

应用已实现会话管理（Session / JWT / Cookie），避免重复 SSO 认证

SSO 故障逃生方案已实现并测试

6.4 测试验证

正常 CAS SSO 登录流程端到端通过

SSO 故障时可降级到本地登录

回调地址 service 不匹配时有明确错误提示

ticket 过期或重复使用时有明确错误处理

日志中记录了完整的 SSO 事件（ticket 验证、用户匹配、登录成功/失败）

七、常见问题（FAQ）

Q1: `serviceValidate` 返回 `INVALID_TICKET` 错误？

排查：

ticket 是一次性的，不能重复使用

ticket 有效期很短，收到后需尽快调用 serviceValidate

service 参数必须与获取 ticket 时完全一致（包含协议、域名、路径、URL 编码）

Q2: SSO 登录页面可以正常显示，但提交后没有回调？

排查：

检查管理后台配置的"应用回调地址"是否正确

确认 service 参数中的域名与后台配置的回调地址域名一致

场景一（经过网关）：检查网关对回调域名的代理配置是否正确

Q3: XML 解析失败？

原因： CAS 使用带命名空间的 XML 响应，解析时需要处理 cas: 前缀。

Java：使用 getElementsByTagName("cas:user") 或配置 namespace-aware 的 DocumentBuilder

Python：使用 ns = {'cas': 'http://www.yale.edu/tp/cas'} 命名空间映射

Go：使用 xml:"authenticationSuccess" 标签（Go 的 xml 包会自动处理命名空间）

Q4: 场景一（经过网关）中，后端验证 ticket 应该直连 SSO 还是经过网关？

回答： serviceValidate 是后端服务器间通信，建议直连 SSO 服务（不经过网关），这样即使网关出现负载问题，后端验证仍能正常工作。确保后端网络可以直达 SSO 服务地址即可。

Q5: CAS 和 OAuth 应该选哪个？

对比：

维度	CAS	OAuth2.0
复杂度	简单（2 步：跳转 + 验 ticket）	较复杂（3 步：跳转 + 换 token + 取用户信息）
凭证管理	无需 `client_id/secret`	需要 `client_id` + `client_secret`
数据格式	XML	JSON
令牌刷新	不支持	支持 `refresh_token`
适用场景	纯 SSO 认证	SSO + API 授权

如果只需要 SSO 单点登录，CAS 更简单；如果还需要 API 授权能力，选择 OAuth2.0。

Q6: SSO 挂了怎么办？

参见第五章"SSO 故障逃生机制"。核心思路：前端先检查 SSO 服务可用性，不可用则降级显示本地登录表单。同时始终保留一个有密码的本地管理员账号。

八、参考资源

零信任平台 OpenSDK — 官方 Java Demo

零信任平台标准 Open API — 完整 API 文档

CAS 协议官方规范 — CAS 协议标准参考

文档版本: v2.0 | 最后更新: 2026-03-17

零信任平台Cas协议对接指南

一、整体架构#

1.1 场景选择#

1.2 角色说明#

1.3 网络架构#

场景一：经过网关#

场景二：SaaS 直连（不经过网关）#

1.4 创建应用与配置#

二、CAS 协议对接流程#

2.1 流程图（场景一：经过网关）#

2.2 流程图（场景二：SaaS 直连，不经过网关）#

2.3 流程分步说明#

三、API 接口详细说明#

3.1 获取 ticket 票据#

3.2 票据换取用户信息#

3.3 完成本地登录#

四、代码示例#

4.1 Java（Spring Boot）#

4.2 Go#

4.3 Python（Flask）#

五、SSO 故障逃生机制#

5.1 设计思路#

5.2 SSO 健康检查#

5.3 前端降级逻辑#

5.4 管理后台手动关闭 SSO#

5.5 保留管理员本地账号#

六、集成检查清单#

6.1 配置检查#

6.2 代码检查#

6.3 安全检查#

6.4 测试验证#

七、常见问题（FAQ）#

Q1: serviceValidate 返回 INVALID_TICKET 错误？#

Q2: SSO 登录页面可以正常显示，但提交后没有回调？#

Q3: XML 解析失败？#

Q4: 场景一（经过网关）中，后端验证 ticket 应该直连 SSO 还是经过网关？#

Q5: CAS 和 OAuth 应该选哪个？#

Q6: SSO 挂了怎么办？#

八、参考资源#