ToolJet 集成 Azure AD（Entra ID）实现 OpenID Connect 单点登录（SSO）完整配置指南

ToolJet 集成 Azure AD（Entra ID）实现 OpenID Connect 单点登录（SSO）完整配置指南

【免费下载链接】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 的 Azure AD（现 Microsoft Entra ID）OpenID Connect 单点登录配置文档为主体，逐步演示如何在 Azure 门户完成应用注册、客户端密钥创建，并在 ToolJet 的实例级或工作区级 SSO 设置中完成 Client ID、Client Secret 与 Well Known URL 的对接。读完本文，你将能够独立完成从 Azure 侧注册应用到 ToolJet 侧启用 OIDC 登录的全流程，并理解底层配置存储与鉴权链路的实现原理。

ToolJet 的 SSO 与 OpenID Connect 概览

单点登录（SSO）允许用户使用一套凭据访问多个应用与服务，从而减少重复登录、降低密码疲劳并提升安全合规水平。ToolJet 官方支持多种 SSO 方式，包括 GitHub、Google、OpenID Connect、LDAP 与 SAML，其中 OpenID Connect（OIDC）是构建在 OAuth 2.0 之上的身份认证协议，应用可通过它借助外部身份提供商（IdP）来验证用户身份。

在 ToolJet 中，OIDC 是一类受许可控制的功能：前端许可证提示组件将OpenID Connect明确列入付费特性列表（参见 LicenseTooltip/index.jsx），OIDC 设置文档 也标注其为Paid feature。通过 OIDC，ToolJet 可与Azure AD、Google 或 Okta 等身份提供商对接，为企业用户提供统一、安全的认证入口。

配置 OIDC 需要满足如下权限要求：

• 实例级（Instance Level）：需要Super Admin（超级管理员）角色；
• 工作区级（Workspace Level）：需要Admin（管理员）角色。

第一步：在 Azure AD 门户中注册应用程序

Azure AD（Entra ID）侧的配置是整个过程的前提，ToolJet 会作为 OIDC 客户端与 Azure 签发并校验的身份令牌对接。在 Azure 门户中按以下步骤创建应用：

1. 打开你的组织页面，选择App registrations（应用注册），然后点击New registration（新建注册），进入应用注册流程：

2. 在注册表单中填写如下信息：

   • Name（名称）：为该应用指定一个可识别的显示名称；
   • Supported account types（支持的账户类型）：根据你的组织需求选择账户范围（例如仅本组织、多租户目录等），这决定了哪些账户可以通过该应用登录 ToolJet；
   • Redirect URI（重定向 URI）：在平台类型中选择 Web，并将 ToolJet 提供的重定向地址粘贴进来。该地址可在 ToolJet 控制台的Manage SSO → Open Id → Redirect URL处复制获取。

3. 填写完毕后点击Register（注册），应用即注册成功：

重定向 URI 是 OIDC 授权码流程中 IdP 回跳 ToolJet 的地址，必须与 ToolJet 端生成的 Redirect URL 完全一致，否则登录时会出现回调地址不匹配的错误。因此建议先进入 ToolJet 的 Open ID 配置页面触发 Redirect URL 生成，再回到 Azure 侧填写。

第二步：将 Application (Client) ID 配置为 Client ID

应用注册完成后，Azure 门户的Essentials（基本信息）区域会展示该应用的标识信息，其中Application (client) ID（应用程序（客户端）ID）是 OIDC 客户端的公开标识：

在 ToolJet 的Open Id 配置页面中，将该值填入client id字段。这一字段在服务端对应SSOConfigs实体中OpenId配置类型的clientId属性（参见 sso_config.entity.ts）。

第三步：创建并配置客户端密钥（Client Secret）

OIDC 客户端在向 Azure 换取令牌时需要证明自己的身份，因此必须创建客户端密钥：

1. 在应用页面的Client credentials（客户端凭据）区域，点击Add a certificate or secret（添加证书或密钥）；
2. 点击+ New Client Secret（新建客户端密钥）；
3. 为密钥填写Description（描述），设置Expires（过期时间），然后点击Add（添加）；
4. 密钥创建成功后，立即复制生成的 Value（值）（离开页面后 Azure 将不再展示明文），并将其填入 ToolJet Open Id 配置页面的client secret字段。

安全提醒：客户端密钥属于敏感凭据。在 ToolJet 服务端，clientSecret等含secret的字段在存储时会进行加密处理，且对外返回配置时会被脱敏隐藏（详见下文"源码层面的实现支撑"）。但出于安全最佳实践，仍建议设置合理的密钥过期时间并定期轮换。

第四步：品牌化重定向页面（可选）

Azure AD 允许通过Branding and properties（品牌和属性）选项自定义登录重定向页面的品牌展示（例如 Logo、公司名称与配色），使 SSO 登录体验与你的企业形象保持一致。该步骤为可选优化项，不影响 SSO 功能本身，但对面向终端用户的登录界面观感有直接影响。

构造 Well Known URL（OIDC 发现端点）

在 ToolJet 的 Open ID 配置中，Well known URL是一个关键参数：OIDC 客户端依赖它自动发现授权端点、令牌端点、JWKS 公钥与 issuer 等元数据，从而无需手工逐项填写端点地址。ToolJet 通过该 URL 完成对 Azure AD 的身份发现与信任建立。

对于 Azure AD（Entra ID），Well Known URL 采用其标准的 OIDC 发现端点格式，形如：

https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration

其中{tenant-id}需要替换为你的目录（租户）ID，可从应用注册页面的Directory (tenant) ID获取。

这一域名约定在 ToolJet 服务端同样有迹可循：工具函数isAzureEntraIdIssuer会依据 issuer 是否包含microsoftonline.com等微软域来判断签发者是否为 Azure Entra ID（参见 utils.helper.ts），与 Well Known URL 的域名构成相互印证。

在 ToolJet 侧启用 OpenID Connect 并完成配置

Azure 侧的准备完成后，回到 ToolJet 控制台完成最终的 OIDC 启用（以下步骤继承自 OIDC 设置文档）：

1. 点击仪表盘左下角的设置图标（⚙️）；
2. 进入对应级别的登录设置页面：
   • 实例级：Settings > Instance login（示例地址形如https://app.corp.com/instance-settings/instance-login）；
   • 工作区级：Workspace Settings > Workspace login（示例地址形如https://app.corp.com/nexus/workspace-settings/workspace-login）；
3. 在右侧的 SSO 客户端列表中，所有开关默认处于关闭状态，打开OpenID Connect对应的开关；
4. 开关打开后会弹出配置弹窗，包含Name、Client ID、Client secret、Well known URL等输入项。弹窗左上角有启用开关，先将其打开，并在不填写任何参数的情况下点击Save changes，此时 ToolJet 会生成Redirect URL—— 请复制该地址回填到 Azure 应用注册的重定向 URI 中；
5. 从身份提供商处获取Client ID、Client Secret与Well Known URL（Azure 场景即本文第二步、第三步与上一节的取值），填入弹窗后点击底部的Save changes。

保存成功后，OIDC SSO 即告启用，你的用户即可通过 Azure AD 凭据经由 OpenID Connect 无缝登录 ToolJet。

源码层面的实现支撑

为了让读者对这套配置背后的机制有更深入的理解，下面结合 ToolJet 服务端源码补充几个关键实现事实：

配置数据模型：OIDC 配置持久化在sso_configs表中，configs为 JSON 列。针对 OpenID Connect，其结构包含clientId、clientSecret、name、customScopes、wellKnownUrl、claimName、groupMapping、enableGroupSync、enableShortSession等字段（参见 sso_config.entity.ts）。其中customScopes支持自定义 OIDC 授权范围，claimName用于指定身份断言字段，enableGroupSync与groupMapping则对应可选的组同步能力。

配置作用域：每条 SSO 配置通过configScope区分instance（实例级）与organization（组织/工作区级）两种级别（参见 sso_config.entity.ts）。在组织级别下，OIDC 配置以数组形式暴露以支持多租户场景，而实例级 OIDC 保持单对象结构（参见 util.service.ts）。

敏感信息保护：服务端在返回 SSO 配置前会过滤掉所有键名包含secret的字段（buildConfigs方法），并在存取时对密钥进行加密/解密处理（encryptSecret/decryptSecret），确保clientSecret不会以明文形式出现在前端响应中（参见 util.service.ts）。

登录调用链：前端通过signInViaOAuth将授权码提交至/oauth/sign-in/:configId或/oauth/sign-in/common/:ssoType（参见 authentication.service.js），服务端由OauthController的signIn端点接收并交由 OAuth 服务完成令牌交换与用户信息解析（参见 controller.ts），其中 OIDC 流程由OidcOAuthService承载（参见 oidc-auth.service.ts），底层依赖openid-client库（参见 main.ts、user_response.ts）。

常见问题与注意事项

• 重定向 URI 不匹配：Azure 侧注册的重定向 URI 必须与 ToolJet 生成的 Redirect URL 逐字符一致（注意协议、域名、路径与端口），否则授权码回跳会失败；
• Client Secret 过期：Azure 客户端密钥可设置有效期，过期后登录将失败，需在 ToolJet 中更新为新的密钥值；
• 账户类型选择：若选择"仅本组织"（单租户），则只有该目录内的账户能够登录；多租户场景需在 Azure 侧正确配置租户访问策略；
• Well Known URL 可用性：确保该发现端点可从 ToolJet 服务端网络访问，代理或网络隔离环境下需放行对应域名；
• 付费特性限制：OIDC 属于付费功能，实例需具备相应许可证后配置项才会生效。

按照上述流程完成配置后，即可实现用户通过 Azure AD 凭据一键登录 ToolJet，将身份认证统一收敛到企业的 Entra ID 目录中。

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