添加 sso登录sop.md
This commit is contained in:
parent
1171b004da
commit
1197b29770
224
sso登录sop.md
Normal file
224
sso登录sop.md
Normal 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` 中含组织信息,按需取用(以实际返回为准)。
|
||||
Loading…
x
Reference in New Issue
Block a user