From 1197b29770b7f6ec237265d458bc3cda55d0f49a Mon Sep 17 00:00:00 2001 From: "chao.wu" Date: Tue, 17 Nov 2026 20:13:37 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20sso=E7=99=BB=E5=BD=95sop.m?= =?UTF-8?q?d?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- sso登录sop.md | 224 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 sso登录sop.md diff --git a/sso登录sop.md b/sso登录sop.md new file mode 100644 index 0000000..3c52d0a --- /dev/null +++ b/sso登录sop.md @@ -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 回跳:`?bearer=`;或 POST 表单字段 `bearer` 到 redirectUrl(见 §4) | +| 用户校验 API | `GET https://cloud.d-robotics.cc/api/dcloudUserApi/user/userAndOrg` | +| 校验 API 认证 | 请求头 `Authorization: `(**不加** `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= 回跳你的页面(GET 或 POST,见 §4) │ + │ │ │ │ + ├─ POST /api/user/login {bearer_token} ─────────────► │ │ + │ │ GET userAndOrg ─────────────────────────────────► │ + │ │ ◄── {status:0, data:{userId,userName,...}} │ + │ ◄── 登录成功 + 用户身份 ── │ UPSERT 本地用户表 │ │ + │ │ │ │ + │ 之后所有 API 带 Authorization: ,后端复验(带节流,见 §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 以 `?bearer=` 回跳。前端 `initAuth()` 已处理。 +缺点:token 会进浏览器历史、服务器 access log、可能的 referer。 + +### 方式 B:POST 回调 + 中间页(推荐,token 不进历史) +SSO 把 `bearer` 以 POST 表单提交到你的 redirectUrl;你的服务端**不渲染业务页**,而是返回一张中间页,由 JS 写入 localStorage 后跳转: + +```html + +

登录中,请稍候...

+ +``` + +服务端填充时必须做注入防护:`json.dumps(token).replace('` 逃逸。 + +## 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` 中含组织信息,按需取用(以实际返回为准)。