README

一个 Laravel 应用的 CAS (Central Authentication Service) 客户端 Composer 包,为已有 Laravel 项目提供 SSO 单点登录 与 SLO 单点登出 接入能力,默认与 lyn-huang/laravel-cas-server 配套使用,同时也兼容任何标准 CAS 2.0 / 3.0 协议的服务器。

✨ 功能特性

🔐 SSO 单点登录 — 整页跳到 CAS 服务器,一次登录多个应用共享会话
🔄 SLO 单点登出 — 一处登出,通过 SAML 风格的回调广播到所有客户端
🎫 协议兼容 — CAS 2.0 / 3.0,JSON / XML 双响应格式,4 种校验端点
🛡️ 中间件鉴权 — cas.auth 中间件 + 3 种可插拔认证适配器(Guard / Header / Attribute)
🔌 契约可替换 — UserResolver / ResponseBuilder / AuthStateChecker 三大契约,改 config 一行就能切换实现
📢 事件体系 — 6 个细粒度事件,业务方可监听做埋点 / 审计 / 通知
🎨 双响应模式 — redirect 模式给后端渲染,json 模式给前后端分离
📦 Laravel 风格 — ServiceProvider + Facade + Middleware + Artisan 命令,接入自然

📋 环境要求

依赖	版本
PHP	^7.4 \|\| ^8.0
Laravel	^8.0 \|\| ^9.0 \|\| ^10.0 \|\| ^11.0
guzzlehttp/guzzle	^6.5 \|\| ^7.0 \|\| ^8.0

无需数据库迁移,无内置路由,无内置 Controller — 包只提供"能力",业务方自己决定怎么用。

⚡ 快速安装

# 1. 安装
composer require lyn-huang/laravel-cas-client

# 2. 发布配置 + 接入示例 stub
php artisan cas-client:install

# 3. 配置 .env
# CAS_SERVER=https://cas.example.com
# CAS_SERVICE=https://app.example.com/cas/callback
# CAS_RESPONSE_MODE=json

# 4. 在业务路由里调一行 CasManager

详细步骤见 01 · 快速安装。

🚀 快速开始

最小接入代码(在 routes/web.php 或 routes/api.php 里):

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use LynHuang\LaravelCasClient\Services\CasManager;

Route::get('/cas/callback', function (Request $request, CasManager $casManager) {
    $result = $casManager->handleCallback($request->query('ticket'));

    // ↓ 在这里由业务方自行决定如何落地登录态
    // Auth::loginUsingId($result['resolved_user']['id']);

    return response()->json($result);
});

Route::get('/profile', function () {
    return '受保护内容';
})->middleware('cas.auth');

回调成功后 handleCallback() 会返回 resolved_user / context / logout_url / record_client_token_url, 业务方拿到这些数据后,自己决定写 Auth::login() / Sanctum / JWT / 自定义 token。包不默认执行登录态落地 — 这是核心设计边界。

🎯 核心定位

本包是"协议处理层",不是"业务登录态层"。

┌────────────────────────────────────────────────────────┐
│  你的应用 (Laravel 业务系统)                              │
│  - 自己的用户表 / 自己的 token 体系 / 自己的 session     │
│  - 用本包"调远端 CAS 校验 ticket → 拿用户信息"          │
│  - 自己决定把用户信息落地成什么形态 (Auth/Sanctum/JWT)   │
└──────────────────┬─────────────────────────────────────┘
                   │ 整页跳(协议要求)
┌──────────────────▼─────────────────────────────────────┐
│  CAS 服务器 (laravel-cas-server 或任意 CAS 实现)        │
│  - 统一身份认证 (登录页 + Cookie 会话)                   │
│  - 签发一次性 ticket 给客户端                            │
│  - SLO 通知所有客户端清理本地会话                        │
└────────────────────────────────────────────────────────┘

关键认知:

本包不替换你的用户表 — 用户数据还在你那
本包不接管你的登录态 — 你继续用 Auth / Sanctum / JWT
本包只做"协议处理":拼 URL、调 serviceValidate、解析响应、派发事件
业务方拿到 resolved_user 后自己决定写 session / token — 5 行代码的事

📚 使用文档

章节	内容
01 · 快速安装	环境要求、安装步骤、.env 速查、验证安装
02 · 配置解读	全部配置项详解,含协议 / 适配器 / 绑定说明
03 · SSO 单点登录	主流程、4 种适配器、协议增强参数、单次覆盖
04 · SLO 单点登出	登出动作、SLO 回调、record-client-token 登记
05 · 自定义与扩展	替换 UserResolver / ResponseBuilder / AuthStateChecker
06 · 事件体系	6 个事件详解 + Listener 实战
07 · CAS 协议参考	端点 URL、请求/响应结构、协议字段
08 · 错误码 / 动作码	15 个统一错误码 + 7 个动作码
09 · 故障排查	Q&A、诊断步骤、已知限制
10 · SPA 应用接入指南	Vue/React SPA 接入方案,后端路由 + 前端代码 + SLO 实时性

📦 包结构

laravel-cas-client/
├── config/cas-client.php       # 全部配置项
├── src/
│   ├── CasClientServiceProvider.php   # Laravel 服务提供者(入口)
│   ├── Facades/CasClient.php          # Facade 静态入口
│   ├── Commands/InstallCommand.php    # artisan cas-client:install
│   ├── Http/Middleware/CasAuthenticate.php   # cas.auth 中间件
│   ├── Services/
│   │   ├── CasManager.php              # 主编排器
│   │   ├── CasTicketValidator.php      # Ticket 校验
│   │   ├── CasUrlGenerator.php         # URL 生成
│   │   ├── CasProtocolResponseParser.php   # JSON/XML 解析
│   │   ├── CasUserResolver.php         # 本地用户解析
│   │   ├── AuthStateManager.php        # 认证状态路由器
│   │   ├── GuardAuthStateChecker.php   # Guard 适配器(默认)
│   │   ├── RequestHeaderAuthStateChecker.php   # Header 适配器
│   │   ├── RequestAttributeAuthStateChecker.php # Attribute 适配器
│   │   ├── CasSessionRecorder.php      # 客户端会话登记
│   │   ├── CasSloService.php           # SLO 服务
│   │   └── CasStateRepository.php      # 状态仓库
│   ├── Contracts/                # 3 个可替换契约
│   ├── Enums/                    # ErrorCode / ActionCode / ResponseMode
│   ├── Events/                   # 6 个事件
│   ├── Exceptions/               # 4 个异常
│   ├── Parsers/                  # 协议响应解析
│   ├── Responses/                # 默认 ResponseBuilder
│   └── Support/CasUser.php       # 远端用户 DTO
├── stubs/http-integration.stub.php   # artisan install 拷贝的接入示例
├── examples/demo.env.example    # 完整 .env 模板
├── tests/                       # PHPUnit 测试
├── docs/                        # 本文档
└── docs/architecture.html       # 架构可视化页面

🤝 与 laravel-cas-server 配套

你需要	用这个包
部署 SSO 用户中心	`lyn-huang/laravel-cas-server`
接入已有 Laravel 应用	`lyn-huang/laravel-cas-client` ← 你在这

📄 License

MIT

lyn-huang / laravel-cas-client

Maintainers

Package info

Statistics

Security