无极开物Docs

OIDC 认证

为自托管服务器配置通用 OIDC 提供商（Okta/Auth0/Azure AD/Keycloak 等）。

Kaiwu 支持配置一个或多个 OIDC 提供商实例。该功能适用于企业级或自托管部署场景，特别是当企业不想使用 GitHub 作为身份提供商时。

支持哪些标准？

Kaiwu 的“自定义提供商”支持 OpenID Connect (OIDC) 1.0，采用带 PKCE 的 OAuth 2.0 授权码流程（Authorization Code Flow）。

  • 必须支持 OIDC 发现机制（即 issuer 下的 /.well-known/openid-configuration）
  • 提供商必须支持在令牌端点（token endpoint）进行授权码兑换
  • 将 id_token 声明作为主要身份档案，并可按需启用可选的 /userinfo
  • 可选存储刷新令牌（加密存储），以便在人员离职或权限回收时进行复核

如果你需要使用 SAML，建议使用身份提供商（IdP）的“OIDC 应用”或通过 SAML→OIDC 桥接器（例如 Okta、Auth0、Azure AD、Keycloak 等），然后按照下方的 OIDC 配置项接入 Kaiwu。

配置来源

可通过以下任一方式配置提供商：

  • AUTH_PROVIDERS_CONFIG_PATH（推荐）：服务器上的 JSON 文件路径
  • AUTH_PROVIDERS_CONFIG_JSON：JSON 字符串（适用于简单部署）

JSON schema (v1)

配置内容必须是一个 JSON 数组，其中每个条目定义一个提供商实例：

[
  {
    "id": "okta",
    "type": "oidc",
    "displayName": "Acme Okta",
    "issuer": "https://acme.okta.com/oauth2/default",
    "clientId": "…",
    "clientSecret": "…",
    "redirectUrl": "https://YOUR_SERVER/v1/oauth/okta/callback",

    "scopes": "openid profile email",
    "httpTimeoutSeconds": 30,
    "claims": {
      "login": "preferred_username",
      "email": "email",
      "groups": "groups"
    },
    "allow": {
      "usersAllowlist": ["alice", "bob"],
      "emailDomains": ["example.com"],
      "groupsAny": ["engineering", "platform"],
      "groupsAll": ["employees"]
    },
    "fetchUserInfo": false,
    "storeRefreshToken": false,
    "ui": {
      "buttonColor": "#111111",
      "iconHint": "okta"
    }
  }
]

说明：

  • id 将作为提供商 ID，用于策略配置（AUTH_SIGNUP_PROVIDERS=okta）和回调 URL（/v1/oauth/:provider/callback）。
  • issuer 必须指向提供商的 OIDC 签发者 URL（发现流程会请求 /.well-known/openid-configuration）。
  • 请确保你的 OIDC 应用配置中允许完全一致的 redirectUrl。
  • scopes 默认为 openid profile email，且必须包含 openid。
  • httpTimeoutSeconds（默认值为 30，取值范围限制为 1–120）：OIDC 发现及后续 OIDC 客户端配置发起的 HTTP 请求超时时间（单位：秒）。
  • claims 用于映射从何处读取提供商的用户名（login）、邮箱（email）和用户组（groups）（默认值如上所示）。
  • allow 用于限制访问资格（所有比较均转为小写）：
    • usersAllowlist：与提供商返回的登录用户名声明（login claim）进行匹配。
    • emailDomains：仅当 domain 匹配时才允许 user@domain。
    • groupsAny：用户必须处于至少一个用户组中。
    • groupsAll：用户必须处于所有用户组中。
  • fetchUserInfo（默认为 false）：若启用，服务器会拉取 /userinfo 并合并到身份档案中。
  • storeRefreshToken（默认为 false）：若启用，服务器会存储加密的刷新令牌，并通过刷新流程定期复核用户资格（处理离职或失效），无需用户重新连接。
  • ui 仅提供可选的 UI 提示信息（不影响安全性）。

用户组超限（Group overage）与外部声明

部分提供商（尤其是 Microsoft Entra ID / Azure AD）可能会在令牌中省略用户组信息，转而返回一个“超限（overage）”指示（例如 _claim_names/_claim_sources）。如果你配置了 groupsAny/groupsAll，Kaiwu 在检测到用户组超限时会采取**闭合失效（fail-closed）**策略（直接判定该用户不具备资格），除非能从配置的声明源中成功读取到用户组信息（例如启用 fetchUserInfo 并合理映射 claims.groups）。

启用 OIDC 注册与强制登录

示例：仅允许通过 Okta 注册 + 持续访问必须绑定 Okta：

AUTH_ANONYMOUS_SIGNUP_ENABLED=false
AUTH_SIGNUP_PROVIDERS=okta
AUTH_REQUIRED_LOGIN_PROVIDERS=okta

AUTH_PROVIDERS_CONFIG_PATH=/etc/KAIWU/auth-providers.json

免密钥 OIDC 登录（可选，企业版）

通过特性环境变量启用后，Kaiwu 还可以将 OIDC 提供商作为一种免密钥登录方式（无需设备密钥）。

该功能专为企业部署设计，通常与明文存储模式配合使用。详见：

最低前置条件（以提供商 ID okta 为例）：

KAIWU_FEATURE_ENCRYPTION__STORAGE_POLICY=optional|plaintext_only
KAIWU_FEATURE_E2EE__KEYLESS_ACCOUNTS_ENABLED=1

KAIWU_FEATURE_AUTH_OAUTH__KEYLESS_ENABLED=1
KAIWU_FEATURE_AUTH_OAUTH__KEYLESS_PROVIDERS=okta

若要在首次登录时允许 OIDC 登录自动创建新的免密钥/明文账户：

KAIWU_FEATURE_AUTH_OAUTH__KEYLESS_AUTO_PROVISION=1

说明：

  • 免密钥 OIDC 登录与基于密钥的 OIDC 注册是彼此独立的，你可以单独启用其中一个，也可以两者同时启用。
  • KAIWU_FEATURE_ENCRYPTION__DEFAULT_ACCOUNT_MODE 仅控制 optional 下带密钥账户的默认行为，不会限制免密钥账户的预配。
  • 在 KAIWU_FEATURE_ENCRYPTION__STORAGE_POLICY=optional 上，当提供商同时启用了带密钥预配和免密钥自动预配时，客户端在首次登录时可能会提供选择（端到端加密 vs 明文）。

自动重定向（纯 OIDC 部署）

如果 OIDC 提供商是系统唯一支持的登录/注册流程，你可以开启自动重定向，免去用户手动点击按钮的步骤：

KAIWU_FEATURE_AUTH_UI__AUTO_REDIRECT_ENABLED=1
KAIWU_FEATURE_AUTH_UI__AUTO_REDIRECT_PROVIDER_ID=<providerId>
AUTH_ANONYMOUS_SIGNUP_ENABLED=0

操作步骤：添加新的 OIDC 提供商

  1. 选取一个提供商 ID（全小写），例如 okta / auth0 / entra。
  2. 在你的 IdP 管理控制台中创建一个 OIDC 应用：
    • 授权类型（Grant type）：Authorization Code
    • 启用 PKCE
    • 添加重定向 URI：https://YOUR_SERVER/v1/oauth/<providerId>/callback
  3. 将提供商配置写入 AUTH_PROVIDERS_CONFIG_PATH（推荐）或 AUTH_PROVIDERS_CONFIG_JSON 中：
    • 精确设置 issuer、clientId、clientSecret 和 redirectUrl（必须与步骤 2 保持一致）。
  4. 在策略中启用该提供商：
    • 允许通过此提供商注册：AUTH_SIGNUP_PROVIDERS=<providerId>
    • 设置为持续访问的必需项：AUTH_REQUIRED_LOGIN_PROVIDERS=<providerId>
    • 若有需要，可禁用匿名注册：AUTH_ANONYMOUS_SIGNUP_ENABLED=false
  5. 确保客户端应用能够从 OAuth 正常返回：
    • Web 端（除非使用 https://kaiwu.wujilabs.cn，否则为必填）：设置 KAIWU_WEBAPP_URL（或 KAIWU_WEBAPP_OAUTH_RETURN_URL_BASE）
    • 移动端 Deep Link：设置 KAIWU_WEBAPP_OAUTH_RETURN_URL_BASE，并通过 KAIWU_OAUTH_RETURN_ALLOWED_SCHEMES 允许对应 scheme（例如 myapp）
  6. 验证：
    • 重启服务器（以加载环境变量和配置变更）。
    • 打开 Kaiwu 应用，确认欢迎/登录界面出现了新的登录选项。
    • 如果没有显示，请仔细核对重定向 URL、签发者 URL，并确认 AUTH_SIGNUP_PROVIDERS / AUTH_REQUIRED_LOGIN_PROVIDERS 引用了相同的提供商 ID。（排查问题时，你也可以检查 GET /v1/features。）

关于“可选”Web 应用 URL 环境变量的说明：

  • 只有在使用托管于 https://kaiwu.wujilabs.cn 的客户端时，KAIWU_WEBAPP_URL / KAIWU_WEBAPP_OAUTH_RETURN_URL_BASE 才是“可选”的。
    • 如果你是自托管 Web 应用，或使用本地开发环境的 Web UI，则必须配置其中之一，以便服务器在 OAuth 流程结束后能够重定向回你的客户端。

故障排查：

  • 如果在设置了 KAIWU_WEBAPP_URL 后仍被重定向至 https://kaiwu.wujilabs.cn，通常是因为服务器判定你配置的返回 URL 不安全并予以拒绝。本地 Web 开发时，请使用 http://localhost:PORT 或 http://*.localhost:PORT（或使用 https://）。

OIDC 之外的“自定义提供商”

目前，“自定义提供商”仅支持通过 OIDC 配置接入（尚未提供面向任意协议的插件系统）。 如果你需要接入非 OIDC 提供商，则必须在服务端和前端 UI 中将其实现为新的提供商模块（类似于内置的 GitHub 提供商）。

© 乾元执中（南京）科技有限公司 · WUJI-Labs

GitHub 认证

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

mTLS 认证

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

On this page

支持哪些标准？配置来源JSON schema (v1)用户组超限（Group overage）与外部声明启用 OIDC 注册与强制登录免密钥 OIDC 登录（可选，企业版）自动重定向（纯 OIDC 部署）操作步骤：添加新的 OIDC 提供商OIDC 之外的“自定义提供商”