107 lines
4.8 KiB
Markdown
107 lines
4.8 KiB
Markdown
# 企业身份接入与验收
|
||
|
||
## 工程边界
|
||
|
||
当前仓库已经提供企业身份工程基线：
|
||
|
||
- OpenID Connect 授权码登录，服务端保存授权状态并校验 `state`、`nonce` 和 ID Token。
|
||
- 身份提供方配置、客户端密钥加密保存、启停和安全审计。
|
||
- 以 `(provider, subject)` 唯一绑定本地用户，不以可变邮箱作为默认身份主键。
|
||
- 首次登录可创建无本地密码账号；停用账号不能通过企业登录恢复访问。
|
||
- 企业组织声明只同步管理员显式登记的业务用户组映射，不覆盖其他手工用户组。
|
||
- 标准化目录记录可幂等批量同步，并保存完成、部分成功或失败的运行结果。
|
||
- LDAP 提供连接配置和标准化目录适配边界，尚未在应用进程内实现 LDAP 搜索或轮询。
|
||
|
||
工程完成不等于企业环境验收完成。真实 IdP、LDAP 目录、网络出口、证书和组织声明仍需按本文
|
||
最后的清单联调。
|
||
|
||
## 部署配置
|
||
|
||
1. 配置稳定的 `AI_CREDENTIAL_ENCRYPTION_KEY`。身份提供方密钥与模型、渠道凭据共用这套
|
||
Fernet 加密能力；密钥丢失后已有密文不可恢复。
|
||
2. 将 `FRONTEND_APP_URL` 设置为用户访问的前端 HTTPS 根地址。
|
||
3. 将 `OIDC_CALLBACK_BASE_URL` 设置为企业 IdP 可访问的后端 HTTPS 根地址。留空时，服务端
|
||
会从当前请求推导根地址。
|
||
4. 执行迁移和治理初始化：
|
||
|
||
```bash
|
||
python manage.py migrate
|
||
python manage.py bootstrap_governance
|
||
```
|
||
|
||
5. 在“系统治理 → 企业身份”新增 OIDC 提供方，并在 IdP 登记精确回调地址：
|
||
|
||
```text
|
||
https://<后端域名>/api/identity/auth/oidc/<provider-slug>/callback
|
||
```
|
||
|
||
生产 OIDC 地址必须使用 HTTPS；仅在 Django 调试模式下允许本机 `localhost` 或
|
||
`127.0.0.1` 使用 HTTP。
|
||
|
||
## OIDC 声明
|
||
|
||
默认声明映射如下，可在治理页按企业 IdP 的实际声明修改：
|
||
|
||
| 平台字段 | 默认声明 | 说明 |
|
||
|---|---|---|
|
||
| 稳定身份 | `sub` | 必填，同一提供方内不可变化 |
|
||
| 登录账号 | `preferred_username` | 首次创建本地账号时使用，冲突会生成唯一后缀 |
|
||
| 邮箱 | `email` | 用于资料同步，不默认用于绑定已有账号 |
|
||
| 显示名称 | `name` | 同步到本地显示名称 |
|
||
| 企业组织 | `groups` | 只匹配已登记的组织映射 |
|
||
|
||
默认禁止按邮箱自动链接已有账号，以避免邮箱声明错误导致账号接管。确需迁移存量账号时，应由
|
||
管理员评估 IdP 的邮箱验证策略后，在提供方 `configuration` 中显式启用
|
||
`allow_email_linking`，并先用脱敏账号演练。
|
||
|
||
## 目录适配器契约
|
||
|
||
治理页和 `POST /api/identity/providers/{id}/directory-sync` 接收标准化成员数组：
|
||
|
||
```json
|
||
{
|
||
"records": [
|
||
{
|
||
"subject": "employee-1001",
|
||
"username": "zhangsan",
|
||
"email": "zhangsan@example.com",
|
||
"display_name": "张三",
|
||
"active": true,
|
||
"groups": ["IT-Support"]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
- `subject` 是必填稳定标识。
|
||
- 同一提供方和 `subject` 重复提交只会更新原身份。
|
||
- 单次最多 1000 条，单条冲突会记录在同步运行中，不会伪造整批成功。
|
||
- `active=false` 会停用对应本地账号。
|
||
- 连接 LDAP、HR 或 IAM 的可信适配器负责读取企业目录并转换为上述结构；浏览器和审计日志
|
||
不保存 Bind password。
|
||
|
||
## 接口与权限
|
||
|
||
| 接口 | 权限/用途 |
|
||
|---|---|
|
||
| `GET /api/identity/auth/providers` | 匿名读取已启用 OIDC 登录入口 |
|
||
| `GET /api/identity/auth/oidc/{slug}/start` | 启动授权码登录 |
|
||
| `GET /api/identity/auth/oidc/{slug}/callback` | IdP 回调、身份同步并建立 Django 会话 |
|
||
| `GET/POST/PATCH /api/identity/providers` | `system.setting.manage` 管理提供方 |
|
||
| `GET/POST/DELETE .../group-mappings` | `system.setting.manage` 管理受控组织映射 |
|
||
| `POST .../directory-sync` | `system.setting.manage` 执行标准化目录同步 |
|
||
|
||
密钥不会通过管理接口返回；操作审计只记录修改字段、提供方、计数和错误类型，不记录令牌、
|
||
Client secret 或 Bind password。
|
||
|
||
## 真实企业环境验收
|
||
|
||
- [ ] IdP 发现文档、JWKS 和令牌端点均通过受信任 HTTPS 证书访问。
|
||
- [ ] 正常授权码登录成功，篡改 `state`、错误 `nonce`、过期或错误签名 ID Token 均被拒绝。
|
||
- [ ] 同一 `sub` 重复登录只关联一个本地账号，账号名冲突不会串号。
|
||
- [ ] 停用提供方、停用本地账号和无效组织声明都按预期阻断或忽略。
|
||
- [ ] 企业组织新增、移除后只改变已登记映射对应的业务用户组。
|
||
- [ ] IdP 不可用时，本地受控管理员账号仍可完成应急登录。
|
||
- [ ] 登录成功、失败、提供方修改、映射变更和目录同步均可在审计日志追溯。
|
||
- [ ] LDAP/目录适配器在真实目录完成分页、超时、证书、增量和停用成员演练。
|