Skip to content

设置 SAML#

功能可用性

  • 适用于 Business 和 Enterprise 计划。
  • 您需要是实例所有者或管理员才能启用和配置 SAML。

使用环境变量配置

你也可以通过环境变量配置 SAML，而不是只通过 UI 操作。该能力自 n8n v2.18.0 起可用。请参阅 SSO 环境变量。

启用 SAML#

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

SAML Request Type SAML 请求类型

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

Generic IdP setup 通用 IdP 设置#

配置 IdP 的步骤因你选择的 IdP 而异。以下是一些常见的设置任务：

  • 在你的 IdP 中为 n8n 创建应用程序。
  • 将 n8n 属性映射到 IdP 属性：
Value (IdP side) 值（IdP 端） Name format 名称格式 Name 名称
User email 用户电子邮件 URI Reference http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
User First Name 用户名字 URI Reference http://schemas.xmlsoap.org/ws/2005/05/identity/claims/firstname
User Last Name 用户姓氏 URI Reference http://schemas.xmlsoap.org/ws/2005/05/identity/claims/lastname
User Email 用户电子邮件 URI Reference http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn

Instance and project access provisioning 实例和项目访问配置#

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

角色配置能力自 1.122.2 版本起提供。

选择角色分配方式#

在 n8n 中，进入 Settings 设置 > SSO。使用 Role assignment 角色分配 下拉框，选择 n8n 应如何为通过 SSO 登录的用户分配角色。默认值为 Assigned manually in n8n 在 n8n 中手动分配。

可选项如下：

  • Assigned manually in n8n 在 n8n 中手动分配：管理员直接在 n8n 中为用户分配所有角色，不会从 IdP 自动映射。
  • Instance roles via SSO 通过 SSO 分配实例角色：n8n 在用户登录时从 IdP 读取其实例角色。项目访问仍由 n8n 内部手动管理。
  • Instance and project roles via SSO 通过 SSO 分配实例与项目角色：n8n 在用户登录时同时从 IdP 读取实例角色和项目访问权限。

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

现有访问权限会被覆盖

启用任一 SSO 配置模式后，用户下次登录时，凡是已在 n8n 内部分配、但未体现在 IdP 响应中的访问权限，都会被移除。

在保存此更改前，n8n 会提示你下载两个包含当前访问设置的 CSV 文件。请保留这些文件作为参考。

选择角色映射方式#

当 Role assignment 角色分配 设置为 Instance roles via SSO 通过 SSO 分配实例角色 或 Instance and project roles via SSO 通过 SSO 分配实例与项目角色 时，会出现 Role mapping method 角色映射方式 下拉框。你可以选择：

  • Map rules on your IdP 在 IdP 上映射规则：n8n 直接从 SAML 响应中读取 n8n 专用属性（n8n_instance_role 和 n8n_projects）。由你的 IdP 管理员来配置每个用户或组应获得哪个 n8n 角色或项目。
  • Map rules inside n8n 在 n8n 内部映射规则：你在 n8n 中定义表达式，用于评估用户的 SAML 属性并返回角色。当你的 IdP 无法编码 n8n 专用角色逻辑，或在 IdP 侧变更较慢时，这种方式更适合。

在你的 IdP 上映射规则#

请在 IdP 中的组或单个用户上配置以下属性：

Value (IdP side) 值（IdP 端） Data type 数据类型 Name 名称
n8n_instance_role string n8n_instance_role
n8n_projects array n8n_projects

配置 n8n_instance_role 属性

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

支持的实例角色：

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

配置 n8n_projects 属性

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

例如：

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

对于启用项目访问配置时已经存在的访问设置，你可以在下载的 CSV 文件中找到项目 ID。

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

在 n8n 内部映射规则#

Map rules inside n8n 在 n8n 内部映射规则 自 2.19.0 版本起可用。

使用此选项时，组到角色的映射逻辑定义在 n8n 内部，而不是 IdP 中。每条规则都是一个表达式，n8n 会根据 IdP 响应中的 SAML 属性对其进行求值。

表达式的工作方式

  • 表达式通过 $claims 对象访问 IdP 响应中的所有 SAML 属性。
  • 如果表达式返回 true，n8n 就会分配该规则对应的角色。
  • 规则会按照从上到下的顺序求值，第一条命中的规则即生效。
  • 规则会在每次登录时重新求值，因此角色变更会在用户下次会话中生效。
  • $claims 暴露的是原始 SAML 属性。n8n 不会对其做标准化，因此编写表达式时必须基于你的 IdP 实际发送的数据结构。SAML 组成员信息通常会以多值属性形式发送，但具体形态取决于 IdP。

检查你的 SAML 响应结构

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

实例角色规则

在 Instance role rules 实例角色规则 下，选择 Add rule 添加规则 来创建规则。输入条件表达式，并选择当该条件返回 true 时要分配的实例角色。

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

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

Default condition 默认条件 这一行定义了在没有任何规则命中时，用户应获得的角色。默认值为 Member。

项目角色规则

在 Project role rules 项目角色规则 下，选择 Add rule 添加规则 来创建规则，从而为一个或多个项目分配项目角色。

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

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

在 assign 字段中选择角色，在 in 字段中选择目标项目。未命中任何项目规则的用户将不会获得任何项目访问权限。

手动角色管理会被禁用

当 Map rules inside n8n 在 n8n 内部映射规则 处于启用状态时，手动分配用户角色的 UI 控件会被禁用。所有角色分配都将通过这些映射规则进行。

切换映射方式

如果你从 Map rules inside n8n 在 n8n 内部映射规则 切换回 Map rules on your IdP 在 IdP 上映射规则，n8n 内部的映射规则会被移除。如果 IdP 中没有配置等价映射，用户可能会在下次登录时失去当前分配的角色。应用此变更前，n8n 会要求你确认。

常见 IdP 的设置资源#

常见 IdP 的文档链接。

IdP 文档
Auth0 Configure Auth0 as SAML Identity Provider: Manually configure SSO integrations
Authentik Applications and the SAML Provider
Azure AD SAML authentication with Azure Active Directory
JumpCloud How to setup SAML (SSO) applications with JumpCloud (using Zoom as an example)
Keycloak Choose a Getting Started guide depending on your hosting.
Okta n8n provides a Workforce Identity setup guide as well as a step-by-step PDF guide
PingIdentity PingOne SSO