mTLS 认证

基于客户端证书（MDM 签发）的企业级认证。包含自动预配与多设备身份映射。

mTLS（双向 TLS）是一种企业级身份验证模式。在握手阶段，客户端设备会向服务端提供公司颁发的 TLS 证书。

Kaiwu 支持通过 mTLS 实现以下能力：

无需 OAuth 重定向即可完成用户身份验证；
用户首次登录时，可按需自动配置账号；
强制实施严格的“仅限公司设备”访问策略。

重要提示：

mTLS 解决的是身份验证，而非端到端加密（E2EE）。
若停用 E2EE（选择不加密 / 明文存储），服务器便可读取并索引会话内容，从而支持服务端搜索等功能。详见：加密与明文存储。

mTLS 与 OIDC 的选型场景

若企业已通过 MDM 分发设备证书，且希望实现“凭设备证书登录”，请选择 mTLS。
若需要身份提供商的用户体验、基于用户组的策略或浏览器端单点登录（SSO）流程，请选择 OIDC（Okta/Azure AD/Auth0/Keycloak）。

两种部署模式

Kaiwu 支持以下两种模式，运维人员可通过环境变量进行选择。

模式 A：转发 mTLS（推荐）

在此模式下，反向代理或负载均衡器负责终结 TLS、校验客户端证书，并将受信任的身份标识（例如证书指纹或用户主体）转发给 Kaiwu。

推荐理由：

在边缘节点集中管理 TLS 策略；
应用服务器无需配置 HTTPS 即可运行；
符合多数生产环境既有的架构模式。

安全须知：

转发身份的请求头必须在边缘节点剥离并重写，以防客户端伪造。

模式 B：直连 mTLS（暂未实现）

直连模式由 Kaiwu API 自行终结 TLS，并依据配置的 CA 证书包验证客户端证书链。开源版服务器目前不支持该模式。 配置 KAIWU_FEATURE_AUTH_MTLS__MODE=direct 并不会启动该模式——服务器会记录 auth_mtls_not_configured 且不在服务中公布该认证方式，因此界面上不会出现 mTLS 登录入口。

请使用转发模式。如果当前尚未部署反向代理，部署一个反向代理是官方支持的合规方案，而非权宜之计。

稳定身份映射（多设备行为）

企业通常希望同一用户在不同设备上对应“同一个账号”。

为此，Kaiwu 提供了可配置的策略，从证书中派生出 mtls 身份 ID：

首选策略：SAN email 或 SAN UPN（在设备证书轮换时保持稳定）。
备选策略：使用者 CN（subject CN）（仅当 PKI 体系能够保证唯一性与稳定性时适用）。
兜底策略：证书指纹（每个证书唯一；除非引入账号关联流程，否则通常会导致每台设备生成一个账号）。

建议：

使用 SAN email 或 SAN UPN，并强制启用签发者与域名允许列表。

自动配置账号

自动配置（Auto-provisioning）的流程如下：

客户端提供有效的证书。
Kaiwu 派生出稳定的身份 ID（见上文）。
若尚无账号关联该身份，Kaiwu 会创建新账号并完成关联。
Kaiwu 返回标准的 Bearer 令牌，后续所有请求均携带 Authorization: Bearer ...。

若停用自动配置：

未知证书将被直接拒绝（运维人员可通过管理流程预先配置账号或身份）。

仅无密钥模式特性（重要）

在当前的 Kaiwu 中，mTLS 属于**无密钥（keyless）**登录方式：

mTLS 自动配置新账号时，创建的是无密钥/明文账号（不生成设备密钥）。
若 mTLS 身份映射到的账号当前启用了 E2EE，服务器将拒绝签发令牌，转而要求走恢复 / 密钥质询流程。

这保证了核心约束不变：E2EE 账号必须持有私钥方可登录。

选择不加密（企业推荐搭配）

若企业有以下需求：

不希望用户自行管理加密密钥；
需要服务端搜索与索引功能；
简化多设备协同逻辑；

建议将 mTLS 与明文存储模式（选择不加密）搭配使用。在该模式下，新会话存储时无需经过端到端加密。

注意：切换加密模式不会对历史数据进行追溯性的解密或重新加密。

环境变量（概览）

前提条件

mTLS 配置的是无密钥账号，而无密钥账号默认处于禁用状态。以下两项配置必须同时设置，否则自动配置将拒绝所有身份并报错 e2ee-required：

变量	必需值	默认值
`KAIWU_FEATURE_E2EE__KEYLESS_ACCOUNTS_ENABLED`	`1`	off
`KAIWU_FEATURE_ENCRYPTION__STORAGE_POLICY`	`optional` 或 `plaintext_only`	`required_e2ee`

存储策略保持默认值，是 mTLS 配好后仍然无法生效的最常见原因。关于这对用户账号的具体影响，请参阅仅无密钥模式特性。

启用 mTLS

KAIWU_FEATURE_AUTH_MTLS__ENABLED (0/1)
KAIWU_FEATURE_AUTH_MTLS__MODE (forwarded | direct)
KAIWU_FEATURE_AUTH_MTLS__AUTO_PROVISION (0/1)

身份映射

KAIWU_FEATURE_AUTH_MTLS__IDENTITY_SOURCE (san_email | san_upn | subject_cn | fingerprint)
KAIWU_FEATURE_AUTH_MTLS__ALLOWED_EMAIL_DOMAINS（CSV 格式；建议与 san_email / san_upn 配合使用）
KAIWU_FEATURE_AUTH_MTLS__ALLOWED_ISSUERS（推荐；支持 CN 或精确 DN 匹配）

说明：

CN 允许列表项（最常用）既可写为 cn=...，也可直接写 CN 字符串（例如 Example Root CA）。多个 CN 项之间用逗号分隔。
精确 DN 允许列表项可传入完整的签发者 DN（例如 C=US, O=Example Corp, CN=Example Root CA）。若需配置多个 DN 项，请使用换行符或 ; 进行分隔（因 DN 字符串本身包含逗号）。
转发过来的签发者字符串既可为简单的 CN=... 值，也可为完整的 DN。Kaiwu 会对其执行大小写与空格不敏感的归一化处理。
匹配规则：
- 若允许列表项仅包含 CN，Kaiwu 会将其与提取出的签发者 CN 进行比对；
- 若允许列表项为完整 DN，Kaiwu 要求（归一化后）精确匹配整个 DN。

转发请求头配置（仅限转发模式）

KAIWU_FEATURE_AUTH_MTLS__TRUST_FORWARDED_HEADERS (0/1)
KAIWU_FEATURE_AUTH_MTLS__FORWARDED_EMAIL_HEADER（默认 x-KAIWU-client-cert-email）
KAIWU_FEATURE_AUTH_MTLS__FORWARDED_UPN_HEADER（默认 x-KAIWU-client-cert-upn）
KAIWU_FEATURE_AUTH_MTLS__FORWARDED_SUBJECT_HEADER（默认 x-KAIWU-client-cert-subject）
KAIWU_FEATURE_AUTH_MTLS__FORWARDED_FINGERPRINT_HEADER（默认 x-KAIWU-client-cert-sha256）
KAIWU_FEATURE_AUTH_MTLS__FORWARDED_ISSUER_HEADER（默认 x-KAIWU-client-cert-issuer）

原生应用交接（移动端）

KAIWU_FEATURE_AUTH_MTLS__RETURN_TO_ALLOW_PREFIXES（CSV 格式；默认为 KAIWU:// 与 KAIWU_WEBAPP_URL）
KAIWU_FEATURE_AUTH_MTLS__CLAIM_TTL_SECONDS（默认 60）

说明：

对于 http:// / https:// 条目，Kaiwu 按源（Origin）（协议 + 主机 + 端口）校验 returnTo；若在允许列表条目中包含了路径，还会附加路径前缀约束。此举可防止诸如 https://app.example.com.evil.com/... 等“前缀拼接型”开放重定向绕过漏洞。
对于深度链接（Deep Link），请使用类似 KAIWU:// 的协议前缀（或更具体的类似 KAIWU:///mtls 的前缀）。