企业官网建设流程全解析

ToolJet REST API 数据源认证配置指南：Basic、Bearer Token 与 OAuth 2.0 全解析

【免费下载链接】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 官方文档（docs/versioned_docs/version-3.0.0-LTS/data-sources/restapi/authentication.md）为主体，系统讲解 ToolJet REST API 数据源支持的三种认证方式——Basic 认证、Bearer Token 认证与 OAuth 2.0 认证的完整配置流程。读完本文，你将能够在 ToolJet 中为 REST API 数据源正确配置认证参数、处理 SSL 证书校验，并完成一次完整的 OAuth 2.0 授权码流程（以 Google Cloud Platform 为例），同时了解这些认证方式在 ToolJet 源码中的底层实现原理。

认证类型总览

ToolJet 的 REST API 数据源支持多种认证类型，用于在与 REST API 服务交互时完成用户身份验证。受支持的认证类型包括：

• Basic：HTTP 协议内置的简单认证方案
• Bearer：由认证服务器签发、客户端携带访问受保护资源的令牌
• OAuth 2.0：支持Authorization Code（授权码）与Client Credentials（客户端凭证）两种授权类型

此外，从 REST API 插件清单 可以看到，该数据源还支持apiKey（API Key）、aws_v4（AWS Signature V4）与none（无认证）等选项，其中auth_type的默认值为none。

在源码层面，认证类型的分派发生在 REST API 查询服务（plugins/packages/restapi/lib/index.ts）中：当auth_type为aws_v4时走签名逻辑，其余类型统一交由公共模块的validateAndSetRequestOptionsBasedOnAuthType函数处理。该函数（plugins/packages/common/lib/oauth.ts）内部按auth_type的值进行switch分发，分别进入 OAuth、Bearer、API Key、Basic 四种处理分支，最终返回带有认证信息的请求配置。

Basic 认证

Basic Authentication是内置于 HTTP 协议的简单认证方案。客户端在请求头中以Authorization: Basic <base64(username:password)>的形式携带凭证，服务器解码后校验。

配置带 Basic 认证的 REST API 数据源

1. 在 ToolJet 仪表盘进入Data Sources（数据源）页面，在侧边栏选择API分类，然后选择REST API数据源。
2. 在Base URL字段中输入基础 URL，该字段指定 API 服务的网络地址，例如http://localhost:3001/api/basic-auth。
3. 如需自定义请求头，填写Headers（键值对，随每次 REST API 请求一起发送）。
4. 从下拉框中将Authentication类型选择为Basic。
5. 在对应字段中输入Username（用户名）和Password（密码），这两个值即为认证所需的用户凭证。

Basic 认证的底层实现

Basic 认证在公共模块中由handleBasicAuthentication函数处理（plugins/packages/common/lib/oauth.ts）。实现非常直接：将sourceOptions中的username与password原样写入请求配置，最终由 HTTP 客户端（got）在发送请求时自动完成Authorization: Basic头的构造。请注意，密码字段在数据源清单中被标记为encrypted: true（plugins/packages/restapi/lib/manifest.json），即 ToolJet 会对其加密存储。

Bearer Token 认证

Bearer Token是由认证服务器签发、发放给客户端的安全令牌。客户端携带该令牌访问资源服务器上受保护的资源，请求头形式为Authorization: Bearer <token>。

配置带 Bearer Token 的 REST API 数据源

1. 在 ToolJet 仪表盘进入Data Sources（数据源）页面，在侧边栏选择API分类，然后选择REST API数据源。
2. 在Base URL字段中输入基础 URL，例如http://localhost:3001/api/bearer-auth。
3. 如需自定义请求头，填写Headers。
4. 从下拉框中将Authentication类型选择为Bearer。
5. 在Token字段中输入令牌。该令牌由认证服务器签发，客户端用它访问受保护资源。

6. 接下来可以按需选择SSL Certificate（SSL 证书）。SSL 证书用于校验服务器证书，默认值为None。你可以在下拉框中选择CA Certificate或Client Certificate：

   1. CA Certificate（CA 证书）：需要一份 CA 证书用于校验服务器证书。将server.crt文件的内容复制并粘贴到CA Cert字段中。server.crt是用于校验服务器证书的证书文件。
   2. Client Certificate（客户端证书）：需要客户端证书与服务端进行双向 TLS 认证。其中client.key、client.crt与server.crt是用于认证的证书文件。将client.key文件内容粘贴到Client Key字段，将client.crt文件内容粘贴到Client Cert字段，将server.crt文件内容粘贴到CA Cert字段。

7. 配置完成后，点击Save（保存）按钮保存数据源。

验证认证是否成功

创建一个查询，向该 URL 发起GET请求。如果令牌有效，接口将返回成功消息。

Bearer 认证与 SSL 证书的源码实现

Bearer 认证由handleBearerAuthentication函数处理（plugins/packages/common/lib/oauth.ts）：它直接把Authorization: Bearer ${sourceOptions.bearer_token}写入请求头。同样，bearer_token在数据源清单中被标记为加密存储（plugins/packages/restapi/lib/manifest.json）。

SSL 证书的处理则发生在 REST API 插件的fetchHttpsCertsForCustomCA方法中（plugins/packages/restapi/lib/index.ts）：

• ssl_certificate为ca_certificate时，将ca_cert作为certificateAuthority注入 HTTPS 请求；
• ssl_certificate为client_certificate时，同时注入certificateAuthority、客户端私钥key（client_key）与客户端证书certificate（client_cert），实现双向 TLS；
• ssl_certificate为none时，设置rejectUnauthorized: false，即跳过服务器证书校验；
• 若环境变量NODE_EXTRA_CA_CERTS存在，还会把系统根证书与该文件中的 CA 证书合并注入。

清单文件（plugins/packages/restapi/lib/manifest.json）中ca_cert、client_key、client_cert均为加密字段，且下拉框的可选值与文档描述一致（CA certificate / Client certificate / None）。

OAuth 2.0 认证

ToolJet 的 REST API 数据源支持OAuth 2.0认证，受支持的授权类型（Grant Type）为：

• Authorization Code（授权码）：用于机密客户端与公开客户端，通过交换授权码换取访问令牌（Access Token）。
• Client Credentials（客户端凭证）：用于客户端在脱离用户上下文的情况下直接获取访问令牌。

从数据源清单的默认值（plugins/packages/restapi/lib/manifest.json）可以看到：grant_type默认值为authorization_code，add_token_to默认值为header，header_prefix默认值为Bearer（注意末尾带空格），client_auth默认值为body，scopes默认值为read, write。这些默认值在下面的配置步骤中会被反复用到。

在 Google Cloud Platform 上创建 OAuth 应用

:::info 在 ToolJet 中配置 REST API 数据源之前，需要先在Google Cloud Platform（GCP）完成配置，获取授权所需的 API 密钥。 :::

GCP 提供了 350 多个 API 与服务，可以让我们访问 Google 账户及其服务中的数据。下面创建一个 OAuth 应用，授权其读取 Google 个人资料数据（如姓名与头像）。

1. 登录 Google Cloud 账号，在控制台中创建一个新项目（New Project）。
2. 进入APIs and Services（API 和服务），从左侧边栏打开OAuth consent screen（OAuth 同意屏幕）。
3. 填写应用详细信息，并为应用选择合适的Scopes（范围）。本示例选择profile与email两个 scope。
4. 创建好 OAuth 同意屏幕后，在左侧边栏的Credentials（凭据）部分新建OAuth client ID（OAuth 客户端 ID）凭据。
5. 选择应用类型、填写应用名称，然后在Authorized Redirect URIs（授权重定向 URI / 回调 URL）下添加以下 URI：
   1. https://app.tooljet.com/oauth2/authorize（使用 ToolJet Cloud 时）
   2. http://localhost:8082/oauth2/authorize（本地运行 ToolJet 时）

6. 保存后，你将获得应用的Client ID 和 Client Secret。

将 ToolJet 应用配置为使用 Google 的 OAuth 2.0 API

按照以下步骤授权 ToolJet 访问你的 Google 个人资料数据：

1. 在 ToolJet 仪表盘进入Data Sources（数据源）页面，在侧边栏选择 API 分类，然后选择REST API数据源。
2. 在Base URL字段中输入基础 URL：https://www.googleapis.com/oauth2/v1/userinfo。
3. 将Authentication类型选择为OAuth 2.0。
4. 保持Grant Type、Add Access Token To、Header Prefix的默认值不变，即分别为Authorization Code、Request Header、Bearer。
5. 输入Access Token URL：https://oauth2.googleapis.com/token。该端点用于验证用户身份，并返回唯一的访问令牌。
6. 输入在 Google Console 生成的Client ID与Client Secret。
7. 在Scope字段中输入https://www.googleapis.com/auth/userinfo.profile。Scope 是 OAuth 2.0 中用于限制应用对用户账户访问范围的机制。
8. 输入Authorization URL：https://accounts.google.com/o/oauth2/v2/auth。该 URL 向用户请求授权，并重定向以从身份服务器获取授权码。
9. 创建三个Custom Authentication Parameters（自定义认证参数）：
   1. response_type：code（code即授权码 Authorization Code）
   2. client_id：你的 Client ID
   3. redirect_url：本地使用 ToolJet 时填http://localhost:8082/oauth2/authorize，使用 ToolJet Cloud 时填https://app.tooljet.com/oauth2/authorize
10. 保持Client Authentication的默认选择，然后Save（保存）数据源。

验证 OAuth 2.0 认证

创建查询以对 URL 发起GET请求，此时会弹出一个新窗口，要求用户针对该 API 进行身份验证：

• 添加一个新查询，从下拉框中选择 REST API 数据源；
• 在Method下拉框中选择GET，并开启Run query on application load?（应用加载时运行查询）；
• 运行查询；
• 将弹出新的窗口进行认证，认证成功后再次运行查询，即可获取如姓名与头像等用户数据。

OAuth 2.0 的源码实现原理

从源码可以完整还原 OAuth 2.0 在 ToolJet 中的执行链路：

授权码流程（Authorization Code）。当查询执行且当前没有可用令牌时，handleAuthorizationCodeGrant函数会返回status: 'needs_oauth'及auth_url（plugins/packages/common/lib/oauth.ts）。REST API 查询服务检测到该状态后直接返回，不再发起真实请求（plugins/packages/restapi/lib/index.ts），前端随即引导用户跳转授权页面。授权 URL 由getAuthUrl函数构造（plugins/packages/common/lib/oauth.ts）：它基于auth_url、response_type=code、client_id、redirect_uri（拼接自环境变量TOOLJET_HOST与SUB_PATH的/oauth2/authorize路径）以及scope拼接而成，同时把custom_query_params中的自定义参数追加到 URL 上。

令牌注入。当令牌已存在时，validateAndMaybeSetOAuthHeaders会从tokenData中取出access_token，并依据add_token_to配置注入请求头——若为header，则写入Authorization: ${header_prefix}${access_token}（plugins/packages/common/lib/oauth.ts）。这与文档中“Header Prefix 默认值为 Bearer”的配置相互印证。

客户端凭证流程（Client Credentials）。当grant_type为client_credentials时，handleClientCredentialsGrant会直接调用getTokenForClientCredentialsGrant（plugins/packages/common/lib/oauth.ts）：请求体携带grant_type、可选audience与scope；若client_auth为header，则将client_id:client_secret做 Base64 编码放入Authorization: Basic头，否则把两者放入表单请求体。请求发送前还会通过validateUrlForSSRF校验 token URL，防止服务端请求伪造（SSRF）。

令牌刷新。当 API 返回 401 且认证类型为oauth2时，查询服务会抛出OAuthUnauthorizedClientError（plugins/packages/restapi/lib/index.ts），触发refreshToken流程。getRefreshedToken（plugins/packages/common/lib/oauth.ts）使用refresh_token调起grant_type=refresh_token的令牌刷新请求，并校验响应中必须包含access_token，刷新成功后新的令牌会回写存储，供后续查询使用。

回调端点。在服务端，OAuth 回调由数据源模块处理，回调地址形如${tooljetHost}/oauth2/authorize（server/src/modules/data-sources/util.service.ts）。因此文档中要求在 GCP 授权重定向 URI 中填写https://app.tooljet.com/oauth2/authorize（Cloud）或http://localhost:8082/oauth2/authorize（本地），二者必须与 ToolJet 实际部署的主机地址保持一致，否则授权码将无法正确回传。

小结

ToolJet 的 REST API 数据源通过统一的认证分派机制，将 Basic、Bearer、OAuth 2.0（授权码/客户端凭证）、API Key 与 AWS SigV4 等认证方式收敛到同一套查询执行链路中。配置时只需遵循“选择认证类型 → 填写对应凭证 → 保存并建查询验证”的通用流程：

对于生产环境中的自托管部署，请务必确认回调 URL 与你的 ToolJet 实例主机（TOOLJET_HOST与SUB_PATH环境变量）一致，并对client_secret、bearer_token、CA/客户端证书等敏感字段启用加密存储（清单中已默认标记为encrypted）。如需深入了解数据源插件的完整结构，可继续阅读 REST API 插件清单 与 插件公共模块。

【免费下载链接】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