ToolJet 集成 Azure ADEntra IDOpenID Connect 单点登录配置指南【免费下载链接】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-2.50.0-LTS/user-authentication/sso/openid/azuread.md讲解如何在 ToolJet 工作区中接入微软 Azure Active Directory现 Microsoft Entra ID作为 OpenID ConnectOIDC身份提供方实现企业员工一次登录、免密进入内部工具平台的 SSO 体验。读完本文你将掌握从 Azure 门户注册应用、生成客户端凭据到在 ToolJet 侧填写 OpenId 配置并完成登录闭环的完整操作同时了解 ToolJet 服务端对 OpenID 配置的底层存储结构与ssoUserInfo二次消费能力。一、前置准备与方案概述在开始配置之前你需要具备以下条件一个拥有Azure 门户portal.azure.com管理权限的账号且所在租户Tenant启用了 Active Directory 服务一个可访问ToolJet 实例本文以v2.50.0-LTS版本为例并拥有Workspace Admin / Super Admin权限以修改 SSO 设置明确 OpenID Connect 的核心参数来源Azure AD 应用注册后产生的Application (Client) ID与Client Secret以及由 Azure 元数据端点自动推导的Well Known URL。整个方案的链路如下用户浏览器 ──(1)访问 ToolJet── ToolJet 前端 │ ▼ ToolJet 的 OpenId 配置页Workspace Settings → SSO → OpenId Connect │ 填入 client id / client secret / well-known url ▼ Azure AD 登录门户 ──(2)用户输入企业账号── 签发 ID Token / Access Token │ ▼ ToolJet 服务端 /oauth|/sso 端点server/src/modules/auth/oauth/controller.ts完成回调校验并建立会话从源码结构看ToolJet 将openid与google、saml、ldap并列作为一类 SSO 类型见 sso_config.entity.ts 中的SSOType.OPENID openid所有 OpenId 提供方Azure AD、Okta、Google OpenID 等复用同一套配置入口与回调机制。二、在 Azure 门户中注册应用程序2.1 创建新应用注册打开你的Azure 门户进入Azure Active DirectoryEntra ID在左侧菜单中选择App registration应用注册然后点击New registration新建注册。官方文档给出的操作界面如下图所示截图来源于仓库docs/static/img/sso/azuread/azure-app-reg-v2.gif说明如果 Azure 门户提示需要进入Microsoft Entra ID新界面操作路径一致Identity → Applications → App registrations → New registration。2.2 填写注册信息并配置重定向 URI在新建注册表单中依次填写字段说明Name名称应用显示名例如ToolJet SSO最终会展示在用户登录页上Supported account types支持的账户类型按企业实际选型常见为Accounts in this organizational directory only仅本租户Redirect URI重定向 URI必须选择Web平台类型并填入从 ToolJet 侧复制的重定向地址重定向地址的获取方式登录 ToolJet 工作区进入Workspace Settings⚙️→ SSO → OpenId Connect页面上会展示Redirect URL字段直接复制即可。请务必先打开 ToolJet 的 OpenId 配置页再回 Azure 填写否则重定向地址会填错。2.3 完成注册并记录 Application (Client) ID点击Register注册后应用即创建成功。进入应用详情页Overview你会看到Application (Client) ID与Directory (Tenant) ID。字段用途Application (Client) ID在 ToolJet 的 OpenId 配置页中填写为client idDirectory (Tenant) ID通常用于拼接 Well Known URL见下文 2.5 节Azure 也会将其包含在 OIDC 发现文档中注意不要直接复制Directory (Tenant) ID当作client id两者含义不同。ToolJet 服务端在sso_configs表sso_config.entity.ts中以 JSON 形式保存clientId其取值正是 Azure 的 Application (Client) ID。2.4 创建客户端密钥Client Secret在应用详情页左侧选择Certificates secrets证书和机密点击 New client secret新建客户端机密填写Description描述如tooljet-sso设置Expires过期时间点击Add添加机密创建成功后Value值仅显示一次请立即复制并妥善保存。随后将其粘贴到 ToolJet OpenId 配置页的client secret字段。⚠️ 安全提示Client Secret 属于高敏凭据泄露后任何持有者都能以该应用身份向 Azure 换取令牌。建议设置合理的过期时间如 12 个月以内并纳入企业的密钥轮换计划。Azure 也支持使用证书Certificate作为更强凭据但 ToolJet 的 OpenId 配置页按 Client Secret 方式接入。2.5 构造 Well Known URLToolJet 的 OpenId 配置需要Well Known URLOIDC 发现端点。对于 Azure AD官方构造方式遵循 OIDC 协议规范Azure 文档v2-protocols-oidchttps://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration其中{tenant}可以是租户 IDDirectory (Tenant) ID的 GUID例如https://login.microsoftonline.com/11111111-2222-3333-4444-555555555555/v2.0/.well-known/openid-configuration组织域名如https://login.microsoftonline.com/contoso.com/v2.0/.well-known/openid-configuration通用值common、organizations或consumers分别对应多租户/组织账户/个人账户场景。浏览器访问该 URL会返回包含authorization_endpoint、token_endpoint、jwks_uri等标准字段的 JSON 文档。ToolJet 服务端会通过该发现端点自动解析出授权、令牌与公钥信息用于发起授权码流程并校验 ID Token 签名。三、在 ToolJet 中完成 OpenId 配置3.1 进入 OpenId 配置页登录 ToolJet 工作区点击左侧边栏底部的Workspace Settings⚙️选择SSO选择OpenId Connect。3.2 填写配置项配置项填写内容Name自定义名称例如Azure AD用于在登录页区分不同 SSO 提供方Client Id第 2.3 步获取的 AzureApplication (Client) IDClient Secret第 2.4 步保存的Client Secret ValueWell Known URL第 2.5 步构造的 Azure OIDC 发现端点保存后可在登录页面选择Azure AD进行单点登录验证。3.3 登录闭环验证配置完成后建议使用无痕窗口完成一次完整验证打开 ToolJet 登录页点击 Azure AD 登录入口浏览器跳转到login.microsoftonline.com用户输入企业账号密码或经条件访问/MFA 后登录Azure 将授权码回调到 ToolJet 的重定向地址ToolJet 服务端在/oauth|sso路由下完成令牌换取与用户信息解析对应 oauth/controller.ts 的sign-in/:configId与sign-in/common/:ssoType端点随后创建/匹配 ToolJet 用户并建立会话。3.4 登录页品牌定制可选Azure 门户允许通过Branding properties品牌和属性选项定制登录页 Logo、背景色、说明文本等使企业员工在登录跳转时看到的是公司统一品牌界面而非 Azure 默认样式。四、配置背后的源码实现进阶4.1 OpenId 配置的数据模型ToolJet 服务端在实体 sso_config.entity.ts 中定义了OpenId类型除了文档中提到的三个核心字段还包括以下扩展字段type OpenId { clientId: string; // Azure Application (Client) ID clientSecret: string; // Azure Client Secret name: string; // 显示名称 customScopes: string; // 自定义 OAuth 作用域 wellKnownUrl: string; // OIDC 发现端点 claimName: string; // 用户标识声明 groupMapping: { [key: string]: string }; // 组映射 enableGroupSync: boolean; // 是否启用组同步 enableShortSession: boolean; // 是否启用短会话 };这些配置以 JSON 形式存储在数据库sso_configs表的configs列中Column({ type: json }) configs并受enabled字段控制开关。同表还支持google、git、saml、ldap等类型SSOType枚举因此 Azure AD 只是 ToolJet 多提供方 SSO 能力中的一个实例。4.2 OIDC 服务抽象与回调端点从源码结构看ToolJet 通过 IOidcService 接口 抽象了 OIDC 的核心能力signIn用授权码换取用户信息、getConfigs生成授权 URL 与 code_verifier、handleOIDCConfigs处理配置并返回授权 URL。与之对应的统一入口是 oauth/controller.ts它同时暴露了POST sign-in/:configId、POST sign-in/common/:ssoType等端点其中ssoType路由使得 Azure AD、Okta 等 OIDC 提供方可以共享同一套登录流程。说明v2.50.0-LTS仓库中OidcOAuthService为接口桩实现实际生产逻辑由 ToolJet EE/Cloud 版本提供OpenId SSO 属于付费特性详见 setup.md 顶部的 Paid feature 标注。以上结论均来自对仓库源码结构的观察。五、登录后如何使用 OpenId 用户信息ssoUserInfo完成 OpenID 配置后ToolJet 版本v2.6.2-ee2.1.0及以上提供方返回的用户信息会被暴露在currentUser变量的ssoUserInfo属性中你可以在应用编辑器Inspector中查看并在任何支持 JS 表达式的属性里通过{{globals.currentUser.ssoUserInfo.key}}动态访问。对于 Azure AD / Microsoft 身份平台ID Token 中常见的声明Claims包括Key说明访问语法sub终端用户在签发方Issuer处的唯一标识符{{globals.currentUser.ssoUserInfo.sub}}name用户的完整显示名称{{globals.currentUser.ssoUserInfo.name}}given_name用户名字{{globals.currentUser.ssoUserInfo.given_name}}family_name用户姓氏{{globals.currentUser.ssoUserInfo.family_name}}email用户首选邮箱符合 RFC 5322 addr-spec 规范{{globals.currentUser.ssoUserInfo.email}}email_verified邮箱是否已验证布尔值{{globals.currentUser.ssoUserInfo.email_verified}}preferred_username首选用户名Azure AD 常见声明{{globals.currentUser.ssoUserInfo.preferred_username}}oidAzure AD 中用户对象的稳定标识{{globals.currentUser.ssoUserInfo.oid}}tid用户所属租户 ID{{globals.currentUser.ssoUserInfo.tid}}picture用户头像 URLPNG/JPEG/GIF 图片文件地址{{globals.currentUser.ssoUserInfo.picture}}locale用户区域BCP47 语言标签如en-US、fr-CA{{globals.currentUser.ssoUserInfo.locale}}access_token提供方返回的访问令牌{{globals.currentUser.ssoUserInfo.access_token}}id_token提供方返回的 ID 令牌{{globals.currentUser.ssoUserInfo.id_token}}id_token_encrpted加密id_token的 JSON 值{{globals.currentUser.ssoUserInfo.id_token_encrpted}}提示实际可用声明取决于 Azure 应用注册时配置的 API 权限与customScopes字段。若需更多声明如groups、roles可在 Azure 应用清单中启用相应可选声明Optional claims或在 ToolJet 的 OpenId 配置中通过customScopes申请profile、email、openid之外的作用域。典型用法示例——在文本组件中展示当前登录用户邮箱当前登录账号{{globals.currentUser.ssoUserInfo.email}}六、常见问题排查现象可能原因排查建议登录跳转后提示回调地址不匹配Azure 中 Redirect URI 与 ToolJet 配置页显示的 Redirect URL 不一致重新从 ToolJet OpenId 配置页复制 Redirect URL 并回 Azure 更新提示client id无效填入了 Tenant ID 而非 Application (Client) ID回到应用 Overview 核对 Application (Client) IDWell Known URL 解析失败租户占位符错误或网络无法访问login.microsoftonline.com浏览器直接访问构造的 URL 验证返回 JSON确认 ToolJet 服务端可出网用户登录后无法匹配到 ToolJet 用户ssoUserInfo.email与现有用户邮箱不一致确认企业邮箱域与 ToolJet 用户邮箱一致检查是否启用了自动创建用户/自动 SSO 登录见 auto-sso-login.mdClient Secret 过期密钥超过设置的有效期在 Azure 重新生成 Secret 并同步更新到 ToolJet 配置页七、延伸阅读OpenId Connect 配置通用说明含 ssoUserInfo 完整字段表Okta 作为 OpenID 提供方的配置Google OpenID 配置自动 SSO 登录配置SSO 配置的数据模型源码OAuth/SSO 统一入口控制器源码OIDC 服务抽象接口源码【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考