添加 sso登录sop.md

This commit is contained in:
chao.wu 2026-11-17 20:13:37 +08:00
parent 1171b004da
commit 1197b29770

224
sso登录sop.md Normal file
View File

@ -0,0 +1,224 @@
# 公司 SSO 网页登录接入 SOP
> 版本 v2.0 · 2026-11-17 · 通用版,适用于任何内部 Web 项目。
> 本文档自包含:只需下表信息即可完成接入,不依赖任何特定项目或代码库。
## 0. 一句话说明
你的网页跳转到公司 SSO 登录页 → 用户登录后 SSO 携 token 回跳你的页面 → 你的后端拿 token 调用户信息接口完成验证 → 之后该用户的请求都带这个 token。
**无需申请 client_id / client_secret,无需注册回调域名**,`redirectUrl` 传你自己的页面地址即可。
## 1. 接入信息
| 项 | 值 |
|---|---|
| SSO 登录页 | `https://sso.d-robotics.cc/` |
| 跳转参数 | `?redirectUrl=<登录成功后回跳的页面URL>`(需 urlencode) |
| 回跳方式 | GET 回跳:`<redirectUrl>?bearer=<token>`;或 POST 表单字段 `bearer` 到 redirectUrl(见 §4) |
| 用户校验 API | `GET https://cloud.d-robotics.cc/api/dcloudUserApi/user/userAndOrg` |
| 校验 API 认证 | 请求头 `Authorization: <token 原样>`(**不加** `Bearer ` 前缀,SSO 给什么传什么) |
| 校验 API 超时 | 建议 10s |
校验 API 返回示例:
```json
// 成功
{"status": 0, "data": {"userId": "...", "userName": "...", "mobile": "...",
"email": "...", "state": "activated", ...}}
// 失败(无 token / token 无效或过期)
{"status": 10002, "message": "token invalidation",
"location": "https://sso.d-robotics.cc", "success": false}
```
**通过条件:HTTP 200 且 `status == 0` 且 `data.state == 'activated'`。** 三者缺一不可;`state` 非 `activated`(如离职/停用账号)应拒绝。可拿到的字段:`userId`(稳定主键)、`userName`、`mobile`、`email`。
## 2. 完整时序
```
浏览器 你的前端 你的后端 sso.d-robotics.cc / cloud.d-robotics.cc
│ 点"SSO登录" │ │ │
├─ location.href ─────────► │ │ │
│ https://sso.d-robotics.cc/?redirectUrl=<你的页面URL> ───────────────────────► │ 用户输公司账号密码
│ │ │ │
│ ◄── 登录成功,携 ?bearer=<token> 回跳你的页面(GET 或 POST,见 §4) │
│ │ │ │
├─ POST /api/user/login {bearer_token} ─────────────► │ │
│ │ GET userAndOrg ─────────────────────────────────► │
│ │ ◄── {status:0, data:{userId,userName,...}} │
│ ◄── 登录成功 + 用户身份 ── │ UPSERT 本地用户表 │ │
│ │ │ │
│ 之后所有 API 带 Authorization: <token>,后端复验(带节流,见 §6) │
```
## 3. 前端接入(完整代码,可直接抄)
```js
const SSO_LOGIN_URL = 'https://sso.d-robotics.cc/';
const TOKEN_KEY = 'sso_bearer_token'; // 自定义你自己的 key
// ① 登录按钮
function redirectToSSO() {
const redirectUrl = window.location.origin + window.location.pathname;
window.location.href = SSO_LOGIN_URL + '?redirectUrl=' + encodeURIComponent(redirectUrl);
}
// ② 页面加载时:捕获回调 token,调后端换身份
async function initAuth() {
const params = new URLSearchParams(location.search);
const bearer = params.get('bearer') || localStorage.getItem(TOKEN_KEY);
if (!bearer) return showLoginPage(); // 显示"SSO 登录"按钮
localStorage.setItem(TOKEN_KEY, bearer);
history.replaceState(null, '', location.pathname); // 顺手把 ?bearer= 从地址栏抹掉
const r = await fetch('/api/user/login', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({ bearer_token: bearer })
});
if (!r.ok) { logout(); return showLoginPage(); }
currentUser = await r.json(); // {user_id, user_name, ...}
}
// ③ 之后所有业务请求统一挂 token(建议封装一个 apiFetch)
async function apiFetch(url, opts = {}) {
const r = await fetch(url, {...opts, headers: {...opts.headers,
'Authorization': localStorage.getItem(TOKEN_KEY) || ''}});
if (r.status === 401) { logout(); showLoginPage(); throw new Error('登录过期'); }
return r;
}
// ④ 登出 = 清本地(SSO 侧会话独立,见 §9)
function logout() { localStorage.removeItem(TOKEN_KEY); }
```
## 4. 回调方式:GET 与 POST 二选一
### 方式 A:GET 回跳(默认,最简单)
SSO 以 `<redirectUrl>?bearer=<token>` 回跳。前端 `initAuth()` 已处理。
缺点:token 会进浏览器历史、服务器 access log、可能的 referer。
### 方式 B:POST 回调 + 中间页(推荐,token 不进历史)
SSO 把 `bearer` 以 POST 表单提交到你的 redirectUrl;你的服务端**不渲染业务页**,而是返回一张中间页,由 JS 写入 localStorage 后跳转:
```html
<!-- 中间页模板(服务端填充 BEARER_JSON) -->
<!DOCTYPE html><html><body><p>登录中,请稍候...</p>
<script>
localStorage.setItem('sso_bearer_token', BEARER_JSON); // BEARER_JSON = json.dumps(token),已转义引号
window.location.replace('/'); // replace 不留历史
</script></body></html>
```
服务端填充时必须做注入防护:`json.dumps(token).replace('</', '<\\/')`,防止 token 值中 `</script>` 逃逸。
## 5. 后端校验(完整代码,可直接抄)
用户表(首次接入先建):
```sql
CREATE TABLE IF NOT EXISTS users (
user_id TEXT PRIMARY KEY, -- SSO userId
user_name TEXT,
mobile TEXT,
email TEXT,
bearer_token TEXT,
last_login_at TEXT,
created_at TEXT
);
```
校验函数(Python / aiohttp 风格,其他语言按注释等价实现):
```python
import aiohttp, sqlite3
from datetime import datetime
SSO_USER_API = "https://cloud.d-robotics.cc/api/dcloudUserApi/user/userAndOrg"
async def verify_sso_token(http_session, bearer_token: str, db_path: str) -> dict:
"""验证 SSO token;成功返回 {'success': True, 'user_id', 'user_name'}"""
# 1. 调公司校验 API(Authorization 头原样透传,不加 Bearer 前缀)
try:
async with http_session.get(
SSO_USER_API,
headers={'Authorization': bearer_token}, # 原样!
timeout=aiohttp.ClientTimeout(total=10)
) as resp:
if resp.status != 200:
return {'success': False, 'error': f'SSO 返回 HTTP {resp.status}'}
resp_json = await resp.json()
except Exception as e:
return {'success': False, 'error': f'SSO 请求失败: {e}'}
# 2. 判定:status==0 且账号已激活
if resp_json.get('status') != 0:
return {'success': False, 'error': 'SSO 验证失败'}
data = resp_json.get('data', {})
if data.get('state') != 'activated':
return {'success': False, 'error': '用户未激活'}
user_id, user_name = data.get('userId', ''), data.get('userName', '')
if not user_id:
return {'success': False, 'error': 'SSO 返回无效用户'}
# 3. UPSERT 本地用户表
now = datetime.now().isoformat()
conn = sqlite3.connect(db_path); cur = conn.cursor()
cur.execute('''
INSERT INTO users (user_id, user_name, mobile, email, bearer_token, last_login_at, created_at)
VALUES (?, ?, ?, ?, ?, ?, ?)
ON CONFLICT(user_id) DO UPDATE SET
user_name=excluded.user_name, mobile=excluded.mobile, email=excluded.email,
bearer_token=excluded.bearer_token, last_login_at=excluded.last_login_at
''', (user_id, user_name, data.get('mobile',''), data.get('email',''), bearer_token, now, now))
conn.commit(); conn.close()
return {'success': True, 'user_id': user_id, 'user_name': user_name}
```
鉴权入口(登录路由 + 每请求校验中间件/装饰器):
- `POST /api/user/login`:body 里的 `bearer_token` 调 `verify_sso_token`,成功则返回用户身份;
- 其余受保护 API:取 `Authorization` 头(去掉首尾空白)调 `verify_sso_token`(建议先查节流,见 §6),失败返回 401。
## 6. 节流(强烈建议)
如果每个请求都远程校验,SSO 一抖你的服务就全站不可用。建议参数:
- **登录成功后 24h 内**:本地 users 表有该 user_id 且 token 一致 → 直接放行,不再外呼;
- **校验失败后冷却 10 分钟**:同一 user_id 的重试请求直接拒绝,防止高频重打 SSO;
- 节流状态可放内存(重启即清,可接受)或 users 表时间戳。
## 7. 安全清单
1. token 是长期 bearer,**拿到即本人**:全站必须 HTTPS,日志外发/采样前脱敏 `bearer=`。
2. localStorage 存 token 有 XSS 直取风险:不要引入不可信第三方 JS;安全要求高的场景可改为 HttpOnly Cookie + 后端会话(代价是多一层会话管理)。
3. **永远在服务端校验**,前端只负责转发;不要只在前端判 token 格式。
4. token 字符串原样透传,不要拼接、截断或自行加 `Bearer ` 前缀。
5. GET 回调方式下 token 会出现在 URL 中(历史/access log),高敏感系统用 §4 方式 B。
## 8. 验收清单
- [ ] 未登录访问 → 显示"SSO 登录"按钮,点击跳 `sso.d-robotics.cc`;
- [ ] 公司账号登录后回跳,页面显示正确的 userName;
- [ ] 业务 API 带 token 返回 200;不带 Authorization 返回 401;
- [ ] 伪造 token(如 `test-invalid-token`)→ 后端返回验证失败(对齐上游 `status:10002`);
- [ ] 模拟 SSO 不可达:24h 内已登录用户不受影响(节流生效),新登录报错信息可读;
- [ ] 登出后清 token;重放已失效 token 被拒。
## 9. FAQ
**Q: token 有效期多久?过期怎么办?**
由 SSO 侧统一管理,接入方无法续期。失效后业务 API 返回 401,前端清 token 引导重新跳登录即可。
**Q: 登出怎么实现?**
清本地 token 即可。注意 SSO 侧会话是独立的——用户浏览器在 sso.d-robotics.cc 的会话仍在,下次点登录通常免密直达回跳,属正常体验。
**Q: 需要找谁开权限/注册应用吗?**
当前机制不需要:无 client_id、无回调域名白名单,`redirectUrl` 由你方前端自由指定。若你的项目要走标准 OIDC(授权码 + client_secret),才需要另行向 SSO 团队申请。
**Q: 同一账号多端登录?**
允许。每端各存各的 token,互不影响。
**Q: 能拿到部门/组织信息吗?**
校验接口为 userAndOrg,`data` 中含组织信息,按需取用(以实际返回为准)。