认证 | 无极开物

本指南面向服务器运维人员，旨在介绍核心身份验证模型，以及用于控制注册与登录鉴权策略的环境变量。

有关各提供商的具体配置指南，请参阅：

选择身份验证方案（私网服务器与公网服务器）

具体配置主要取决于哪些人能够访问您的服务器。

私网服务器（仅限 Tailscale / VPN / 局域网）

若服务器仅能通过私有网络访问（例如经由 Tailscale），通常无需基于提供商的身份验证：

推荐做法：保持启用匿名注册（默认），依靠网络层访问控制来保障安全。
请务必确保服务器无法从公网直接访问（通过防火墙、安全组或反向代理控制）。

配置示例：

AUTH_ANONYMOUS_SIGNUP_ENABLED=true
AUTH_SIGNUP_PROVIDERS=
AUTH_REQUIRED_LOGIN_PROVIDERS=

可选方案（私网服务器）：在匿名注册的基础之上，您也可以同时启用 GitHub 或 OIDC，以提供多样化的注册方式：

AUTH_ANONYMOUS_SIGNUP_ENABLED=true
AUTH_SIGNUP_PROVIDERS=github
AUTH_REQUIRED_LOGIN_PROVIDERS=

公网服务器（可从互联网访问）

若服务器暴露在公网上，保持匿名注册会导致任何人都能随意创建账户。在这种场景下，通常建议强制使用身份提供商：

推荐做法：禁用匿名注册
推荐做法：强制要求关联提供商方可维持访问权限（AUTH_REQUIRED_LOGIN_PROVIDERS）
可选方案：通过白名单限制准入资格（例如“必须属于 GitHub 组织 X”）

配置示例（以 GitHub 为例）：

AUTH_ANONYMOUS_SIGNUP_ENABLED=false
AUTH_SIGNUP_PROVIDERS=github
AUTH_REQUIRED_LOGIN_PROVIDERS=github

随后请参考对应提供商的配置指南：

GitHub：GitHub 身份验证
OIDC：OIDC 身份验证

标准身份验证（设备密钥账户）

Kaiwu 采用设备密钥账户模型（每个账户均与一个设备私钥绑定）。

默认行为：用户可通过设备密钥注册创建账户（POST /v1/auth）。
可选配置：您可以强制要求通过外部提供商（GitHub 或 OIDC）进行注册，或要求其维持后续访问权限。
外部提供商并非传统意义上的“密码登录”：若用户想在新的设备或浏览器中访问现有的 Kaiwu 账户，仍需恢复该账户（例如通过添加手机或恢复账户），随后在设置中关联各提供商。

有密钥与无密钥模式（提供商在 UI 中的呈现方式）

同一个 OAuth 提供商（例如 GitHub 或 OIDC 提供商）在 UI 中可以充当两种不同的角色：

有密钥配置（“通过 GitHub 继续”）：创建设备密钥账户。
- 用户必须备份私钥，并在新设备或新浏览器上进行恢复。
- 这是 Kaiwu 的标准模型，可在纯端到端加密（E2EE）服务器上正常运行。
无密钥登录（“使用 GitHub 登录”）：登录无密钥/明文账户（不生成设备密钥）。
- 该模式可实现跨设备无缝登录，但专为企业部署设计，通常搭配明文存储使用。

服务器运维人员可通过 /v1/features（策略与功能环境变量）控制启用哪种角色。客户端不应自行推测。

身份验证方式（发现机制）

客户端应以 GET /v1/features 作为判断“当前可用身份验证流程”的权威依据。

Kaiwu 通过以下途径对外声明身份验证入口：

capabilities.auth.methods[]（首选途径；包含方式、操作与模式）
以及诸如 capabilities.auth.signup.methods[] 等旧版入口，供老版本客户端兼容使用

每种方式均可声明多种操作：

login（登录现有账户）
provision（创建新账户）
connect（将身份提供商关联至已认证的账户）

并且每项操作都会声明其账户密钥模式：

keyed：设备密钥账户（Kaiwu 默认模型）
keyless：无设备密钥（企业模式；通常搭配明文存储使用）

无密钥身份验证（企业版）

某些部署场景希望账户无需设备密钥即可存在（例如：由企业统一托管身份、需要服务端索引与搜索支持，或追求更简便的多设备协同体验）。

Kaiwu 目前支持通过以下方式进行无密钥登录：

mTLS 身份验证
通过功能环境变量启用的 OAuth 无密钥登录（GitHub/OIDC）

无密钥账户的自动置备受到严格的门禁控制：

启用无密钥账户：KAIWU_FEATURE_E2EE__KEYLESS_ACCOUNTS_ENABLED=1
允许明文存储（无密钥账户所必需）：KAIWU_FEATURE_ENCRYPTION__STORAGE_POLICY=optional|plaintext_only
针对 OAuth 无密钥登录：
- 启用开关：KAIWU_FEATURE_AUTH_OAUTH__KEYLESS_ENABLED=1
- 允许的提供商白名单：KAIWU_FEATURE_AUTH_OAUTH__KEYLESS_PROVIDERS=github,okta,...
- 允许首次登录时自动创建账户：KAIWU_FEATURE_AUTH_OAUTH__KEYLESS_AUTO_PROVISION=1
针对 mTLS 无密钥登录：请参阅 mTLS 身份验证

针对明文/无密钥部署的推荐加固措施：

静态落盘时封印明文账户设置：KAIWU_FEATURE_ENCRYPTION__PLAIN_ACCOUNT_SETTINGS_AT_REST=server_sealed（默认开启）
静态落盘时封印明文账户已连接服务的凭据：KAIWU_FEATURE_ENCRYPTION__PLAIN_ACCOUNT_CREDENTIALS_AT_REST=server_sealed（默认开启）

注意：当存储策略设为 optional 时，KAIWU_FEATURE_ENCRYPTION__DEFAULT_ACCOUNT_MODE 仅用于控制有密钥账户与新会话的默认模式，并不会限制无密钥账户的自动置备。

OAuth 无密钥置备选择（可选加密服务器）

当服务器存储策略设为 optional 时，通过 OAuth（GitHub/OIDC）完成认证返回的新用户可能会看到如下选择：

端到端加密（E2EE）：创建设备密钥账户；用户必须备份私钥，以便在新设备上恢复。
不加密（明文）：创建无密钥/明文账户；可实现跨设备无缝登录，但服务端能够读取所存储的内容。

当某个提供商同时启用了这两种模式（有密钥置备与无密钥自动置备）时，客户端应展示该选择界面。若仅有一种模式可用，客户端应自动选中该模式，无需展示多余页面。

在 plaintext_only 服务器上，客户端应自动选择明文模式。在 required_e2ee 服务器上，客户端则不应提供明文或无密钥选项。

运维推荐配置示例

纯端到端加密（公网服务器）+ 必须使用 GitHub

KAIWU_FEATURE_ENCRYPTION__STORAGE_POLICY=required_e2ee

AUTH_ANONYMOUS_SIGNUP_ENABLED=false
AUTH_SIGNUP_PROVIDERS=github
AUTH_REQUIRED_LOGIN_PROVIDERS=github

纯无密钥（企业级）+ 纯明文 + 必须使用 GitHub

KAIWU_FEATURE_ENCRYPTION__STORAGE_POLICY=plaintext_only
KAIWU_FEATURE_E2EE__KEYLESS_ACCOUNTS_ENABLED=1

AUTH_ANONYMOUS_SIGNUP_ENABLED=false
AUTH_SIGNUP_PROVIDERS=
AUTH_REQUIRED_LOGIN_PROVIDERS=github

KAIWU_FEATURE_AUTH_OAUTH__KEYLESS_ENABLED=1
KAIWU_FEATURE_AUTH_OAUTH__KEYLESS_PROVIDERS=github
KAIWU_FEATURE_AUTH_OAUTH__KEYLESS_AUTO_PROVISION=1

可选加密（企业级）+ OAuth 置备选择（GitHub）

KAIWU_FEATURE_ENCRYPTION__STORAGE_POLICY=optional
KAIWU_FEATURE_E2EE__KEYLESS_ACCOUNTS_ENABLED=1

AUTH_ANONYMOUS_SIGNUP_ENABLED=false
AUTH_SIGNUP_PROVIDERS=github
AUTH_REQUIRED_LOGIN_PROVIDERS=github

KAIWU_FEATURE_AUTH_OAUTH__KEYLESS_ENABLED=1
KAIWU_FEATURE_AUTH_OAUTH__KEYLESS_PROVIDERS=github
KAIWU_FEATURE_AUTH_OAUTH__KEYLESS_AUTO_PROVISION=1

可选配置：当存储策略设为 optional 时，允许用户切换现有账户（e2ee ↔ plain）：

KAIWU_FEATURE_ENCRYPTION__ALLOW_ACCOUNT_OPTOUT=1

升级注意事项（运维指引）

针对有密钥账户（设备密钥模型），通常可以先升级客户端，因为旧版服务器仍兼容核心的 /v1/auth 登录流程。
在拥有支持明文存储的客户端之前，切勿启用 plaintext_only（否则旧版客户端会因加密写入被拒而报错）。
若启用了 OAuth 无密钥自动置备，请确保客户端版本足够新，能够识别 /v1/features 声明的无密钥流程（否则用户可能会遇到按钮缺失或登录失败的问题）。

OAuth 回调 URL（自托管 GitHub/OIDC 必需）

若启用了任何外部 OAuth 提供商（GitHub 或 OIDC），服务器必须明确在 OAuth 认证完成后，应将浏览器重定向回客户端应用的哪个地址。

若使用官方托管的 Web 应用，无需进行任何设置（默认为 https://kaiwu.wujilabs.cn）。
若自托管 Web 应用（或使用本地开发界面），则必须配置以下项之一：
- KAIWU_WEBAPP_URL（Web 端最常用）
- KAIWU_WEBAPP_OAUTH_RETURN_URL_BASE（常用于移动端深度链接或自定义路径）

否则，用户将被重定向至错误地址，或者重定向请求可能因不安全而被直接拒绝。

身份验证策略（环境变量）

使用以下环境变量控制账户创建权限，并决定是否强制要求提供商身份方可维持访问。

注册与登录策略

AUTH_ANONYMOUS_SIGNUP_ENABLED（默认值为 true）
- 若设为 false，则禁用匿名账户创建（新用户请求 POST /v1/auth 将返回 403 signup-disabled）。
AUTH_SIGNUP_PROVIDERS（逗号分隔值，默认为空）
- 启用基于提供商的注册（例如 github、okta）。
AUTH_REQUIRED_LOGIN_PROVIDERS（逗号分隔值，默认为空）
- 强制要求提供商身份方可维持访问权限（例如 github、okta）。

鉴权生效范围

当配置了 AUTH_REQUIRED_LOGIN_PROVIDERS 时，系统将对以下操作强制执行资格审查：

需认证的 HTTP 路由（通过 authenticate 前置处理器）
Socket.IO 握手连接（/v1/updates）

若缺失必需的提供商身份：

请求将被拒绝，并返回 403 provider-required。

权限收回与资格复核

若配置了白名单（GitHub 组织白名单或 OIDC 准入规则），服务器可定期复核用户的准入资格，并将结果缓存至身份记录中。

AUTH_OFFBOARDING_ENABLED
- 若配置了任何基于成员关系的白名单（GitHub 组织白名单或 OIDC 准入规则），该项默认设为 true；否则默认为 false。
AUTH_OFFBOARDING_INTERVAL_SECONDS（默认值为 86400，取值限制在 60 至 86400 之间）
AUTH_OFFBOARDING_STRICT（默认值为 false）
- 若设为 true，一旦因上游服务故障导致无法复核资格，服务器将采取**故障关闭（直接阻断）**策略（适用于企业严格管控模式）。

常用配置（示例）

默认配置（匿名注册）

AUTH_ANONYMOUS_SIGNUP_ENABLED=true
AUTH_SIGNUP_PROVIDERS=
AUTH_REQUIRED_LOGIN_PROVIDERS=

仅限 GitHub 注册 + 登录必须使用 GitHub

完整配置步骤请参阅 GitHub 身份验证。

仅限 OIDC 注册（例如 Okta）+ 登录必须使用 OIDC

有关提供商的详细配置，请参阅 OIDC 身份验证。

认证

On this page