如何设置 SSO

配置单点登录（SSO），为你的 Activepieces 平台启用安全、集中的身份验证

此功能仅适用于付费版本。如有需要，请联系我们。

概述

单点登录（SSO）允许你的团队成员使用组织现有的身份提供商进行身份验证，无需单独的 Activepieces 凭证。这提高了安全性，简化了用户管理，并提供无缝的登录体验。

先决条件

在配置 SSO 之前，请确保你拥有：

Activepieces 平台的管理员访问权限
身份提供商（Google、GitHub、Okta 或 JumpCloud）的管理员访问权限
Activepieces SSO 配置屏幕中的重定向 URL

访问 SSO 配置

在 Activepieces 管理后台导航到 平台设置 → SSO 以访问 SSO 配置屏幕。

强制执行 SSO

你可以通过指定组织的电子邮件域名来强制执行 SSO。启用 SSO 强制执行后：

匹配的电子邮件域名的用户必须通过 SSO 提供商进行身份验证
可以禁用电子邮件/密码登录以增强安全性
所有身份验证都将通过你指定的身份提供商进行

我们建议先在少量用户中测试 SSO，然后再在整个组织中强制执行。

SSO 域名

SSO 域名允许你将公共域名（例如 acme.com）映射到平台的 SAML 提供商，以便用户从共享登录页面发现正确的 IdP。

你可以在 SAML 配置对话框（平台设置 → SSO → SAML 2.0 → 启用）的 SSO 域名 字段中设置。留空以禁用基于域名的发现。

在云版上的工作方式

在云版登录页面上，点击 使用 SAML 登录 会打开一个对话框，询问用户其组织域名。当他们输入 acme.com 时，系统会查找匹配该 SSO 域名的平台，并将用户重定向到该平台的身份提供商。

约束条件

必须是包含点的有效公共主机名（例如 acme.com，而不是 acme）
在云版上，每个域名只能被一个平台声明

在自托管的企业版实例上，登录页面上的 SAML 按钮直接重定向到已配置的身份提供商，因此 **SSO 域名** 字段在登录时实际上被忽略。你仍然可以将其留空。

支持的 SSO 提供商

Activepieces 支持多个 SSO 提供商，以便与你现有的身份管理系统集成。

Google

访问 [Google Cloud Console](https://console.cloud.google.com/) 并选择你的项目（或创建一个新项目）。导航到 **API 和服务** → **凭据** → **创建凭据** → **OAuth 客户端 ID**。

选择 **Web 应用** 作为应用类型。

从 Activepieces SSO 配置屏幕复制**重定向 URL**，并将其添加到 Google Cloud Console 中的**已授权的重定向 URI**。从 Google 复制**客户端 ID** 和**客户端密钥**，并粘贴到 Activepieces 的相应字段中。点击 **完成** 以完成设置。

GitHub

进入 [GitHub 开发者设置](https://github.com/settings/developers) → **OAuth 应用** → **新建 OAuth 应用**。填写应用详情：

* **应用名称**：选择可识别的名称（例如 "Activepieces SSO"）
* **主页 URL**：输入你的 Activepieces 实例 URL

从 Activepieces SSO 配置屏幕复制**重定向 URL**，并粘贴到**授权回调 URL** 字段。点击 **注册应用** 以创建 OAuth 应用。注册后，点击 **生成新的客户端密钥** 并立即复制（之后将不再显示）。复制**客户端 ID** 和**客户端密钥**，并粘贴到 Activepieces 的相应字段中。点击 **完成** 以完成设置。

使用 Okta 的 SAML

进入 [Okta 管理门户](https://login.okta.com/) → **应用程序** → **创建应用集成**。选择 **SAML 2.0** 作为登录方式，然后点击 **下一步**。输入**应用名称**（例如 "Activepieces"），还可以上传徽标。点击 **下一步**。 * **单点登录 URL**：从 Activepieces 配置屏幕复制 SSO URL * **受众 URI（SP 实体 ID）**：输入 `Activepieces` * **名称 ID 格式**：选择 `EmailAddress` 添加以下属性映射：

| 名称 | 值 |
| - | - |
| `firstName` | `user.firstName` |
| `lastName` | `user.lastName` |
| `email` | `user.email` |

点击 **下一步**，选择适当的反馈选项，然后点击 **完成**。进入 **登录** 标签 → **查看 SAML 设置说明** 或 **查看 IdP 元数据**。复制身份提供商元数据 XML。 * 将 **IdP 元数据** XML 粘贴到相应字段 * 从 Okta 复制 **X.509 证书**并粘贴到**签名密钥**字段 * （可选，云版）将 **SSO 域名** 设置为组织的公共域名（例如 `acme.com`），以便用户可在云版登录页面上通过输入域名登录。参见上面的 [SSO 域名](#sso-domain) 点击 **保存** 以完成设置。

使用 Microsoft Entra ID（Azure AD）的 SAML

进入 [Azure 门户](https://portal.azure.com/) → **Microsoft Entra ID** → **企业应用程序** → **新建应用程序** → **创建自己的应用程序**。

为其命名（例如 "Activepieces"），然后选择**集成你在库中未找到的任何其他应用程序（非库）**。

打开应用程序 → **单点登录** → 选择 **SAML**。编辑 **基本 SAML 配置**：

* **标识符（实体 ID）**：`Activepieces`
* **回复 URL（断言消费者服务 URL）**：粘贴 Activepieces 配置屏幕中的 SSO URL

编辑 **属性和声明** 并添加以下附加声明（将**命名空间**留空）：

| 声明名称 | 源属性 |
| - | - |
| `firstName` | `user.givenname` |
| `lastName` | `user.surname` |
| `email` | `user.mail` |

在 **SAML 证书** 部分，复制**应用联合元数据 URL**。

你可以将此 URL 直接粘贴到 Activepieces 的 **IdP 元数据** 字段——Activepieces 会自动获取元数据 XML。或者，在浏览器中打开该 URL，保存 XML 并粘贴其内容。

从 **SAML 证书** 部分下载**证书（Base64）**。打开文件，将其内容（包括 `-----BEGIN CERTIFICATE-----` / `-----END CERTIFICATE-----` 标记）复制到 Activepieces 的**签名密钥**字段。进入应用程序的**用户和组**，分配应允许登录的用户或组。在 Activepieces 中点击 **保存** 以完成设置。

使用 JumpCloud 的 SAML

进入 [JumpCloud 管理门户](https://console.jumpcloud.com/) → **SSO 应用程序** → **添加新应用程序** → **自定义 SAML 应用**。从 Activepieces 配置屏幕复制 **ACS URL**，并粘贴到 JumpCloud 的 **ACS URL** 字段。

<img src="https://mintcdn.com/activepieces/uHZ35vXyxX7goNO-/resources/screenshots/jumpcloud/acl-url.png?fit=max&auto=format&n=uHZ35vXyxX7goNO-&q=85&s=850741fb9a122b3aa3be92a9c0f16475" alt="JumpCloud ACS URL" width="608" height="263" data-path="resources/screenshots/jumpcloud/acl-url.png" />

将 **SP 实体 ID**（受众 URI）设置为 `Activepieces`。配置以下属性映射：

| 服务提供商属性 | JumpCloud 属性 |
| - | - |
| `firstName` | `firstname` |
| `lastName` | `lastname` |
| `email` | `email` |

<img src="https://mintcdn.com/activepieces/uHZ35vXyxX7goNO-/resources/screenshots/jumpcloud/user-attribute.png?fit=max&auto=format&n=uHZ35vXyxX7goNO-&q=85&s=7ca21b93a70e8b51d392ee06cc6c4d10" alt="JumpCloud User Attributes" width="599" height="368" data-path="resources/screenshots/jumpcloud/user-attribute.png" />

JumpCloud 默认不包含 `HTTP-Redirect` 绑定。你**必须**启用此选项。

<img src="https://mintcdn.com/activepieces/uHZ35vXyxX7goNO-/resources/screenshots/jumpcloud/declare-login.png?fit=max&auto=format&n=uHZ35vXyxX7goNO-&q=85&s=8f2daa949a616e4dc98840b7623f00cb" alt="JumpCloud Redirect Binding" width="597" height="243" data-path="resources/screenshots/jumpcloud/declare-login.png" />

<Warning>
  没有 HTTP-Redirect 绑定，SSO 集成将无法正常工作。
</Warning>

点击 **保存**，然后刷新页面并点击 **导出元数据**。

<img src="https://mintcdn.com/activepieces/uHZ35vXyxX7goNO-/resources/screenshots/jumpcloud/export-metadata.png?fit=max&auto=format&n=uHZ35vXyxX7goNO-&q=85&s=9945a82f3b87881deea9dce937968f01" alt="JumpCloud Export Metadata" width="618" height="250" data-path="resources/screenshots/jumpcloud/export-metadata.png" />

<Tip>
  验证导出的 XML 包含 `Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"` 以确保绑定已正确启用。
</Tip>

将导出的元数据 XML 粘贴到 Activepieces 的 **IdP 元数据** 字段。在 IdP 元数据中找到 `` 元素并提取其值。格式化为 PEM 证书：

```
-----BEGIN CERTIFICATE-----
[将证书值粘贴在此处]
-----END CERTIFICATE-----
```

将其粘贴到**签名密钥**字段。

在 JumpCloud 中，将应用程序分配给适当的用户或用户组。

<img src="https://mintcdn.com/activepieces/uHZ35vXyxX7goNO-/resources/screenshots/jumpcloud/user-groups.png?fit=max&auto=format&n=uHZ35vXyxX7goNO-&q=85&s=43f7dcb66b7aaeec59a070053fdaf8e7" alt="JumpCloud Assign App" width="939" height="526" data-path="resources/screenshots/jumpcloud/user-groups.png" />

点击 **完成** 以完成设置。

故障排查

* 验证重定向 URL 在身份提供商中配置正确 * 确保用户在身份提供商中已分配给应用 * 检查电子邮件域名是否与 SSO 强制执行设置匹配 * 确认 IdP 元数据完整且格式正确 * 如果粘贴的是元数据 URL，请确保它可以公开访问（Activepieces 在服务端获取） * 验证签名证书格式正确且包含 BEGIN/END 标记 * 确保所有必需的属性（firstName、lastName、email）均已映射 * 在 JumpCloud 中启用 HTTP-Redirect 绑定选项 * 启用绑定后重新导出元数据 * 验证绑定是否出现在导出的 XML 中

需要帮助？

如果在 SSO 设置过程中遇到问题，请联系我们的企业支持或销售团队。