设置 SAML(Set up SAML)

Feature availability

• Available on Business and Enterprise plans.
• You need to be an instance owner or admin to enable and configure SAML.

使用环境变量进行配置

你也可以通过环境变量而不是 UI 配置 SAML。从 n8n v2.18.0 开始可用。请参阅 SSO 环境变量。

启用 SAML(Enable SAML)

1. 在 n8n 中，前往 设置 > 单点登录 (SSO)。
2. 记下 n8n 的 重定向 URL 和 实体 ID。
   • 可选：如果你的身份提供商允许你通过导入的元数据设置 SAML，请导航到 实体 ID URL 并保存 XML。
   • 可选：如果你在负载均衡器后运行 n8n，请确保已配置 N8N_EDITOR_BASE_URL。
3. 使用你的身份提供商（IdP）设置 SAML。你需要 重定向 URL 和 实体 ID。你可能还需要 IdP 用户的电子邮件地址和名称。
4. 在你的身份提供商(IdP)完成设置后，将元数据 XML 加载到 n8n 中。你可以使用元数据 URL 或原始 XML：
   • 元数据 URL：将你的 IdP 的元数据 URL 复制到 n8n 中的 身份提供商设置 字段。
   • 原始 XML：从你的身份提供商 (IdP) 下载元数据 XML，将 身份提供商设置 切换为 XML，然后将原始 XML 复制到 身份提供商设置 中。
5. 选择 保存设置。
6. 选择 测试设置 来检查你的 SAML 设置是否正常工作。
7. 将 SAML 2.0 设置为 已激活。

SAML 请求类型

n8n 不支持 POST 绑定。请将你的 IdP 配置为使用 HTTP 请求绑定。

通用身份提供商 (IdP) 设置(Generic IdP setup)

配置身份提供者（IdP）的步骤取决于你选择的身份提供者。以下是一些常见的设置任务：

🌐 The steps to configure the IdP vary depending on your chosen IdP. These are some common setup tasks:

• 在你的身份提供商 (IdP) 中为 n8n 创建应用。
• 将 n8n 属性映射到 IdP 属性：

值（IdP 端）	名称格式	名称
用户邮箱	URI 引用	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
用户名字	URI 引用	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/firstname
用户姓氏	URI 引用	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/lastname
用户电子邮件	URI 引用	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn

实例和项目访问权限配置(Instance and project access provisioning)

n8n 支持通过 SSO 配置实例角色和项目角色。当用户通过 SAML 登录时，n8n 可以根据 SAML 响应中的属性自动分配他们的实例角色和项目访问权限。

🌐 n8n supports provisioning the instance role and project roles via SSO. When a user signs in via SAML, n8n can assign their instance role and project access automatically based on attributes in the SAML response.

角色配置在版本 1.122.2 中引入。

🌐 Role provisioning was introduced in version 1.122.2.

选择角色分配方式(Choose how roles are assigned)

在 n8n 中，前往 设置 > SSO。使用 角色分配 下拉菜单选择 n8n 如何为通过 SSO 登录的用户分配角色。默认设置为 在 n8n 中手动分配。

🌐 In n8n, go to Settings > SSO. Use the Role assignment dropdown to choose how n8n assigns roles to users who sign in via SSO. The default is Assigned manually in n8n.

选项有：

🌐 The options are:

• 在 n8n 中手动分配：管理员在 n8n 中直接分配每个角色。没有来自你的 IdP 的自动映射。
• 通过 SSO 的实例角色：n8n 在登录时从 IdP 读取用户的实例角色。项目访问仍然在 n8n 中手动管理。
• 通过 SSO 的实例和项目角色：n8n 在登录时从 IdP 读取实例角色和项目访问权限。

每次登录时都会重新评估角色，因此 IdP 的更改将在用户下次登录时生效。

🌐 Roles are re-evaluated on every login, so changes in the IdP take effect at the user's next sign-in.

现有访问权限将被覆盖

当你启用其中一种 SSO 配置模式时，n8n 内授予的、但未在 IdP 响应中反映的任何访问权限将在用户下次登录时被移除。

在保存此更改之前，n8n 会要求你下载两个包含当前访问设置的 CSV 文件。请保留这些文件以供参考。

选择角色映射方法(Choose a role mapping method)

当 角色分配 设置为 通过 SSO 的实例角色 或 通过 SSO 的实例和项目角色 时，会出现一个 角色映射方法 下拉菜单。你可以选择：

🌐 When Role assignment is set to Instance roles via SSO or Instance and project roles via SSO, a Role mapping method dropdown appears. You can choose:

• 在你的身份提供者(IdP)上映射规则：n8n直接从SAML响应中读取n8n特定属性（n8n_instance_role 和 n8n_projects）。你的IdP管理员配置每个用户或组应接收的n8n角色或项目。
• n8n 内的映射规则：你可以在 n8n 中定义表达式，这些表达式会评估用户的 SAML 属性并返回一个角色。当你的 IdP 无法编码 n8n 特定的角色逻辑，或者 IT 管理导致 IdP 端的更改很慢时，请使用此方法。

在你的身份提供者上映射规则(Map rules on your IdP)

在你的身份提供者(IdP)中为组或单个用户配置这些属性：

🌐 Configure these attributes on the groups or individual users in your IdP:

值（IdP端）	数据类型	名称
n8n_instance_role	字符串	n8n_instance_role
n8n_projects	数组	n8n_projects

配置 n8n_instance_role 属性

n8n_instance_role 是为你的 IdP 上的某个组或用户配置的字符串。如果未设置值，n8n 将回退到 global:member。

支持的实例角色：

🌐 Supported instance roles:

• global:member
• global:admin
• global:chatUser

配置 n8n_projects 属性

n8n_projects 是在你的 IdP 上为某个组或用户配置的字符串数组。每个元素必须遵循 <project-id>:<role> 格式。

例如：

🌐 For example:

• bHsykgeFirmIhezz:viewer
• 4K3zrg3DvlMFFTB7:editor
• dCjnYuEpYOUBVaNe:admin

在启用项目配置时，对于已有的访问权限，请在下载的 CSV 文件中查找项目 ID。

🌐 For existing access at the time of enabling project provisioning, find the project IDs in the downloaded CSV file.

对于新项目，在浏览器中查看项目时从 URL 获取项目 ID。在 URL <your-domain>/projects/VVRWZaq5DRxaf9O1/workflows 中，项目 ID 是 VVRWZaq5DRxaf9O1。

🌐 For new projects, get the project ID from the URL when viewing the project in your browser. In the URL <your-domain>/projects/VVRWZaq5DRxaf9O1/workflows, the project ID is VVRWZaq5DRxaf9O1.

在 n8n 中映射规则(Map rules inside n8n)

n8n 内的映射规则 从版本 2.19.0 开始可用。

使用此选项在 n8n 内定义组到角色的映射，而不是在你的身份提供者 (IdP) 中定义。每条规则都是一个表达式，n8n 会将其针对 IdP 响应中的 SAML 属性进行评估。

🌐 Use this option to define group-to-role mappings inside n8n rather than in your IdP. Each rule is an expression that n8n evaluates against the SAML attributes in the IdP response.

表达式的工作原理

• 表达式通过 $claims 对象访问来自 IdP 响应的所有 SAML 属性。
• 如果表达式返回 true，n8n 会在该规则上分配你所选择的角色。
• 规则按从上到下的顺序进行评估。第一个匹配的规则获胜。
• 规则在每次登录时重新评估，因此角色更改将在用户的下一次会话中生效。
• $claims 会暴露原始的 SAML 属性。n8n 不会对它们进行规范化，因此需要根据你的 IdP 实际发送的结构编写表达式。SAML 组成员通常作为多值属性传递，但具体形式取决于你的 IdP。

检查你的 SAML 响应结构

不同的身份提供者（IdP）对组和其他属性的序列化方式不同。在编写规则之前，使用浏览器工具，如 SAML Chrome Panel（或你的 IdP 测试工具），检查 SAML 响应，并确认属性名称和结构。

实例角色规则

在实例角色规则下，选择添加规则以创建规则。输入条件表达式，并在条件返回true时选择要分配的实例角色。

🌐 Under Instance role rules, select Add rule to create a rule. Enter a condition expression and choose the instance role to assign when the condition returns true.

例如，要将 Admin 角色分配给 IdP admin 组中的任何用户：

🌐 For example, to assign the Admin role to any user in the IdP admin group:

{{ $claims.groups.includes('admin') }}

默认条件 行设置了当没有规则匹配时用户所获得的角色。默认情况下这是 成员。

🌐 The Default condition row sets the role that users receive when no rule matches. By default this is Member.

项目角色规则

在项目角色规则下，选择添加规则以创建在一个或多个项目中分配项目角色的规则。

🌐 Under Project role rules, select Add rule to create a rule that assigns a project role in one or more projects.

例如，要将 operations 组的用户在 Operations 项目中设置为 Project Editor 角色，请将表达式设置为：

🌐 For example, to give users in the operations group the Project Editor role in the Operations project, set the expression to:

{{ $claims.groups.includes('operations') }}

在 assign 字段中选择角色，在 in 字段中选择目标项目。不符合任何项目规则的用户将无法访问任何项目。

🌐 Choose the role in the assign field and the target projects in the in field. Users who don't match any project rule get no project access.

手动角色管理已禁用

当 n8n 内的映射规则 激活时，用于手动分配用户角色的 UI 控件将被禁用。所有角色分配都通过映射规则进行。

切换映射方法

将 n8n 内的映射规则 切换回 在你的 IdP 上的映射规则 会删除任何 n8n 内的映射。如果在你的 IdP 中未设置等效映射，用户在下次登录时可能会失去当前分配的角色。n8n 会在应用此更改前要求你确认。

常用身份提供商 (IdP) 的设置资源(Setup resources for common IdPs)

常用身份提供商 (IdP) 的文档链接。

🌐 Documentation links for common IdPs.

| 身份提供者 | 文档 |

| --- | --- |

| Auth0 | 将 Auth0 配置为 SAML 身份提供者：手动配置 SSO 集成 |

| Authentik | 应用 和 SAML 提供者 |

| Azure AD | 使用 Azure Active Directory 的 SAML 身份验证 |

| JumpCloud | 如何使用 JumpCloud 设置 SAML（SSO）应用（以 Zoom 为例） |

| Keycloak | 根据你的托管情况选择一个 入门 指南。 |

| Okta | n8n 提供了一个 员工身份设置指南 以及一个 逐步 PDF 指南 |

| PingIdentity | PingOne 单点登录 |