ToolJet 通过 Google 作为 OIDC 身份提供方：Client ID / Client Secret 申请全流程与后端配置解析-二趣网

ToolJet 通过 Google 作为 OIDC 身份提供方：Client ID / Client Secret 申请全流程与后端配置解析

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet

本文以 ToolJet 官方文档「Google (OIDC)」为主体，完整讲解如何将 Google Cloud 配置为 ToolJet 的 OpenID Connect（OIDC）身份提供方：从在 Google Cloud 控制台创建项目、注册 OAuth 客户端、设置userinfo.email与userinfo.profile权限，到把生成的 Client ID、Client Secret 和 Well Known URL 填入 ToolJet 的 OIDC 设置；并结合 ToolJet 服务端源码，说明这些凭据在后端sso_configs实体中的存储结构、敏感字段加密机制以及通过环境变量初始化的方式，帮助读者既完成实操配置，又理解其底层实现。

Google 作为 OIDC 身份提供方在 ToolJet 中的定位

OpenID Connect（OIDC）是一种构建在 OAuth 2.0 之上的身份认证协议，它通过一个受信任的第三方身份提供方（Identity Provider, IdP）安全地验证用户身份。在 ToolJet 中，Google 可以作为一种 OIDC 身份提供方进行接入：用户在登录 ToolJet 时会被重定向到 Google 的登录页面完成身份验证，Google 签发身份凭证后，ToolJet 据此创建或匹配本地用户，实现单点登录（SSO）。

ToolJet 的 OIDC 支持是付费功能（Paid feature），并且支持两种作用域：

Instance Level（实例级）：需要Super Admin角色，入口为Settings > Instance login；
Workspace Level（工作区级）：需要Admin角色，入口为Workspace Settings > Workspace login。

从服务端实体定义看，ToolJet 在后端枚举SSOType中明确支持OPENID = 'openid'这一类型，与GOOGLE、GIT、LDAP、SAML、FORM并列，见 sso_config.entity.ts。而ConfigScope枚举则对应文档所述的两种配置作用域：ORGANIZATION（组织/工作区级）与INSTANCE（实例级），见 sso_config.entity.ts。

需要区分的是：SSOType.GOOGLE是 ToolJet 面向 Google 提供的快捷登录（GCS OAuth 流程），而本文主题SSOType.OPENID是通用的 OIDC 协议接入——Google 只是其中一个可用的身份提供方。本文聚焦后者：使用 Google 充当 OIDC IdP。

第一步：在 Google Cloud 控制台生成 Client ID 与 Client Secret

以下是官方文档给出的完整操作步骤，全部在 Google Cloud 控制台（console.cloud.google.com）完成：

1. 创建项目进入 Google Cloud 控制台并新建一个项目。

2. 进入凭据页面，创建 OAuth 客户端前往 Google Cloud 控制台的 Credentials 页面（apis/credentials），开始创建 OAuth 客户端 ID（Create OAuth client ID）。

3. 选择用户类型（User type）在 OAuth 同意屏幕（consent screen）设置中需要选择用户类型：

选择Internal（内部）：仅允许你所在 Google 工作区（Workspace）内的用户登录；
选择External（外部）：允许工作区之外的用户登录。

请根据企业策略选择，例如面向内部工具场景一般选 Internal。

4. 填写应用注册信息进入应用注册页（App registration），填写必填项，点击页面底部的SAVE AND CONTINUE按钮。

5. 配置 OAuth Scopes（关键步骤）在第二页设置 OAuth 权限。点击ADD OR REMOVE SCOPES，添加以下两个权限：

userinfo.email
userinfo.profile

这两个权限的作用是允许 ToolJet 存储登录用户的邮箱和姓名——即 Google 会在令牌（ID Token）中签发用户的 email 和 profile 声明，供 ToolJet 匹配或创建本地用户。配置完成后点击SAVE AND CONTINUE。

6. 配置回调地址（Authorized redirect URIs，关键步骤）切换到Credentials标签页，点击+ CREATE CREDENTIAL，选择OAuth client ID。选择 Application type 并填写名称；在Authorised JavaScript origins中填入 ToolJet 实际部署的域名；在Authorized redirect URIs中填入ToolJet 的 Google SSO 设置中生成的 Redirect URL（该地址需要在 ToolJet 侧先保存一次配置后才会生成，具体见下文「在 ToolJet 中配置」一节）。

7. 创建并复制凭据点击Create，复制生成的Client ID和Client secret。Client secret 属于敏感凭据，请妥善保管，不要提交到代码仓库或日志中。

8. 获取 Well Known URLOIDC 要求客户端通过身份提供方的元数据端点发现授权地址、令牌地址、JWKS 等。对于 Google，固定使用：

https://accounts.google.com/.well-known/openid-configuration

将其作为 ToolJet 中的Well Known URL参数填入。

在 ToolJet 中配置 OIDC

获得上述三项参数后，回到 ToolJet 完成最终配置（此为 OIDC 通用配置流程，Google 与 Azure AD、Okta 等提供方一致）：

点击 Dashboard 左下角的设置图标（⚙️）。
实例级：进入Settings > Instance login（示例 URL：https://app.corp.com/instance-settings/instance-login）；工作区级：进入Workspace Settings > Workspace login（示例 URL：https://app.corp.com/nexus/workspace-settings/workspace-login）。
右侧会看到各 SSO 客户端的开关，默认全部关闭。打开OpenID Connect的开关。
打开后弹出配置弹窗，包含Name、Client ID、Client secret、Well known URL等输入项。弹窗左上角有启用开关——先打开它，然后在未填写任何参数的情况下直接点击 Save changes。这一操作的目的是让 ToolJet 先生成Redirect URL（上一步在 Google Cloud 中 Authorized redirect URIs 处要填写的地址）。
将 Google Cloud 中获取的Client ID、Client Secret和Well Known URL（https://accounts.google.com/.well-known/openid-configuration）分别填入对应字段，再次点击Save changes。

保存成功后，OIDC SSO 即启用完成，用户即可通过 Google 账户完成 OpenID Connect 认证登录 ToolJet。

注意配置顺序：Google 侧的 redirect URI 依赖 ToolJet 侧生成的 Redirect URL，因此必须先在 ToolJet 弹窗中「空保存」一次拿到该地址，再回 Google Cloud 完成第 6 步，最后回 ToolJet 填入完整参数。

源码级解析：OIDC 配置在后端如何存储与使用

`OpenId`配置结构

在实体定义中，OIDC 类型对应的配置结构如下（sso_config.entity.ts）：

type OpenId = { clientId: string; clientSecret: string; name: string; customScopes: string; wellKnownUrl: string; claimName: string; groupMapping: { [key: string]: string }; enableGroupSync: boolean; enableShortSession: boolean; };

其中clientId、clientSecret、name、wellKnownUrl与文档中弹窗的四个输入项一一对应。此外还存在customScopes（自定义 OAuth scope）、claimName、groupMapping、enableGroupSync（组同步开关）等扩展字段，这些能力超出了基础 OIDC 登录本身，属于工作区级 OIDC 的进阶配置。整个sso_configs表的configs字段以 JSON 列存储（sso_config.entity.ts），同一张表承载google、git、openid、ldap、saml多种 SSO 类型，通过sso枚举列区分。

Client Secret 的加密存储

Client Secret 属于高敏感凭据。从数据迁移代码 AddInstanceLevelSSOInSSOConfigs 可以看到，当从环境变量初始化实例级 OIDC 配置时，clientSecret会先经过encryptionService.encryptColumnValue('ssoConfigs', 'clientSecret', ...)加密后再落库：

{ configScope: ConfigScope.INSTANCE, sso: SSOType.OPENID, enabled: !!envVars?.SSO_OPENID_CLIENT_ID, configs: { clientId: envVars?.SSO_OPENID_CLIENT_ID || '', name: envVars?.SSO_OPENID_NAME || '', clientSecret: (envVars?.SSO_OPENID_CLIENT_SECRET && (await encryptionService.encryptColumnValue( 'ssoConfigs', 'clientSecret', envVars.SSO_OPENID_CLIENT_SECRET ))) || '', wellKnownUrl: envVars?.SSO_OPENID_WELL_KNOWN_URL || '', }, },

同时可以确认三个环境变量到 OIDC 配置的映射关系：

环境变量	对应配置字段	作用
`SSO_OPENID_CLIENT_ID`	`clientId`	同时决定是否启用该 OIDC 配置（非空即`enabled`）
`SSO_OPENID_CLIENT_SECRET`	`clientSecret`	加密后存储
`SSO_OPENID_WELL_KNOWN_URL`	`wellKnownUrl`	OIDC 元数据端点，Google 即`https://accounts.google.com/.well-known/openid-configuration`

这意味着在自托管（self-hosted）部署场景下，运维团队也可以不依赖界面、直接通过环境变量完成 OIDC 配置——这与界面配置的字段完全一致。

认证流程接口

从源码结构看，OIDC 授权流程的交互逻辑位于认证模块的 OAuth 子包中：IOidcService 接口定义了三个核心方法——

getConfigs(configId, codeChallenge?)：返回codeVerifier与authorizationUrl，其中codeChallenge参数表明实现了 PKCE 代码挑战机制，用于增强授权码流程的安全；
handleOIDCConfigs(response, configId)：处理重定向响应，返回authorizationUrl供浏览器跳转到身份提供方；
signIn(code, configs)：用授权码换取令牌并解析用户身份。

结合 Well Known URL 的工作方式可以推断：ToolJet 会先请求https://accounts.google.com/.well-known/openid-configuration获得 Google 的授权端点与 JWKS 端点，随后按标准 OIDC 授权码流程完成重定向登录，而不需要为每个提供方硬编码端点地址。

测试中的佐证

服务端测试同样印证了这套字段结构。例如 organizations.spec.ts 中构造的 OIDC 配置：

wellKnownUrl: 'https://idp.example.com/.well-known/openid-configuration',

而 util.service.spec.ts 则覆盖了登录配置工具服务对wellKnownUrl等字段的处理逻辑，可作为理解 OIDC 配置读取路径的参考。

小结

接入 Google 作为 ToolJet 的 OIDC 身份提供方，核心是三件事：在 Google Cloud 创建 OAuth 客户端并授予userinfo.email、userinfo.profile权限；把 ToolJet 生成的 Redirect URL 注册为 Google 侧的授权回调；最后将 Client ID、Client Secret 与固定 Well Known URL（https://accounts.google.com/.well-known/openid-configuration）填入 ToolJet 的 OIDC 设置。后端侧，这些参数以 JSON 形式存入sso_configs表（SSOType.OPENID），Client Secret 经列级加密落库，并支持通过SSO_OPENID_CLIENT_ID/SSO_OPENID_CLIENT_SECRET/SSO_OPENID_WELL_KNOWN_URL环境变量初始化，适用于自托管部署的自动化配置场景。

企业官网建设流程全解析