GitHub 认证

为自托管服务器配置 GitHub OAuth（注册与连接）及可选的 GitHub 白名单。

本指南介绍 Kaiwu 服务器上的 GitHub 认证配置：

GitHub OAuth（注册与关联）
强制将 GitHub 作为必选登录提供商
可选白名单（用户/组织）及人员离职下线机制

快速入门：GitHub 注册（公网服务器推荐配置）

当希望用户通过 GitHub 注册并禁用匿名注册时，可采用此方案。

注意：Kaiwu 账户本质上仍是设备密钥账户。GitHub 仅作为绑定的身份提供商（用于注册、关联及策略管控），并不能替代设备密钥登录。

界面提示：

若同时启用了匿名注册与 GitHub 注册，欢迎界面会显示创建账户与通过 GitHub 继续。
若禁用了匿名注册，欢迎界面仅显示通过 GitHub 继续（不再提供匿名的“创建账户”选项）。

1) 创建 GitHub OAuth App

Kaiwu 的 OAuth 重定向流程基于 GitHub OAuth App（而非 GitHub App）。

打开 GitHub，前往 Settings → Developer settings → OAuth Apps → New OAuth App。
将 Authorization callback URL 设置为：
- https://YOUR_SERVER/v1/oauth/github/callback
创建应用并保存以下凭据：
- Client ID
- Client secret

注意事项：

Kaiwu 服务器目前直接与 github.com / api.github.com 通信，因此该配置仅适用于 GitHub.com（不适用于 GitHub Enterprise Server）。
回调 URL 的协议、主机名和路径必须与 GITHUB_REDIRECT_URL 中的配置完全一致。
GitHub 通常要求使用 https:// 回调 URL，仅 http://localhost:PORT/... 等本地环回开发地址例外。
无需启用 GitHub 的“Device Flow / 设备认证流”。Kaiwu 服务器采用标准的浏览器重定向 OAuth 流程，保持“Enable Device Flow”处于禁用状态即可。

2) 配置服务器

在 apps/server 上设置以下环境变量（参见 apps/server/.env.example）：

# GitHub OAuth (OAuth App)
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GITHUB_REDIRECT_URL=https://YOUR_SERVER/v1/oauth/github/callback

# OAuth return redirect back to the client (required unless you are using https://kaiwu.wujilabs.cn)
# - Web: set this to the URL you open in the browser for the Kaiwu web app (self-hosted or local dev).
# - Mobile: use KAIWU_WEBAPP_OAUTH_RETURN_URL_BASE + KAIWU_OAUTH_RETURN_ALLOWED_SCHEMES instead.
KAIWU_WEBAPP_URL=https://YOUR_WEBAPP

# Auth policy
AUTH_ANONYMOUS_SIGNUP_ENABLED=false
AUTH_SIGNUP_PROVIDERS=github
AUTH_REQUIRED_LOGIN_PROVIDERS=github

备选配置（移动端 Deep Link 返回）：

KAIWU_WEBAPP_OAUTH_RETURN_URL_BASE=myapp://oauth
KAIWU_OAUTH_RETURN_ALLOWED_SCHEMES=myapp

3) 验证配置是否生效

重启服务器。
检查 GET /v1/features，确认：
- capabilities.oauth.providers.github.configured 为 true
打开 Kaiwu 应用，确认界面已出现“通过 GitHub 继续”选项。
若你的 GitHub 用户名已被占用（或不符合用户名格式规范），Kaiwu 会在注册过程中提示你另选用户名，这属于正常现象。
- 重要提示：该流程属于注册（创建新的 Kaiwu 账户）。若需在另一台设备上通过 GitHub“登录”已有的 Kaiwu 账户，必须使用设备密钥恢复（例如选择添加手机 / 恢复账户），随后在设置 → 账户中关联 GitHub。

排错指南：

若出现类似“provider already linked”的错误，说明该 GitHub 身份已与当前服务器上的某个 Kaiwu 账户绑定。
- 请在该设备或浏览器中使用设备密钥恢复登入该账户，之后即可继续使用。

免密钥 GitHub 登录（可选，企业特性）

Kaiwu 还支持将 GitHub OAuth 作为一种免密钥登录方式（无需设备密钥）。

该方案适用于以下企业部署场景：

希望实现跨设备无缝登录（无需提示输入恢复密钥）；且
接受将新增会话内容以明文形式存储在服务器上（或本身已采用全明文存储运行）。

最低前置要求：

# Keyless accounts require a storage policy that allows plaintext
KAIWU_FEATURE_ENCRYPTION__STORAGE_POLICY=optional|plaintext_only

# Enable keyless accounts (enterprise)
KAIWU_FEATURE_E2EE__KEYLESS_ACCOUNTS_ENABLED=1

# Enable keyless OAuth and allow GitHub as a keyless provider
KAIWU_FEATURE_AUTH_OAUTH__KEYLESS_ENABLED=1
KAIWU_FEATURE_AUTH_OAUTH__KEYLESS_PROVIDERS=github

若要允许用户在首次通过 GitHub 登录时自动创建免密钥/明文账户：

KAIWU_FEATURE_AUTH_OAUTH__KEYLESS_AUTO_PROVISION=1

注意事项：

免密钥 GitHub 登录与带密钥的 GitHub 注册是相互独立的机制，可单独或同时开启。
KAIWU_FEATURE_ENCRYPTION__DEFAULT_ACCOUNT_MODE 仅控制 optional 下带密钥账户的默认设置，不会限制免密钥账户的置备。
在 KAIWU_FEATURE_ENCRYPTION__STORAGE_POLICY=optional 模式下，若 GitHub 同时启用了带密钥置备与免密钥自动置备，客户端可能会在首次登录时提供选项（端到端加密 vs 明文）。详见服务器认证。

自动重定向（仅支持 GitHub 部署）

若 GitHub 是系统中唯一支持的登录与注册流程，可启用自动重定向，免去用户手动点击按钮的操作：

KAIWU_FEATURE_AUTH_UI__AUTO_REDIRECT_ENABLED=1
KAIWU_FEATURE_AUTH_UI__AUTO_REDIRECT_PROVIDER_ID=github
AUTH_ANONYMOUS_SIGNUP_ENABLED=0

服务器环境变量（GitHub OAuth）

必选：

GITHUB_CLIENT_ID
GITHUB_CLIENT_SECRET
GITHUB_REDIRECT_URL（推荐）或旧版配置 GITHUB_REDIRECT_URI
- 必须设置为：https://YOUR_SERVER/v1/oauth/github/callback

必选（除非直接使用托管于 https://kaiwu.wujilabs.cn 的官方客户端）：

KAIWU_WEBAPP_URL（默认值 https://kaiwu.wujilabs.cn）

可选（通常仅在支持移动端 Deep Link 或自定义 URL Scheme 时需要）：

KAIWU_WEBAPP_OAUTH_RETURN_URL_BASE
KAIWU_OAUTH_RETURN_ALLOWED_SCHEMES
OAUTH_STATE_TTL_SECONDS（默认值 600，取值区间限制在 60–3600）
OAUTH_PENDING_TTL_SECONDS（默认值 600，取值区间限制在 60–3600；旧版降级配置：GITHUB_OAUTH_PENDING_TTL_SECONDS）
GITHUB_HTTP_TIMEOUT_SECONDS（默认值 10，取值区间限制在 1–120）

注意事项：

GITHUB_REDIRECT_URL 必须能够被 GitHub 访问（用户完成 OAuth 授权后，GitHub 会将浏览器重定向至该地址）。
若服务器部署在反向代理之后，GITHUB_REDIRECT_URL 应填写公网可访问的 URL（而非容器内部主机名）。
只有在使用托管于 https://kaiwu.wujilabs.cn 的官方客户端时，KAIWU_WEBAPP_URL / KAIWU_WEBAPP_OAUTH_RETURN_URL_BASE 才是“可选”的。
- 若自托管 Web 应用或在本地开发 Web 界面，则必须配置其中之一，以便服务器在 OAuth 流程完成后能重定向回客户端。

OAuth 客户端返回 URL（高级）

服务器处理完 GitHub 的回调后，会将浏览器重定向回客户端以完成整个流程。

默认返回基础路径：KAIWU_WEBAPP_URL（https://kaiwu.wujilabs.cn）
- 除非主动覆盖，否则服务器默认重定向至 ${KAIWU_WEBAPP_URL}/oauth/github?...。
覆盖返回基础路径（不包含提供商后缀）：KAIWU_WEBAPP_OAUTH_RETURN_URL_BASE
- 示例：https://app.example.com/custom-oauth → 重定向至 https://app.example.com/custom-oauth/github?...
允许返回重定向使用其他 URL Scheme：KAIWU_OAUTH_RETURN_ALLOWED_SCHEMES
- 用于移动端 Deep Link（例如 myapp）
- http:// 仅允许用于 localhost、127.0.0.1 及 *.localhost 等本地环回主机，非环回主机禁止使用。

排错指南：

若配置了 KAIWU_WEBAPP_URL 后仍被重定向至 https://kaiwu.wujilabs.cn，多半是因为服务器判定所配置的返回 URL 存在安全隐患并进行了拦截。本地 Web 开发请使用 http://localhost:PORT 或 http://*.localhost:PORT（亦可使用 https://）。

OAuth 权限范围（Scopes）

服务器请求的 OAuth Scope 如下：

默认请求：read:user
仅当启用组织白名单且配置了 AUTH_GITHUB_ORG_MEMBERSHIP_SOURCE=oauth_user_token 时，才会追加申请 read:org

GitHub 白名单（准入资格）

重要说明：

所有配置值均会统一转换为小写处理。
白名单仅在 AUTH_REQUIRED_LOGIN_PROVIDERS 中包含 GitHub 时才会对访问权限生效。

用户白名单

AUTH_GITHUB_ALLOWED_USERS（以逗号分隔的 GitHub 用户名列表）

若配置了该项且登录强制要求 GitHub，用户必须位于此列表中，否则会收到 403 not-eligible。

组织白名单

AUTH_GITHUB_ALLOWED_ORGS（以逗号分隔的组织 Slug 列表）
AUTH_GITHUB_ORG_MATCH（any/all，默认值 any）

若配置了该项且登录强制要求 GitHub，用户必须隶属于允许的组织。系统会按照离职下线检查周期定期复核成员资格。

组织成员资格验证源（重要）

AUTH_GITHUB_ORG_MEMBERSHIP_SOURCE 控制服务器如何验证用户的组织成员资格：

github_app（推荐方案）
oauth_user_token（使用用户的 OAuth 令牌，需要 read:org 权限）

默认行为：

若 AUTH_GITHUB_ALLOWED_ORGS 为空 → oauth_user_token（不进行组织检查）
若配置了 AUTH_GITHUB_ALLOWED_ORGS → 默认采用 github_app

这意味着：如果配置了 AUTH_GITHUB_ALLOWED_ORGS 却未配置 GitHub App 模式，所有用户都将被判定为不具备准入资格。

GitHub App 模式（组织管控推荐方案）

GitHub App 模式无需依赖用户的 OAuth 令牌。即便用户撤销了 OAuth 授权，组织的管控策略依然能够稳定执行。

服务器环境变量（GitHub App 模式）

AUTH_GITHUB_APP_ID
AUTH_GITHUB_APP_PRIVATE_KEY（PEM 格式）
AUTH_GITHUB_APP_INSTALLATION_ID_BY_ORG（CSV 格式映射，形如 acme=123,other=456）

GitHub 配置步骤（GitHub App）

创建 GitHub App：前往 Settings → Developer settings → GitHub Apps → New GitHub App。
生成私钥（Private Key），将 PEM 内容复制到 AUTH_GITHUB_APP_PRIVATE_KEY 中。
配置验证成员资格所需的最低权限：
- Organization permissions → Members: Read
将该应用安装到所有需要允许访问的组织中。
获取每个组织的 Installation ID，并配置到 AUTH_GITHUB_APP_INSTALLATION_ID_BY_ORG 中。

获取 Installation ID 小贴士：

安装应用后，在安装管理页点击 Configure，页面 URL 中通常包含 installations/⟦K9⟧。

基于用户 OAuth 令牌验证组织资格（备选方案）

若无法采用 GitHub App 模式，也可以利用用户的 OAuth 令牌来验证组织成员资格：

AUTH_GITHUB_ALLOWED_ORGS=acme
AUTH_GITHUB_ORG_MEMBERSHIP_SOURCE=oauth_user_token
GITHUB_STORE_ACCESS_TOKEN=true

注意事项：

用户在 OAuth 授权期间会收到申请 read:org 权限的提示。
定期复核组织资格需要持久化存储令牌；若禁用了令牌存储，组织检查将会失败，导致用户失去准入资格。
若在用户已关联 GitHub 后才切换为该模式，用户可能需要先解绑再重新关联，以便服务器能够保存用于检查成员资格的令牌。

令牌存储（高级）

GITHUB_STORE_ACCESS_TOKEN 用于控制服务器是否持久化存储 GitHub 访问令牌（静态加密存储）。

常规配置下默认为：false（如 Friends 模式或基础 GitHub 关联）
当通过 oauth_user_token 启用组织检查时，实际默认为：true（离职下线检查必须依赖该令牌）

配置示例

仅允许 GitHub 注册 + 强制使用 GitHub 登录

AUTH_ANONYMOUS_SIGNUP_ENABLED=false
AUTH_SIGNUP_PROVIDERS=github
AUTH_REQUIRED_LOGIN_PROVIDERS=github

混合模式（匿名 + GitHub 注册）

适用于私有服务器（如通过 VPN、Tailscale 或局域网访问）。该模式下既保留匿名账户，同时提供“通过 GitHub 继续”的登录选项。

AUTH_ANONYMOUS_SIGNUP_ENABLED=true
AUTH_SIGNUP_PROVIDERS=github
AUTH_REQUIRED_LOGIN_PROVIDERS=

仅允许 GitHub + 限制特定组织（GitHub App 模式）

AUTH_ANONYMOUS_SIGNUP_ENABLED=false
AUTH_SIGNUP_PROVIDERS=github
AUTH_REQUIRED_LOGIN_PROVIDERS=github

AUTH_GITHUB_ALLOWED_ORGS=acme
AUTH_GITHUB_ORG_MEMBERSHIP_SOURCE=github_app
AUTH_GITHUB_APP_ID=...
AUTH_GITHUB_APP_PRIVATE_KEY=...
AUTH_GITHUB_APP_INSTALLATION_ID_BY_ORG=acme=123

On this page