# 身份与登录

Raise 的统一身份中心由 Zitadel（`id.{base}`）承载。租户门户支持使用平台自建登录页或 Zitadel 原生登录页，运营管理台则始终通过 Zitadel 原生页面与 oauth2-proxy 进行统一身份认证。租户管理员可以在「我的组织」中自主配置密码规则、通行密钥、企业身份源（IdP）以及企业微信扫码登录。

## 谁能用

不同角色在身份与认证系统中的职责与权限如下：

| 角色 / 身份 | 权限标识 | 权限说明 |
|---|---|---|
| 部署与系统运维人员 | 主机与容器管理权限 | 负责系统部署、配置 SMTP 发信服务、切换租户登录页以及添加平台运营人员。平台管理员邮箱由 `PLATFORM_ADMIN_EMAIL` 指定（默认 `admin@{域名}`），在系统初始化引导时分配 `platform.ops` 角色权限；初始密码保存在 `.env` 文件的 `PLATFORM_ADMIN_PASSWORD` 环境变量中。Zitadel 设置了首次登录强制修改密码，首次登录时必须修改密码。 |
| 平台运营管理员 | `platform.ops` | 拥有运营管理台的完整操作权限，负责开通租户与重发管理员验证码。可通过运维脚本 `deploy/scripts/create-operator.sh <email>` 创建，或在 `.env` 中配置 `OPS_ADMINS` 变量后重新执行安装脚本。 |
| 只读运营人员 | `platform.support` | 拥有运营管理台的只读权限。可通过 `deploy/scripts/create-operator.sh <email> --support` 脚本创建，或在 `.env` 中配置 `OPS_SUPPORT` 变量后重新执行安装脚本。只读运营人员不能开通租户。 |
| 租户管理员 | `tenant.admin` 或 `admin.write` | 拥有租户组织的安全管理权限，可以在「我的组织」中修改「登录与认证」「企业登录」和「协作平台」配置。 |
| 租户审计员与只读角色 | `admin.read` 或审计员角色 | 拥有安全设置的只读权限。进入「登录与认证」时，顶部显示「只读」徽章与横幅提示「审计员可以查看安全设置，但不能修改。」。 |
| 普通成员与无权限角色 | 成员权限 | 无法进入组织安全与连接器管理页面。 |

> **身份服务未连接说明**
>
> 若当前部署未连接身份服务，租户管理员打开「企业登录」时界面显示「不可用」并提示「这个部署没有连接身份服务，企业登录由部署方配置。」；打开「登录与认证」时显示「登录设置不可用」并提示「这个部署没有连接身份服务，登录策略由部署方管理。」。

## 怎么打开

你可以通过以下地址与命令访问各端登录界面或进行身份配置：

| 入口类型 | 访问地址 / 操作命令 | 说明 |
|---|---|---|
| 租户登录入口 | `https://app.{base}`（包含应用子域 `organization.apps.{base}`、`dev.{base}` 等） | 租户成员与管理员日常办公登录入口，默认展示平台自建登录页 |
| 身份中心 | `https://id.{base}` | Zitadel 原生服务地址 |
| 运营管理台 | `https://ops.{base}:8443` | 平台运营台访问入口，默认监听地址 `OPS_BIND` 为 `127.0.0.1`，需通过 SSH 隧道访问，始终使用 Zitadel 原生登录页并经由 oauth2-proxy 认证 |
| 切换租户登录页 | `deploy/scripts/login-page.sh on\|off` | 部署运维脚本，用于开启或关闭平台自建登录页 |
| 创建运营人员 | `deploy/scripts/create-operator.sh <email> [--support]` | 部署运维脚本，用于添加平台运营管理员或只读运营人员 |
| 配置邮件服务 | `deploy/scripts/smtp.sh set\|status\|clear` | 部署运维脚本，用于配置、查询或清除 SMTP 邮件服务参数 |
| 组织安全与协作设置 | 在[工作台](/guide/workspace)打开「我的组织」 | 租户管理员在「安全」分组下进入「登录与认证」「企业登录」，或进入「协作平台」 |

> **Kubernetes / Helm 部署**
>
> 在 Kubernetes 环境中使用 Helm 部署时，若由客户自备 Zitadel 实例（官方 Helm Chart 建议设置 `fullnameOverride: zitadel`），需在 Helm 配置的 `secrets.zitadelPat` 中填入访问凭据。若 Kubernetes Service 名称命名为 `zitadel`，环境会自动注入 `ZITADEL_PORT`，官方 Chart 已默认处理。

## 界面一览

### 1. 平台自建登录页（默认开启）

平台默认通过 `deploy/scripts/login-page.sh on` 启用自建登录页。宽屏桌面端左侧为品牌展示区（包含标题、说明、三个要点与产品示意），右侧为登录表单区；手机端仅显示右侧表单。租户管理员可以在「基本信息与品牌」中自定义「登录页」文字内容与页脚链接。运营管理台不使用自建登录页。

自建登录页各交互阶段界面元素如下：

| 步骤 / 阶段 | 标题与界面文本 | 字段与操作按钮 |
|---|---|---|
| 账号输入 | 标题「登录」；说明「或者用公司账号登录」 | 字段「登录名」；按钮「下一步」；快捷登录「用通行密钥登录」；企业登录按钮「用……登录」（展示提供方名称） |
| 密码输入 | 标题「输入密码」；提示「第一次登录（还没有密码），或忘记了密码？」 | 字段「密码」；按钮「登录」；切换账号「更换」；跳转链接「输入激活码 / 验证码，设置密码」 |
| 设置密码 | 标题「用验证码设置密码」；已配 SMTP 提示「验证码将发到账号邮箱，邀请邮件里的验证码也可用。」；未配 SMTP 提示「未配置邮件服务，请向管理员索取验证码。」 | 字段「验证码」「新密码」「再输一次」；操作「发送验证码」「重新发送验证码」或倒计时提示「…… 秒后可重发」；提交按钮「设置密码并登录」（需补充用户名时为「设置密码、用户名并登录」） |
| 第二重验证（MFA） | 标题「第二重验证」；提示「输入验证器 App 显示的 6 位数字。」或「用你的通行密钥确认是你本人。」 | 按钮「验证」或「用通行密钥验证」 |
| 设通行密钥 | 标题「设置通行密钥？」 | 按钮「设置通行密钥」「以后再说」「不再提示」 |
| 强制 MFA 设置 | 标题「设置第二重验证」 | 按钮「完成设置」 |
| 异常与失败提示 | 标题「无法登录」；过期提示「这次登录已经过期」；企业登录失败提示「企业登录没有成功。」或「企业登录没有成功，请重试，或用账号密码登录。」；服务不可用提示「身份服务暂时连不上，稍后再试。」；验证切换「需要另一种验证方式」 | — |

### 2. 「我的组织」→「登录与认证」

位于「我的组织」的「安全」导航分组：

- **顶栏状态**：页面标题为「登录与认证」，右上角显示来源徽章「使用平台默认」或「已自定义」；保存配置时显示「保存中…」。页面改动即时生效，可在提示中撤销。
- **「登录与验证」卡片**：
  - 开关「强制第二重验证」：开启状态显示「推荐」徽章，关闭状态显示「建议开启」徽章。
  - 开关「允许通行密钥」。
  - 开关「允许企业身份源」。
  - 下拉菜单「会话时长」：预设选项包含「8 小时（一个工作日）」「1 天」「3 天」「7 天」「10 天（平台默认）」「30 天」。
- **「密码规则」卡片**：
  - 输入框「最短长度」：设定范围为 8–64 个字符，光标离开输入框时保存。右侧动态显示强度徽章「严格」「标准」或「宽松」。
  - 开关「需要大写字母」。
  - 开关「需要小写字母」。
  - 开关「需要数字」。
  - 开关「需要符号」。

### 3. 「我的组织」→「企业登录」

位于「我的组织」的「安全」导航分组：

- **顶栏操作**：提供按钮「接入提供方」（组织接入数量达到上限 10 个时不出现）。下方显示提示「在你们的提供方里登记这个重定向地址」与专属回调地址。
- **空状态**：未接入任何提供方时，显示「还没有接入企业登录」。
- **已接入列表**：列表展示「已接入的提供方」与数量统计（格式如 `n / 10`）。每条记录包含协议类型徽章「OpenID Connect」或「OAuth 2.0」、启用状态「已在登录页提供」或「未启用」，以及开关「登录页提供」。由企业微信托管生成的接入行会标注提示「去「协作平台」修改」。
- **底栏警示**：页面底部提示「企业微信、钉钉、飞书」不能直接作为标准 OIDC 接入，需通过 Authing 或 Keycloak 桥接，或通过「协作平台」接入。

### 4. 「我的组织」→「协作平台」（`/connectors`）

位于「我的组织」应用中：

- **未开通连接**：部署未开启连接功能时，显示「不可用」与提示「未开启协作平台连接，请联系部署方。」。
- **无可连接平台**：无可用套件时，显示「暂无可连接的协作平台」。
- **未连接卡片**：展示配置步骤清单、系统生成的「授权回调域」信息以及操作按钮「连接企业微信」。
- **已连接卡片**：展示连接状态徽章，提供操作按钮「启用登录」或「停用登录」，以及管理按钮「编辑」与「断开」。

### 5. 运营管理台开通租户与凭据管理

平台运营人员在运营管理台管理租户身份凭据：

- **「开通租户」对话框**：包含复选框「直接返回邮箱验证码」（系统默认勾选，说明标注「未配置 SMTP 时勾选。」）。
- **开通成功反馈**：提交后若返回验证码，界面显示「租户已开通」，提示「请把验证码交给管理员」，并显示警告「未配置 SMTP，邮件不会发出。验证码只显示这一次。」。
- **凭证重新发放**：在租户详情页面的「管理员登录」区块，运营人员可点击「发放验证码」重新生成一次性登录验证码。

## 常用操作

### 部署后平台管理员首次登录

1. 连接服务器终端。若使用默认本地绑定（`OPS_BIND` 为 `127.0.0.1`），在本地终端建立 SSH 隧道：
   ```bash
   ssh -L 8443:127.0.0.1:8443 user@主机IP
   ```
2. 在本地浏览器中打开 `https://ops.{base}:8443`。
3. 页面重定向至 Zitadel 原生登录页。输入平台管理员邮箱 `PLATFORM_ADMIN_EMAIL`（默认 `admin@{域名}`）以及 `.env` 中的初始密码 `PLATFORM_ADMIN_PASSWORD` 进行登录。
4. 由于系统默认启用了首次登录改密（`PASSWORDCHANGEREQUIRED=true`），按照页面提示修改新密码。
5. 登录成功后，oauth2-proxy 会在后台建立运营会话，页面进入运营管理台。

> **运营台退出登录机制**
>
> 在运营台点击退出登录时，系统网关调用 `/oauth2/end`，代理清理本地会话 `/oauth2/sign_out`，并调用 Zitadel 的 `end_session` 端点携带 `prompt=login` 返回运营台登录页。这保证了完整的登出清理，避免退出后页面刷新又自动重新登录。

### 开通首个租户与管理员初始化

1. 登录运营管理台，点击「开通租户」按钮。
2. 填写开通信息：
   | 字段 | 必填 | 说明 |
   |---|---|---|
   | 「租户名称」 | 是 | 输入租户组织的展示名称 |
   | 「租户 ID」 | 是 | 输入租户唯一标识，长度为 2–63 位，由小写字母、数字或连字符 `-` 组成，必须以字母开头，创建后不可更改 |
   | 「管理员邮箱」 | 是 | 输入首位管理员邮箱，将被授予 `tenant.admin` 角色 |
   | 「直接返回邮箱验证码」 | 否 | 默认勾选。未配置 SMTP 邮件服务时必须保持勾选 |
3. 点击「开通」按钮（未勾选验证码时按钮再拼「并发送邀请」）。系统会在 Zitadel 中创建对应组织、分配工作台权限、配置租户断言并建立管理员账号。若身份中心步骤中出现故障，系统会自动回滚，你可以重新提交重试。
4. 若勾选了「直接返回邮箱验证码」，弹窗显示「租户已开通」，复制界面展示的一次性验证码并线下转交给租户管理员。
5. 租户管理员打开 `https://app.{base}`，输入管理员邮箱后点击「下一步」，点击「输入激活码 / 验证码，设置密码」，填入验证码并设置新密码后完成登录。

### 配置 SMTP 邮件服务

生产环境建议配置 SMTP 服务，以支持自动发送成员邀请与验证码邮件：

1. 准备 SMTP 发信服务配置信息。
2. 在服务器终端执行以下命令写入配置：
   ```bash
   KWORK_SMTP_HOST=smtp.example.com:587 KWORK_SMTP_USER=ops@example.com KWORK_SMTP_PASSWORD=secret KWORK_SMTP_FROM=no-reply@example.com \
     deploy/scripts/smtp.sh set
   ```
3. 你可以通过 `deploy/scripts/smtp.sh status` 查询当前邮件服务状态，或执行 `deploy/scripts/smtp.sh clear` 清除配置。

> **验证码管理注意事项**
>
> - 未配置 SMTP 邮件服务时，登录页面会自动隐藏「发送验证码」按钮，所有验证码均需由管理员在运营台生成并线下转交。
> - 验证码在界面上只显示一次，系统不会将其写入审计日志（审计日志仅记录操作人员、目标对象及操作类别）。
> - 请勿直接在 Zitadel 原生控制台中手动创建运营人员或租户用户，手动创建的用户会停留在待初始化状态，必须通过引导脚本或运营台进行创建。

### 切换租户登录页展示模式

你可以根据运维需求在平台自建白标登录页与 Zitadel 原生登录页之间切换：

- **切换为平台自建登录页（系统默认）**：
  ```bash
  deploy/scripts/login-page.sh on
  ```
  该命令将租户门户（工作台、组织应用、开放平台与草稿应用）的认证地址指向 `https://id.{base}/ui/v2/login`。每次执行 `kwork bootstrap zitadel` 引导程序会自动将实例品牌同步至 Zitadel 的默认标签策略中；若同步失败仅在终端输出标准错误，不影响引导流程。
- **切换为 Zitadel 原生登录页**：
  ```bash
  deploy/scripts/login-page.sh off
  ```
  该命令将恢复使用 Zitadel 原生登录页面。

> **运营台独立性**
>
> 无论租户登录页如何切换，运营管理台始终强制使用 Zitadel 原生登录页与 oauth2-proxy。

### 添加平台运营人员

如需为运维团队增加人员：

- **添加平台运营管理员（`platform.ops`）**：
  ```bash
  deploy/scripts/create-operator.sh alice@example.com
  ```
  终端会输出该运营员的一次性初始密码，并自动将邮箱标记为已验证。你也可以在 `.env` 文件的 `OPS_ADMINS` 变量中追加邮箱后重新执行 `install.sh`。
- **添加只读支持人员（`platform.support`）**：
  ```bash
  deploy/scripts/create-operator.sh bob@example.com --support
  ```
  终端会输出一次性密码并将邮箱标记为已验证。你也可以在 `.env` 文件的 `OPS_SUPPORT` 变量中追加邮箱后重新执行 `install.sh`。只读运营人员无法开通租户。

### 配置组织登录与认证规则

租户管理员可以在组织内部自定义登录与密码安全策略：

1. 登录[工作台](/guide/workspace)，打开「我的组织」应用。
2. 在左侧导航点击「安全」分组下的「登录与认证」。
3. 根据安全要求调整配置：
   - 切换「强制第二重验证」开关：开启后系统提示「所有成员下次登录时必须设置第二重验证（验证器 App 或安全密钥），否则无法登录。」。
   - 切换「允许通行密钥」开关：关闭后系统提示「成员不能再用通行密钥登录，已登记的通行密钥失效。」。
   - 切换「允许企业身份源」开关：控制是否允许在登录页展示外部企业 IdP 登录入口。
   - 在「会话时长」下拉框中选择时长（可选 8 小时至 30 天）。
   - 在「密码规则」中修改「最短长度」（8–64 个字符）或切换复杂度要求开关。修改后系统提示「更严格的密码规则只对之后设置或修改的密码生效，不会强制现有成员改密码。」。
4. 各项修改在失焦或开关切换时即时保存并生效，界面右上角徽章变为「已自定义」。

### 接入企业身份源（IdP）

组织支持接入外部标准 OIDC 或 OAuth 2.0 身份提供方，单组织最多接入 10 个：

1. 在「我的组织」左侧导航点击「安全」分组下的「企业登录」。
2. 点击右上角「接入提供方」按钮。
3. 选择预置提供方类型：「其他 OpenID Connect」「Microsoft Entra ID（Azure AD）」「Google Workspace」「Okta」「Keycloak」「Authing」或「其他 OAuth 2.0」。
4. 根据所选类型填写配置表单：
   | 字段 | 必填 | 说明 |
   |---|---|---|
   | 提供方名称 | 是 | 显示在登录页按钮上的名称，最多 60 个字符 |
   | Client ID | 是 | 身份源分配的客户端唯一标识 |
   | Client Secret | 是（新建时） | 客户端密钥，仅在填写时可输入，保存后系统不会再次展示 |
   | Issuer（OIDC 类型） | 是 | 必须为完整的 https 协议地址 |
   | 授权端点 / Token 端点 / 用户信息端点（OAuth 类型） | 是 | 三个接口地址均必须为完整的 https 协议地址 |
   | 用户标识字段（OAuth 类型） | 否 | 默认为 `sub` |
   | Scopes | 否 | 默认为 `openid profile email`，最多配置 20 个 |
5. 点击「测试连接」按钮，系统读取提供方的发现文档进行校验。测试成功提示「连接正常」，失败提示「连不上或不对」。
6. 配置「第一次用公司账号登录时」的处理策略：
   - 「自动创建账号」：开启后外部成员首次登录时自动建立组织账号；关闭则仅允许已受邀成员登录。
   - 「按已验证邮箱并入已有账号」：仅当外部提供方能确保邮箱真实性时方可开启。
7. 点击「接入」保存配置。
8. 保存后在列表中找到该提供方，开启「登录页提供」开关。

> **删除提供方**
>
> 在提供方列表中点击删除时，界面弹出确认弹窗「删除……？」（显示提供方名称），并提示「成员将无法再用它登录，账号和数据不受影响。」。确认后提供方将被移除。

### 连接企业微信扫码登录

组织可以通过专用的协作平台连接器接入企业微信扫码登录：

1. 登录企业微信管理后台，在自建应用中创建或选择应用，获取「企业 ID」、应用「AgentId」与「Secret」。
2. 在企业微信后台中，将页面中给出的「授权回调域」填入应用配置，并将服务器公网出口 IP 添加至企业微信后台的「企业可信 IP」名单中。
3. 登录[工作台](/guide/workspace)，打开「我的组织」→「协作平台」。
4. 点击「连接企业微信」，填写连接信息：
   | 字段 | 必填 | 说明 |
   |---|---|---|
   | 名称 | 是 | 显示在登录按钮上的名称 |
   | 企业 ID | 是 | 6–64 位字符，由字母、数字、下划线 `_` 或连字符 `-` 组成 |
   | 应用 AgentId | 是 | 企业微信自建应用的 AgentId，必须为纯数字 |
   | Secret | 是 | 企业微信自建应用的 Secret 密钥 |
   | 通讯录 Secret | 否 | 用于同步通讯录的可选密钥 |
   | 客户联系 Secret | 否 | 用于外部联系人管理的可选密钥 |
5. 点击「测试连接」，并可勾选「连接后立即在登录页提供扫码登录」。
6. 点击保存，系统会向企业微信接口换取凭据并建立连接。

> **断开企业微信**
>
> 如需解除绑定，在协作平台卡片中点击「断开」按钮。弹窗提示「成员将不能再用企业微信扫码登录。已经关联的成员账号和数据不受影响，他们仍可以用密码登录。」。确认后将断开连接。

### 运维单点登录（SSO）集成

Docker Compose 部署环境下系统默认启动 oauth2-proxy 服务，为运维管理组件提供 SSO 支持：

- **客户端凭据配置**：OIDC 客户端凭据由系统引导程序自动写入 `.env` 文件中的 `OPS_OIDC_CLIENT_ID` 与 `OPS_OIDC_CLIENT_SECRET`，运维人员请勿手动修改这两项配置。
- **Grafana 访问**：Grafana 自动信任网关反向代理转发的用户邮箱请求头，无需二次输入账号。
- **Langfuse 访问**：Langfuse 配置有专属的 SSO 客户端，仅具备平台运营角色的账号可以完成登录，其登录页面展示运营 SSO 登录按钮。
- **Superset 访问**：Superset 通过网关共享密钥 `OPS_PROXY_TOKEN` 完成鉴权。
- **故障隔离机制**：若 oauth2-proxy 代理服务发生异常或停止运行，仅会导致运维管理工具无法登录，租户门户与业务访问不受任何影响。

## 状态说明

系统包含以下配置状态徽章与标识：

| 模块 | 状态标识 | 说明 |
|---|---|---|
| 组织安全配置 | 「使用平台默认」 | 租户当前沿用平台默认的会话时长与密码规则基线 |
| 组织安全配置 | 「已自定义」 | 租户管理员已修改并保存了专属的安全策略 |
| 组织安全配置 | 「保存中…」 | 配置正在向身份中心同步保存 |
| 密码规则 | 「严格」/「标准」/「宽松」 | 根据输入的最短长度与字符复杂度要求动态展示的强度等级 |
| 企业身份源 | 「OpenID Connect」/「OAuth 2.0」 | 提供方使用的标准身份认证协议徽章 |
| 企业身份源 | 「已在登录页提供」/「未启用」 | 提供方是否已经在租户登录页向成员开放展示 |
| 协作平台 | 「不可用」 | 部署未开启协作平台连接功能 |
| 协作平台 | 未连接 | 展示配置步骤清单与「连接企业微信」入口 |
| 协作平台 | 已连接 | 展示连接状态徽章，提供「启用登录」或「停用登录」状态切换 |

## 让助手帮你做

在「我的组织」中，你可以让助手协助起草企业登录与协作平台连接配置。由于涉及外部密钥与身份验证，所有操作均属于高风险操作，助手起草后必须由管理员在审阅页面人工填写密钥并最终确认执行：

- **「添加企业登录」**：起草新增外部企业 IdP 配置。
- **「修改企业登录」**：起草更新已有的企业 IdP 配置参数。
- **「删除企业登录」**：起草移除已接入的企业 IdP。
- **「启用或停用企业登录」**：起草开启或关闭企业 IdP 在登录页的展示开关。
- **「连接企业微信」**：起草建立企业微信连接配置。
- **「修改企业微信连接」**：起草更新企业微信连接参数。
- **「断开企业微信」**：起草解除企业微信连接。

你可以对助手说：
> “帮我接上公司的 Entra”
> “把企业登录开到登录页”
> “连企业微信扫码，先别自动建号”

> **助手权限边界**
>
> 助手不能执行以下底层运维与特权操作：
> - 不能修改 Zitadel 实例本身的基础配置。
> - 不能创建平台运营人员或分配运营角色。
> - 不能配置 SMTP 邮件服务参数。
> - 不能执行脚本切换登录页面模式。
> - 不能直接设置任何成员的明文密码（仅能代为触发发放一次性验证码）。
> - 不能在真实企业微信环境中保证接口已完成端到端验证。

## 设置

系统与身份认证相关的配置项如下表所示：

| 配置名称 | 作用说明 | 默认值 | 管理角色 |
|---|---|---|---|
| `KWORK_ZITADEL_URL` / `HOST` / `PAT` / `PAT_FILE` | 连接 Zitadel 身份服务集群及访问凭据 | 安装时自动生成 PAT 令牌 | 部署运维人员 |
| `KWORK_LOGIN_PAGE` | 控制租户登录页面类型（`on` 使用自建白标页，`off` 使用 Zitadel 原生页） | 安装默认启用 `on` | 部署运维人员（通过 `login-page.sh` 脚本调整） |
| `PLATFORM_ADMIN_EMAIL` / `PLATFORM_ADMIN_PASSWORD` | 首个平台运营管理员账号与初始密码 | `admin@{域名}`，密码自动生成 | 安装初始化生成，首次登录强制修改密码 |
| `OPS_OIDC_CLIENT_ID` / `OPS_OIDC_CLIENT_SECRET` | 运维管理网络单点登录（SSO）凭据 | 系统引导程序自动写入 | 系统维护（请勿手动修改） |
| `KWORK_SMTP_*` | Zitadel 发送邀请邮件与验证码所用的 SMTP 服务器配置 | 空（未配置） | 部署运维人员（通过 `smtp.sh` 脚本配置） |
| 「强制第二重验证」 | 强制组织成员开启 MFA 验证 | 关闭（建议开启） | 租户管理员 |
| 「允许通行密钥」 | 允许成员使用通行密钥免密登录 | 开启 | 租户管理员 |
| 「允许企业身份源」 | 允许成员通过企业 IdP 登录 | 开启 | 租户管理员 |
| 「会话时长」 | 用户登录态有效时长 | 「10 天（平台默认）」 | 租户管理员 |
| 「密码规则」 | 密码最短长度（8–64）与复杂度字符要求 | 平台默认基线 | 租户管理员 |

## 注意事项

- **企业身份源配置上限**：单个组织最多接入 10 个企业 IdP；提供方名称长度不能超过 60 个字符；Scopes 权限列表最多配置 20 个。
- **登录接口容量限制**：登录接口请求体大小上限为 8 KiB。
- **防暴力破解频次限制**：
  - 登录尝试限制：同一登录名在 10 分钟内最多尝试 10 次，同一客户端 IP 在 10 分钟内最多尝试 40 次。超出限制后接口返回 429 状态码并带有 600 秒重试等待头（`Retry-After: 600`）。若配置了分布式协调服务（`--coord`），限制计数由全副本共享，否则各副本独立计数。
  - 验证码尝试限制：单个账号 10 分钟内最多输入验证码 10 次。无论账号在系统中是否存在，系统均返回完全一致的提示信息，避免账号被撞库枚举。
  - 密码修改限制：用户修改自身密码时，若连续 5 次输入错误的旧密码，系统在 15 分钟内将锁定修改密码接口。管理员无法直接为任何成员设置明文密码。
- **密码与会话时间边界**：密码最短支持 8 个字符，最长 64 个字符；会话时长允许设置在 1 小时至 30 天之间。
- **时间同步要求**：身份认证系统允许客户端与服务器时间存在最多 30 秒的时钟偏差。
- **协议兼容限制**：企业微信、钉钉与飞书无法作为标准 OIDC 协议直接接入，必须通过 Authing 或 Keycloak 进行协议桥接，或使用组织内的「协作平台」功能。
- **企业微信通讯录同步边界**：
  - 最多支持 5000 个部门，部门层级深度上限为 8 层（包含手工建立的部门；超出上限时系统直接报错并阻止同步，不会截断）。
  - 同步检测周期支持 5–1440 分钟（下拉预设选项为 15、30、60、120、360、1440 分钟，系统默认 30 分钟）。
  - 单次从 Zitadel 接口最多读取 500 名成员，超出该人数时通过邮箱匹配已有账号可能存在遗漏。
  - 企业微信中未填写邮箱的成员，系统将为其分配占位邮箱（格式为 `<userid>@wecom.<tenant>.invalid`）。
- **注册机制限制**：系统未开放任何自主注册通道，所有租户组织必须由平台运营人员在运营管理台中统一开通。

## 目前不支持

- **公开自主注册**：平台不支持成员或组织公开自助注册（当前采用内测邀请机制，组织必须由运营人员统一开通）。
- **钉钉与飞书官方套件直连**：协作平台目前仅提供企业微信一种套件连接，暂不支持直接连接钉钉或飞书。
- **真实企业微信端到端测试**：企业微信连接功能目前仅在模拟器环境中完成过验证，未在真实企业微信环境中完成端到端验证。
- **租户用户模拟登录**：运营管理台目前不支持平台运营人员模拟切换成某位具体租户用户进行操作。

## 常见问题

### 为什么在运营管理台点击退出登录后，页面刷新又重新回到运营台？
退出登录需要执行完整的登出链路。系统由网关触发 `/oauth2/end`，代理清理本地会话 `/oauth2/sign_out`，并调用 Zitadel 的 `end_session` 端点携带 `prompt=login` 返回运营台登录页。如果登出链路未完整执行，浏览器保留的认证凭据会导致自动重新登录。

### 为什么在登录页面看不到「发送验证码」按钮？
当系统未配置 SMTP 邮件服务时，登录页面会自动隐藏「发送验证码」按钮，并显示提示「未配置邮件服务，请向管理员索取验证码。」。在这种情况下，管理员在运营台开通租户或发放验证码时，界面会直接展示一次性验证码，需由管理员线下转交给成员。

### 租户管理员修改了更严格的密码规则后，现有成员需要立即修改密码吗？
不需要。更严格的密码规则只对之后设置或修改密码的操作生效，不会强制要求现有成员立即修改密码。

### 可以在 Zitadel 原生控制台里直接创建运营人员吗？
不建议。在 Zitadel 控制台直接手动创建的用户会停留在待初始化状态。添加运营人员应使用 `deploy/scripts/create-operator.sh` 脚本，或在 `.env` 中配置 `OPS_ADMINS` / `OPS_SUPPORT` 变量后重新运行安装引导程序。

### 为什么无法直接在「企业登录」中把企业微信或飞书添加为 OpenID Connect 提供方？
企业微信、钉钉与飞书不兼容通用的标准 OIDC 协议。如需接入，需要通过 Authing 或 Keycloak 等第三方身份桥接服务进行中转，或者在「我的组织」中进入「协作平台」使用专用的企业微信连接功能。