Activepieces 如何配置 Google 等身份提供商的 SSO 并强制指定邮箱域名走单点登录？-创锋一号

Activepieces 如何配置 Google 等身份提供商的 SSO 并强制指定邮箱域名走单点登录？

【免费下载链接】activepiecesAI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces

在 Activepieces 中启用 SSO（Single Sign-On）后，团队成员不再使用独立的 Activepieces 账号，而是直接通过组织已有的身份提供商（Google、Okta、Microsoft Entra ID 或 JumpCloud）登录平台。本文基于官方文档 SSO 配置指南，给出一条可执行的操作路径：先接入身份提供商，再通过SSO Domain和Allowed Domains两项配置，把指定邮箱域名的登录流量强制路由到 SSO，必要时可关闭邮箱/密码登录。

前提条件与进入配置页

SSO 是付费功能，仅 Enterprise/Cloud 版本可用（企业功能说明）。开始之前，文档要求你具备：

Activepieces 平台的Admin 权限；
身份提供商一侧（Google、GitHub、Okta 或 JumpCloud）的Admin 权限；
Activepieces SSO 配置页上显示的Redirect URL（在身份提供商侧登记用）。

进入方式：在 Activepieces 管理后台依次点击Platform Settings→SSO。页面由 SSO 设置页实现，包含四项配置：Allowed Domains（限制认证邮箱域名）、Google（开关）、SAML 2.0（配置对话框）、Allowed Email Login（邮箱/密码登录开关）。

配置 Google 作为身份提供商

官方文档给出的 Google 接入步骤：

打开 Google Cloud Console，选择（或新建）一个项目；
依次进入APIs & Services→Credentials→Create Credentials→OAuth client ID，应用类型选择Web application；
从 Activepieces SSO 配置页复制Redirect URL，添加到 Google 的Authorized redirect URIs；
把 Google 侧生成的Client ID和Client Secret粘贴到 Activepieces 对应字段；
点击Finish完成设置。

需要说明的是，当前代码中 Google 登录在 SSO 页面上是一个独立的开关（googleAuthEnabled，见 index.tsx）。如果你在实际界面上看到的是开关而非表单字段，开启后按其提示填入 Client ID / Client Secret 即可，两边字段名是一致的。

配置 SAML 2.0（Okta / Microsoft Entra ID / JumpCloud）

点击 SSO 页面上SAML 2.0一行的配置按钮，打开Configure SAML 2.0 SSO对话框（saml-dialog.tsx）。对话框第一屏是SSO Domain设置（下一节详述），第二屏显示要填到身份提供商侧的两个关键值：

Single sign-on URL（ACS URL）：由ApFlagId.SAML_AUTH_ACS_URL标志注入，直接显示在对话框中；
Audience URI (SP Entity ID)：固定为Activepieces。

保存时需要提供IDP Metadata（IdP 元数据 XML 内容或其 URL，Activepieces 会在服务端拉取该 URL）和IDP Certificate（签名证书）。

SAML with Okta

Okta Admin Portal →Applications→Create App Integration，选择SAML 2.0作为 sign-on 方法；
填写App name（如 "Activepieces"）；
SAML 设置：Single sign-on URL填 Activepieces 配置页给出的 SSO URL；Audience URI (SP Entity ID)填Activepieces；Name ID format选EmailAddress；
添加属性映射：
Name Value
firstName user.firstName
lastName user.lastName
email user.email
完成后在Sign On页签导出IdP metadataXML 和X.509 Certificate；
在 Activepieces 中把 metadata XML 粘贴到IDP Metadata字段、证书粘贴到签名密钥字段，点击Save。

Name	Value
`firstName`	`user.firstName`
`lastName`	`user.lastName`
`email`	`user.email`

SAML with Microsoft Entra ID (Azure AD)

Azure Portal →Microsoft Entra ID→Enterprise applications→New application→Create your own application（选Non-gallery）；
Single sign-on页签选择SAML；
Basic SAML Configuration：Identifier (Entity ID)填Activepieces；Reply URL (Assertion Consumer Service URL)填 Activepieces 配置页的 SSO URL；
Attributes & Claims中追加三条 claims（Namespace 留空）：
Claim name Source attribute
firstName user.givenname
lastName user.surname
email user.mail
从SAML Certificates复制App Federation Metadata Url——该 URL 可以直接粘贴进 Activepieces 的IDP Metadata字段（服务端会自动抓取），或手动打开 URL 保存 XML 后粘贴内容；
下载Certificate (Base64)，连同-----BEGIN CERTIFICATE-----/-----END CERTIFICATE-----标记一并复制，粘贴到Signing Key字段；
在Users and groups中分配允许登录的用户或组，最后在 Activepieces 中Save。

Claim name	Source attribute
`firstName`	`user.givenname`
`lastName`	`user.surname`
`email`	`user.mail`

SAML with JumpCloud

JumpCloud Admin Portal →SSO Applications→Add New Application→Custom SAML App；
ACS URLs填 Activepieces 配置页的ACS URL；SP Entity ID(Audience URI) 填Activepieces；
属性映射：
Service Provider Attribute JumpCloud Attribute
firstName firstname
lastName lastname
email email
必须启用 HTTP-Redirect binding——JumpCloud 默认不开启，文档明确警告：不开启该绑定 SSO 集成无法正常工作；
Save后刷新页面并Export Metadata，确认导出的 XML 中包含Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"；
把 metadata XML 粘贴进 Activepieces 的IdP Metadata字段；从<ds:X509Certificate>元素提取证书值，包成 PEM 格式后粘贴到Signing Key字段：
```
-----BEGIN CERTIFICATE----- [此处粘贴从 ds:X509Certificate 提取的证书值] -----END CERTIFICATE-----
```
在 JumpCloud 中把应用分配给相应用户/用户组，完成设置。

Service Provider Attribute	JumpCloud Attribute
`firstName`	`firstname`
`lastName`	`lastname`
`email`	`email`

强制指定邮箱域名走 SSO：SSO Domain 与 Allowed Domains

文档区分了两个容易混淆的“域名”概念，它们作用在不同层面。

SSO Domain：按域名发现 SAML 身份提供商

SSO Domain把一个公网域名（如acme.com）映射到你平台的 SAML 提供商。配置入口在 SAML 对话框的第一步（Platform Settings → SSO → SAML 2.0 → Enable）。

在 Cloud 版上，共享登录页点击Sign in with SAML时会要求用户输入组织域名；输入acme.com后，平台查找 SSO Domain 匹配的平台，并把用户重定向到该平台的 IdP。

约束（来自文档与前端校验）：

必须是包含点的合法公网主机名（如acme.com，不能是acme），最长 253 字符；
在 Cloud 上每个域名只能被一个平台认领。

保存域名后，对话框会展示一条TXT 记录（含 Name / Value 两列，界面自带复制输入框），把它加到你的 DNS 服务商，再点击Verify DNS。界面状态从Waiting for DNS变为DNS verified — domain is ready即验证通过；若提示TXT record not found yet，属于 DNS 生效需要几分钟，稍后重试即可。

两个需要注意的行为：

修改已保存的域名会弹出警告：在验证新域名之前，用户无法通过 SSO 登录（saml-dialog.tsx 中的 "Users won't be able to sign in via SSO until you verify the new domain"）。
自托管 Enterprise 实例上，登录页的 SAML 按钮会直接跳转到已配置的 IdP，SSO Domain 字段在登录时不生效，留空即可。

Allowed Domains：把邮箱域名限定到指定范围

SSO 页面上Allowed Domains（"Restrict authentication to specific email domains"）通过 allowed-domain.tsx 实现：

点击Enable / Update打开Configure Allowed Domains对话框，逐条输入域名（占位示例为example.com），可点击Add Domain添加多个；
保存后，已配置的域名会以徽标形式显示在Allowed Domains一行下方；
对话框明确说明：空列表表示允许所有域名。提交时前端会把enforceAllowedAuthDomains设为true（列表非空时）或false（列表为空时），即配置了域名就等于开启强制。

再配合页面上的Allowed Email Login开关（控制 "Allow logins through email and password"，对应emailAuthEnabled字段），就构成文档描述的完整强制链路：匹配 SSO 域名的用户必须走身份提供商认证，同时可以关闭邮箱/密码登录。文档建议：在组织内全面强制之前，先用一小批用户测试 SSO。

结果验证与故障排查

文档的 Troubleshooting 部分给出了三类故障与对应检查项：

1. 配置 SSO 后用户无法登录

确认 Redirect URL 在身份提供商侧配置正确；
确认用户已被分配到身份提供商中的该应用（如 Entra ID 的 Users and groups、JumpCloud 的应用分配）；
核对用户邮箱域名是否与 SSO 强制设置匹配。

2. SAML 认证失败

确认 IdP metadata 完整、格式正确；
如果填的是 metadata URL，确认它公网可达（Activepieces 在服务端拉取）；
确认签名证书带 BEGIN/END 标记、格式正确；
确认firstName、lastName、email属性映射齐全。

3. HTTP-Redirect binding 报错（JumpCloud）

在 JumpCloud 中启用 HTTP-Redirect binding；
启用后重新导出 metadata；
确认导出 XML 中出现该绑定。

验证方式即按上述清单逐项核对：SSO 页面上SAML 2.0一行显示已保存的 SSO Domain 徽标及Verified状态、Allowed Domains一行显示已配置的域名徽标，然后让测试账号从登录页走一遍 SSO 流程确认能签发登录成功。若仍无法解决，文档建议联系 enterprise support 或 sales 团队。

参考

SSO 官方配置文档（本文主要来源）
EE 认证（SSO/RBAC）知识页（SSO 配置页的文件位置与ssoEnabled门控说明）
SSO 设置页源码、Allowed Domains 对话框、SAML 配置向导

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析