# SSO 统一登录接入指南

> 基于 usercenter、personal-blog、www 三个项目的实际落地经验整理。  
> 新项目接入 SSO 只需按本文档操作，预计 30 分钟内完成。

---

## 一、架构概览

```
                    ┌─────────────────────────┐
                    │     SSO 中心 :9000       │
                    │  (usercenter/app.py)     │
                    │                         │
                    │  职责：                  │
                    │  · 登录页 UI             │
                    │  · 验证账号密码           │
                    │  · 签发 JWT → 种 Cookie   │
                    │  · 修改密码 / 退出        │
                    └────────┬────────────────┘
                             │ Cookie: access_token
                             │ Domain=129.211.173.87
                             │ SameSite=Lax; HttpOnly
                             │
              ┌──────────────┼──────────────┐
              │              │              │
    ┌─────────▼──────┐ ┌────▼────────┐ ┌──▼───────────┐
    │  blog :8888    │ │ www :80     │ │ 新项目 :XXXX │
    │  :8889(后端)   │ │ :8887(后端) │ │              │
    └────────────────┘ └─────────────┘ └──────────────┘
```

**核心思路：同 IP 跨端口共享 Cookie**

- 所有服务跑在同一台机器 `129.211.173.87`，不同端口
- SSO 登录成功后，种下 `Domain=129.211.173.87` 的 Cookie
- 浏览器对同 IP 不同端口的请求会自动携带该 Cookie
- 各业务后端 **本地验签** JWT（共享 SECRET_KEY），无需每请求调 SSO 接口

---

## 二、环境约束与前提

| 项目 | 值 |
|------|-----|
| 服务器 IP | `129.211.173.87` |
| 协议 | HTTP（无 HTTPS） |
| SSO 中心端口 | `9000` |
| Cookie 域 | `129.211.173.87` |
| Cookie SameSite | `Lax`（同 IP 跨端口足够，`None` 需 HTTPS） |
| JWT 算法 | HS256 |
| 默认账号 | `admin / abcd1234` |

**关键约束：**

1. **HTTP 下不能用 `SameSite=None`** —— `None` 要求配 `Secure` 属性，而 `Secure` 要求 HTTPS，我们没 HTTPS
2. **同 IP + `SameSite=Lax` 即可跨端口共享** —— 浏览器把不同端口视为同站点
3. **跨顶级域名（a.com vs b.com）不适用此方案** —— 那种需要 OAuth2/OIDC 重定向流程

---

## 三、SSO 中心说明

### 3.1 目录结构

```
usercenter/
├── app.py           # FastAPI 主服务
├── sso_config.py    # 共享配置（SECRET_KEY、Cookie 属性等）
├── database.py      # SQLAlchemy + SQLite
├── models.py        # User 表
├── static/
│   └── login.html   # 登录页
├── sso.db           # 用户数据库（自动生成）
└── docs/            # 文档
```

### 3.2 关键 API

| 接口 | 方法 | 说明 |
|------|------|------|
| `/` | GET | 登录页，已登录则跳转 redirect 参数地址 |
| `/api/login` | POST | 表单登录，种 Cookie，返回 JSON |
| `/api/logout` | POST | 清除 Cookie |
| `/api/userinfo` | GET | 读取 Cookie 返回 `{"username":"admin"}` |
| `/api/validate` | GET | 同 userinfo，供业务系统可选调用 |
| `/api/change-password` | POST | 修改密码，成功后清 Cookie 要求重新登录 |

### 3.3 登录流程时序

```
用户                业务前端              SSO 中心              业务后端
 │                    │                    │                    │
 │  点击"SSO登录"     │                    │                    │
 │───────────────────>│                    │                    │
 │                    │  跳转 :9000/        │                    │
 │                    │  ?redirect=回调地址  │                    │
 │                    │───────────────────>│                    │
 │                    │                    │                    │
 │  输入账号密码       │                    │                    │
 │───────────────────────────────────────>│                    │
 │                    │                    │                    │
 │                    │   POST /api/login   │                    │
 │                    │   (表单提交)         │                    │
 │                    │───────────────────>│                    │
 │                    │                    │ 验证密码            │
 │                    │                    │ 签发 JWT            │
 │                    │                    │ 种 Cookie           │
 │                    │                    │ ◄────────────────── │
 │                    │  302 跳转回业务前端  │                    │
 │                    │◄───────────────────│                    │
 │                    │                    │                    │
 │  浏览器自动带Cookie访问业务页面           │                    │
 │───────────────────>│                    │                    │
 │                    │  AJAX withCredentials│                   │
 │                    │────────────────────────────────────────>│
 │                    │                    │   读Cookie→验JWT    │
 │                    │                    │   ← 返回用户信息     │
 │                    │◄────────────────────────────────────────│
```

---

## 四、新项目接入步骤

### 步骤 1：复制 SSO 验签模块

把 `sso_client.py` 复制到新项目后端目录：

```python
# sso_client.py — 与 SSO 中心共享 SECRET_KEY
from fastapi import Request, HTTPException
from jose import jwt, JWTError

SECRET_KEY = "your-secret-key-change-in-production"  # 必须与 sso_config.py 一致
ALGORITHM = "HS256"

def get_current_user_from_cookie(request: Request) -> dict:
    """从请求 Cookie 中读取 access_token，本地验签后返回用户信息"""
    token = request.cookies.get("access_token")
    if not token:
        return None
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username: str = payload.get("sub")
        if not username:
            return None
        return {"username": username}
    except JWTError:
        return None
```

**⚠️ SECRET_KEY 必须与 `usercenter/sso_config.py` 完全一致，否则验签失败。**

### 步骤 2：后端接入认证

根据项目情况选择模式：

#### 模式 A：纯 SSO 认证（新项目推荐）

项目本身无独立登录体系，完全依赖 SSO Cookie：

```python
from fastapi import FastAPI, Request, HTTPException, Depends
from sso_client import get_current_user_from_cookie

app = FastAPI()

def require_sso(request: Request) -> str:
    """SSO 必须登录，返回 username"""
    user = get_current_user_from_cookie(request)
    if not user:
        raise HTTPException(401, "未登录，请先访问 SSO 中心登录")
    return user["username"]

# 无需登录的接口
@app.get("/api/public")
def public_api():
    return {"msg": "所有人可访问"}

# 需要登录的接口
@app.post("/api/protected")
def protected_api(username: str = Depends(require_sso)):
    return {"msg": f"你好, {username}"}

@app.delete("/api/protected/{id}")
def delete_api(id: str, username: str = Depends(require_sso)):
    return {"msg": f"{username} 删除了 {id}"}
```

**实际案例：** `www/server.py` 就是这种模式，`require_sso` 作为 `Depends` 注入到写操作接口。

#### 模式 B：双模式认证（已有独立登录的项目）

项目有自己本地账号体系，SSO 作为额外入口：

```python
from fastapi import APIRouter, Depends, HTTPException, status, Request
from fastapi.security import OAuth2PasswordBearer
from sso_client import get_current_user_from_cookie

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/auth/login", auto_error=False)

async def get_current_user(
    request: Request,
    token: str = Depends(oauth2_scheme),
    db: Session = Depends(get_db)
):
    """双模式认证：Bearer Token 优先 → SSO Cookie 兜底"""
    username = None

    # 模式一：原有 Bearer Token（本地登录）
    if token:
        try:
            payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
            username = payload.get("sub")
        except JWTError:
            pass

    # 模式二：SSO Cookie
    if not username:
        sso_user = get_current_user_from_cookie(request)
        if sso_user:
            username = sso_user.get("username")

    if not username:
        raise HTTPException(401, "无法验证凭据")

    # 查本地用户表
    user = db.query(User).filter(User.username == username).first()
    if not user:
        raise HTTPException(401, "用户不存在")
    return user
```

**实际案例：** `personal-blog/backend/routers/auth.py` 的 `get_current_admin` 就是这种模式。

**双模式要点：**
- `OAuth2PasswordBearer` 必须设 `auto_error=False`，无 Header 时返回 `None` 而非抛异常
- SSO 用户必须在本地用户表中有对应记录（如 blog 的 Admin 表），否则查不到会 401
- 退出登录时同时清除本地 token 和 SSO Cookie：

```python
@router.post("/logout")
def logout(response: Response):
    response.delete_cookie("access_token", domain="129.211.173.87", path="/")
    return {"message": "退出成功"}
```

### 步骤 3：配置 CORS

后端必须允许 SSO 中心域名的跨域请求，且必须开启 `allow_credentials=True`：

```python
from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "http://129.211.173.87",        # nginx 反代
        "http://129.211.173.87:8888",    # blog 前端
        "http://129.211.173.87:9000",    # SSO 中心
        "http://129.211.173.87:XXXX",    # ← 新项目前端端口
    ],
    allow_credentials=True,   # ← 必须！否则 Cookie 不会随跨域请求发送
    allow_methods=["*"],
    allow_headers=["*"],
)
```

**⚠️ `allow_origins` 不能用 `["*"]`，与 `allow_credentials=True` 互斥，浏览器会拒绝。**

### 步骤 4：前端接入

#### 4.1 AJAX 配置（必须开 withCredentials）

```javascript
// axios 示例
const api = axios.create({
  baseURL: 'http://129.211.173.87:XXXX/api',
  withCredentials: true,   // ← 关键！跨域请求携带 Cookie
  timeout: 10000,
})

// 如果项目有本地 token，仍然通过 Header 发送（双模式）
api.interceptors.request.use((config) => {
  const token = localStorage.getItem('token')
  if (token) {
    config.headers.Authorization = `Bearer ${token}`
  }
  return config
})
```

**实际案例：** `personal-blog/frontend/src/api/config.js`

#### 4.2 添加 SSO 登录按钮

```javascript
const handleSSOLogin = () => {
  const redirect = window.location.origin + '/admin'  // 登录后回跳地址
  window.location.href = `http://129.211.173.87:9000/?redirect=${encodeURIComponent(redirect)}`
}

// JSX
<Button onClick={handleSSOLogin}>🔐 SSO 统一登录</Button>
```

#### 4.3 自动检测 SSO 登录状态

页面加载时，如果本地无 token，尝试用 SSO Cookie 调后端接口判断是否已登录：

```javascript
useEffect(() => {
  const token = localStorage.getItem('token')
  if (token) {
    navigate('/admin')
    return
  }
  // 无本地 token，尝试 SSO Cookie
  api.get('/auth/me')
    .then(() => navigate('/admin'))
    .catch(() => { /* SSO 也未登录，留在登录页 */ })
}, [])
```

#### 4.4 纯前端页面（无构建工具）的 SSO 检测

如果项目是纯 HTML（如 www/portal），直接用 `fetch` + `credentials`：

```javascript
async function checkSSO() {
  try {
    const res = await fetch('http://129.211.173.87:XXXX/api/userinfo', {
      credentials: 'include'   // ← 等同于 axios 的 withCredentials
    })
    if (res.ok) {
      const data = await res.json()
      return data.username
    }
  } catch (e) {}
  return null
}
```

### 步骤 5：SSO 中心注册新项目的 CORS

编辑 `usercenter/app.py`，在 CORS `allow_origins` 中添加新项目前端地址：

```python
allow_origins=[
    "http://129.211.173.87:8888",
    "http://129.211.173.87:9000",
    "http://129.211.173.87",       # nginx
    "http://129.211.173.87:XXXX",  # ← 新项目
],
```

修改后重启 SSO 中心：

```bash
sudo systemctl restart usercenter
```

### 步骤 6：配置 systemd 服务

```ini
# /etc/systemd/system/your-project.service
[Unit]
Description=Your Project Backend
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/nanocode/your-project
ExecStart=/usr/bin/python3 app.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl daemon-reload
sudo systemctl enable your-project
sudo systemctl start your-project
```

---

## 五、Cookie 配置详解

### 5.1 当前生产配置

```python
# usercenter/sso_config.py
SECRET_KEY = "your-secret-key-change-in-production"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 15      # JWT 有效期 15 分钟

# Cookie 属性
COOKIE_DOMAIN = "129.211.173.87"      # 绑定 IP，跨端口共享
COOKIE_SAMESITE = "Lax"               # HTTP 下只能用 Lax
```

### 5.2 Cookie 种植方式（SSO 中心）

```python
cookie_opts = {
    "key": "access_token",
    "value": jwt_token,
    "domain": "129.211.173.87",  # 关键：绑定 IP 而非端口
    "path": "/",                 # 全站可用
    "httponly": True,            # JS 无法读取，防 XSS
    "samesite": "Lax",           # 同站点跨端口自动携带
    "max_age": 15 * 60,          # 15 分钟
}
response.set_cookie(**cookie_opts)
```

### 5.3 SameSite 三种模式对比

| 值 | 同站跨端口 | 跨站链接跳转 | 跨站 AJAX | 要求 |
|-----|-----------|------------|----------|------|
| Strict | ✅ | ❌ | ❌ | 无 |
| **Lax** | ✅ | ✅（GET） | ❌ | 无 |
| None | ✅ | ✅ | ✅ | 必须配 Secure，即 HTTPS |

**我们的场景**：同 IP 跨端口 = 同站，`Lax` 足够。跨站 AJAX（如 SSO 中心调业务后端）走的是服务端到服务端，Cookie 在浏览器端随页面请求携带，不涉及跨站 AJAX。

---

## 六、已接入项目清单

| 项目 | 前端端口 | 后端端口 | 认证模式 | 备注 |
|------|---------|---------|---------|------|
| personal-blog | 8888 | 8889 | 双模式（Bearer + Cookie） | 保留原有本地登录 |
| www (Portal) | 80 (nginx) | 8887 | 纯 SSO Cookie | 读写分离，读无需登录 |
| usercenter (SSO) | 9000 | 9000 | 自身 | 登录/注销/改密 |

---

## 七、常见问题排查

### Q1: 后端返回 401 "无法验证凭据"，但浏览器能看到 Cookie

**原因**：SECRET_KEY 不一致，JWT 验签失败。

**排查**：
```bash
# 检查 SSO 中心的 SECRET_KEY
grep SECRET_KEY /home/ubuntu/nanocode/usercenter/sso_config.py

# 检查业务后端的 SECRET_KEY
grep SECRET_KEY /home/ubuntu/nanocode/your-project/sso_client.py
```

两边必须完全一致。

### Q2: Cookie 没有随跨域请求发送

**排查清单**：
1. 后端 CORS 是否 `allow_credentials=True`？
2. 后端 CORS `allow_origins` 是否包含前端地址？（不能用 `*`）
3. 前端 axios 是否 `withCredentials: true`？（fetch 用 `credentials: 'include'`）
4. Cookie 的 `domain` 是否设为 `129.211.173.87`？

### Q3: SSO 登录成功，跳转回来后 Cookie 丢了

**原因**：Cookie `domain` 设成了 `localhost` 或带端口的地址。

**正确**：`domain="129.211.173.87"`（纯 IP，不含端口）

### Q4: 退出 SSO 后，业务系统仍然显示已登录

**原因**：
- 双模式项目：清了 SSO Cookie 但 localStorage 里还有 Bearer token
- 解决：退出时同时清两边的凭证

```javascript
// 前端退出逻辑
async function logout() {
  localStorage.removeItem('token')
  // 同时调 SSO 退出，清除 Cookie
  await fetch('http://129.211.173.87:9000/api/logout', {
    method: 'POST',
    credentials: 'include'
  })
  window.location.href = '/login'
}
```

### Q5: JWT 过期后如何处理？

当前 JWT 有效期 15 分钟，过期后 `jose.jwt.decode` 抛 `JWTError`，后端返回 401。

前端应在 401 拦截器中跳转 SSO 重新登录：

```javascript
api.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      localStorage.removeItem('token')
      // 跳转 SSO 登录
      const redirect = window.location.origin + '/admin'
      window.location.href = `http://129.211.173.87:9000/?redirect=${encodeURIComponent(redirect)}`
    }
    return Promise.reject(error)
  }
)
```

如果 SSO Cookie 也过期，SSO 中心会展示登录页；如果仍有效，会自动跳转回业务页面（秒级体验）。

---

## 八、安全建议（生产环境）

1. **SECRET_KEY**：当前是占位值 `your-secret-key-change-in-production`，上线前必须改为强随机字符串（≥32 字符），且所有项目同步更新
2. **HTTPS**：公网部署建议启用 HTTPS，Cookie 可升级为 `SameSite=None; Secure`
3. **JWT 有效期**：当前 15 分钟偏短，可根据业务调整（SSO 登录页有"记住我"空间）
4. **账号同步**：SSO 用户必须存在于业务系统本地表中，建议通过脚本或初始化逻辑保证
5. **CORS 白名单**：只放实际需要的前端地址，不要用通配符

---

## 九、快速接入 Checklist

新项目接入时，按此清单逐项确认：

- [ ] 复制 `sso_client.py` 到项目后端，SECRET_KEY 与 SSO 中心一致
- [ ] 后端选择认证模式（纯 SSO / 双模式），实现 `Depends` 注入
- [ ] 后端 CORS 添加 `allow_credentials=True` + 前端地址白名单
- [ ] 前端 axios 配置 `withCredentials: true`（或 fetch 用 `credentials: 'include'`）
- [ ] 前端添加 "SSO 统一登录" 按钮，跳转 `:9000/?redirect=回调地址`
- [ ] 前端 401 拦截器处理 SSO 重定向
- [ ] SSO 中心 CORS 白名单添加新项目前端地址
- [ ] 配置 systemd 服务确保后端持久运行
- [ ] curl 端到端测试：`curl -v -b jar http://129.211.173.87:XXXX/api/xxx`
- [ ] 浏览器端到端测试：点击 SSO 登录 → 跳转 → 回跳 → 接口正常

---

*最后更新：2026-05-05，基于 usercenter / personal-blog / www 三个项目的实际代码整理。*