# 企业身份接入与验收

## 工程边界

当前仓库已经提供企业身份工程基线：

- 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/目录适配器在真实目录完成分页、超时、证书、增量和停用成员演练。