🎓 云南大学 CAS RESTful 对接文档

📋 快速导航

一、标准 CAS RESTful 协议

1.1 什么是 CAS

CAS（Central Authentication Service，中央认证服务）是 Yale 大学发起的企业级单点登录（SSO）协议。RESTful 版本主要用于非浏览器客户端（如移动 App、单页应用、后端服务）。

1.2 核心票据类型

CAS 协议的核心是基于票据（Ticket）的认证机制。票据是由 CAS 服务器颁发的临时凭证，用于在客户端和应用服务之间传递认证信息，避免直接传输用户密码。

1.3 标准 RESTful 认证流程

1.4 标准接口端点

1.5 标准接口示例

获取 TGT：

curl -X POST https://cas.example.com/cas/v1/tickets \
  -d "username=zhangsan" \
  -d "password=secret123"

获取 ST：

curl -X POST https://cas.example.com/cas/v1/tickets/TGT-xxx \
  -d "service=https://app.example.com"

验证 ST：

curl "https://cas.example.com/cas/p3/serviceValidate?service=https://app.example.com&ticket=ST-yyy"

二、云南大学 CAS 认证流程

2.1 与标准 CAS 的差异

云南大学采用金智教育 CIAP7.0 平台，在标准 CAS 协议基础上做了安全扩展：

2.2 服务器地址

云南大学 CAS 系统包含两个服务器，不同接口需要使用不同的服务器：

2.3 核心票据

2.4 标准认证流程（5步）

2.5 快速集成流程（2步）

适用于移动端 App、后端服务等不需要 SSO 的场景：

2.6 AES 加密要求

2.7 接口清单

三、使用测试工具

3.1 下载安装

无需安装任何依赖！直接从 Releases 下载对应平台的可执行文件：

Windows 用户：

# PowerShell
Invoke-WebRequest -Uri "https://github.com/na57/cas-restful-test/releases/latest/download/ynu-cas-test-windows-amd64.exe" -OutFile "ynu-cas-test.exe"

# 运行
.\ynu-cas-test.exe

macOS 用户：

# 下载
curl -L "https://github.com/na57/cas-restful-test/releases/latest/download/ynu-cas-test-darwin-amd64" -o ynu-cas-test
chmod +x ynu-cas-test

# 运行
./ynu-cas-test

Linux 用户：

# 下载
curl -L "https://github.com/na57/cas-restful-test/releases/latest/download/ynu-cas-test-linux-amd64" -o ynu-cas-test
chmod +x ynu-cas-test

# 运行
./ynu-cas-test

3.2 从源码编译

git clone https://github.com/na57/cas-restful-test.git
cd cas-restful-test
go build -o ynu-cas-test .
./ynu-cas-test

3.3 命令行配置

测试工具提供了便捷的命令行配置功能，无需手动编辑配置文件：

查看帮助：

./ynu-cas-test help

生成初始配置文件：

./ynu-cas-test configure init

该命令会生成一个包含默认值的配置文件模板 config.yaml，您可以直接编辑该文件填写必要信息。

交互式配置：

./ynu-cas-test configure

通过交互式问答方式配置所有参数，支持以下特性：

• 如果配置文件已存在，会保留现有值作为默认值
• 直接回车使用默认值
• 单选项配置项（如测试模式、布尔选项）通过选择方式配置，无需输入

交互式配置示例：

📝 检测到现有配置文件，将保留现有值（直接回车使用默认值）

════════════════════════════════════════════════════════════
CAS服务器配置
════════════════════════════════════════════════════════════
认证服务器地址 [https://ids.ynu.edu.cn]: 
网关服务器地址 [https://gateway.ynu.edu.cn]: 

════════════════════════════════════════════════════════════
测试选项
════════════════════════════════════════════════════════════

测试模式
  [1] quick - 快速集成（2步）
  [2] standard - 标准流程（4步） ✓
请选择 [1-2] (默认: 2): 

是否在测试后登出
  [1] 是 - 测试后销毁TGT ✓
  [2] 否 - 保留TGT
请选择 [1-2] (默认: 1): 

显示详细请求信息
  [1] 是 - 显示详细请求信息 ✓
  [2] 否 - 只显示关键信息
请选择 [1-2] (默认: 1): 

✅ 配置文件已保存: config.yaml

3.4 手动配置

您也可以手动创建配置文件：

# 复制示例配置文件
cp config.example.yaml config.yaml

# 编辑 config.yaml
vim config.yaml

配置文件说明：

# CAS服务器配置
cas:
  # 认证服务器地址（仅用于验证ST）
  # 接口: /authserver/serviceValidate
  authHost: "https://ids.ynu.edu.cn"
  
  # 网关服务器地址（用于获取accessToken、TGT、ST、销毁TGT、快速获取用户信息）
  # 接口: 
  #   - /token/gateway/{appId}/accessToken (获取accessToken)
  #   - /authserver/v1/tickets (获取TGT)
  #   - /authserver/v1/tickets/{TGT} (获取ST、销毁TGT)
  #   - /authserver/v1/users (快速获取用户信息)
  gatewayHost: "https://gateway.ynu.edu.cn"

# 应用配置（从管控台获取）
app:
  appId: "你的应用ID"
  appSecret: "你的应用密钥"
  serviceUrl: "http://127.0.0.1/"

# AES加密配置（从管控台获取）
aes:
  key: "16字节AES密钥"
  iv: "16字节AES向量"

# 测试账号
test:
  username: "学号/工号"
  password: "密码"

# 测试选项
options:
  mode: "standard"    # "standard"(5步) 或 "quick"(2步)
  logout: true        # 最后是否销毁TGT
  verbose: true       # 是否显示详细请求信息

3.5 测试模式

标准流程（5步）：

options:
  mode: "standard"

快速集成（2步）：

options:
  mode: "quick"

3.6 输出示例

🚀 云南大学CAS认证测试工具

════════════════════════════════════════════════════════════
║ 云南大学CAS认证测试 - 标准流程
════════════════════════════════════════════════════════════
应用ID         : 1242483802708951040
测试用户       : 20080081
网关服务器     : https://gateway.ynu.edu.cn
认证服务器     : https://ids.ynu.edu.cn

[1/5] 获取accessToken
──────────────────────────────────────────────────
✅ 获取accessToken成功
Token          : 95eb04941302f98de86750a414a450f7...
有效期         : 2小时

[2/5] 获取TGT（票据授权票据）
──────────────────────────────────────────────────
✅ 获取TGT成功
TGT            : TGT-1-GC3mATQc9B8cslPImdF-r4-8M4E...

[3/5] 获取ST（服务票据）
──────────────────────────────────────────────────
✅ 获取ST成功
ST             : ST-4-cLnYlmqkNIfMXi0wGm0MMWn0r1c...
有效期         : 30秒（一次性使用）

[4/5] 验证ST并获取用户信息
──────────────────────────────────────────────────
✅ 验证ST成功，获取用户信息
用户ID         : 20080081

📋 用户属性:
   cn             : 张三
   sn             : 20080081
   mail           : [email protected]
   department     : 信息学院

[5/5] 登出（销毁TGT）
──────────────────────────────────────────────────
✅ TGT已销毁，登出成功

════════════════════════════════════════════════════════════
║ ✅ 测试完成
════════════════════════════════════════════════════════════

四、常见问题

4.1 获取 accessToken 返回错误

原因：appId 或 appSecret 错误

解决：核对管控台的凭据

4.2 获取 TGT 返回 400

原因：密码未正确加密或账号异常

解决：

• 确保 AES 密钥和 IV 都是 16 字节
• 检查密码加密是否正确
• 联系管理员确认账号状态

4.3 验证 ST 返回 INVALID_TICKET

原因：ST 只有 30 秒有效期且只能使用一次

解决：获取 ST 后立即验证，不要重复使用

4.4 accessToken 频繁被拦截

原因：调用过频

解决：缓存 token，2 小时内复用

📚 相关资源

• 测试工具源码
• 预编译版本下载
• CAS 协议规范
• CAS RESTful API
• AES 在线加密工具