n8n 中文文档

设置 OIDC

提示

Feature availability 功能可用性

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

提示

Feature availability 功能可用性

使用环境变量而不是 UI 配置 OIDC 的功能从 n8n 2.18.0 起可用。请参阅SSO 环境变量。

设置并启用 OIDC

  1. 在 n8n 中,转到 Settings 设置 > Authentication 身份验证 > Single sign-on (SSO) 单点登录。
  2. 在 Select Authentication Protocol 选择身份验证协议 下,从下拉列表中选择 OIDC。
  3. 复制显示的 redirect URL 重定向网址(例如,https://yourworkspace.app.n8n.cloud/rest/sso/oidc/callback).

    负载均衡器或代理的额外配置

    如果您在负载均衡器后面运行 n8n,请确保设置N8N_EDITOR_BASE_URL 环境变量.

  4. 使用您的身份提供商 (IdP) 设置 OIDC。您需要:

    • 在您的 IdP 中创建新的 OIDC 客户端/应用程序。
    • 配置上一步的重定向 URL。
    • 记下您的 IdP 提供的客户端 ID 和客户端密钥。
  5. 在您的 IdP 中,找到发现端点(也称为已知配置端点)。它通常具有以下格式: https://your-idp-domain/.well-known/openid-configuration
  6. 在 n8n 中,完成 OIDC 配置:
    • Discovery Endpoint 发现端点:输入来自你的 IdP 的发现端点 URL。
    • Client ID 客户端 ID:输入你在 IdP 注册应用程序时收到的客户端 ID。
    • Client Secret 客户端密钥:输入你在 IdP 注册应用程序时收到的客户端密钥。
  7. 选择 Save settings 保存设置。
  8. 将 OIDC 设置为 Activated 已激活。

实例和项目访问配置

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

角色配置功能从 n8n 1.122.2 起可用。

选择如何分配角色

在 n8n 中,进入 Settings 设置 > Authentication 身份验证 > Single sign-on (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 中的更改会在用户下次登录时生效。

警告

Existing access will be overwritten 现有访问权限将被覆盖

当您启用其中一种 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 直接从 IdP 响应中读取 n8n 专用 claims(n8n_instance_role 和 n8n_projects)。由你的 IdP 管理员来配置每个用户或组应获得哪个 n8n 角色或项目。
  • Map rules inside n8n 在 n8n 内部映射规则:你在 n8n 中定义表达式,用于评估用户的 OIDC claims 并返回角色。当你的 IdP 无法编码 n8n 专用角色逻辑,或在 IdP 侧变更较慢时,这种方式更适合。

IdP 上的映射规则

在你的 OIDC 授权服务器中新增一个名为 n8n 的 scope,并在其中包含以下两个 claim:

Name 名称 Data type 数据类型 Scope 作用域 Token type 令牌类型
n8n_instance_role 字符串 n8n 身份证
n8n_projects 字符串数组 n8n 身份证

这两个 claim 必须始终包含在授权服务器签发的 ID Token 中。请在有权访问 n8n 的 IdP 用户组上配置它们。

配置 n8n_instance_role claim

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

支持的实例角色:

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

配置 n8n_projects claim

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 内部映射规则 从 n8n 2.19.0 起可用。

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

表达式的工作方式

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

提示

Send a groups claim from your IdP 从您的 IdP 发送组声明

大多数基于组的规则需要在 OIDC 响应中使用 groups 声明。默认情况下不包含此声明,您需要配置 IdP 才能发送它。例如,在 Okta 中添加 groups 范围,或在 Azure AD 令牌配置中配置 groups 声明。在编写规则之前检查 IdP 的响应,以便了解确切的声明名称和结构。

userinfo 响应示例

认证完成后,n8n 会调用 IdP 的 userinfo 端点以获取用户 claims。典型响应如下:

{
  "sub": "00uwyqw9raWrKRJ0Q697",
  "name": "Jane Doe",
  "email": "[email protected]",
  "email_verified": true,
  "given_name": "Jane",
  "family_name": "Doe",
  "groups": [
    "Everyone",
    "n8n admins",
    "n8n members",
    "Operations"
  ]
}

$claims 会反映该 payload。因此,$claims.email 是字符串,$claims.groups 是字符串数组,你可以对它们使用标准 JavaScript 方法。具体的组名取决于你的 IdP。有些提供商(例如 Azure AD)发送的是组 UUID,而不是显示名称,这种情况下表达式中就需要引用 UUID。

若要在 Okta 中查看你自己的 userinfo 响应,请使用有效 access token 直接调用 userinfo 端点。你可以在 Security > API > Authorization Servers > 你的 server > Token Preview 选项卡中获取测试 access token,然后运行:

curl -H "Authorization: Bearer <access-token>" https://<your-okta-domain>/oauth2/<auth-server-id>/v1/userinfo

实例角色规则

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

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

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

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

项目角色规则

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

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

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

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

警告

Manual role management is disabled 手动角色管理已禁用

当 Map rules inside n8n n8n 内的映射规则 处于活动状态时,用于手动分配用户角色的 UI 控件将被禁用。所有角色分配都遵循映射规则。

警告

Switching mapping methods 切换映射方法

从 Map rules inside n8n n8n 内的映射规则 切换回 Map rules on your IdP 在您的 IdP 上映射规则 将删除所有 in-n8n 映射。如果您的 IdP 中未设置等效映射,用户可能会在下次登录时丢失当前分配的角色。 n8n 要求您在应用此更改之前进行确认。

提供商特定的 OIDC 设置

奥克塔

在 Okta 中设置 OIDC 的步骤与下面描述的 Auth0 类似。

对于 Okta,您可以下载 PDF 格式的可视分步指南:

n8n-oidc-with-okta.pdf

授权0

  1. 在 Auth0 中创建应用程序:
    • 登录到您的 Auth0 仪表板。
    • 转到应用程序 > 应用程序。
    • 点击创建应用程序。
    • 输入名称(例如,"n8n SSO")并选择常规 Web 应用程序。
    • 点击创建。
  2. 配置应用程序:
    • 转到新应用程序的设置选项卡。
    • 允许的回调 URL:从 Settings 设置 > Authentication 身份验证 > Single sign-on (SSO) 单点登录 > OIDC 添加您的 n8n 重定向 URL。
    • 允许的 Web 来源:添加您的 n8n 基础 URL(例如,https://yourworkspace.app.n8n.cloud)。
    • 点击保存更改。
  3. 获取您的凭据:
    • 客户端 ID:在设置选项卡中找到。
    • 客户端密钥:在设置选项卡中找到。
    • 发现端点:https://{your-auth0-domain}.auth0.com/.well-known/openid-configuration。
  4. 在 n8n 中,完成 OIDC 配置:
    • 发现端点:输入来自 Auth0 的发现端点 URL。
    • 客户端 ID:输入您在 Auth0 设置中找到的客户端 ID。
    • 客户端密钥:输入您在 Auth0 设置中找到的客户端密钥。
  5. 选择保存设置。
  6. 将 OIDC 设置为已激活。

发现端点引用

  • Google 发现端点示例:
https://accounts.google.com/.well-known/openid-configuration
  • Microsoft Azure AD 发现端点示例:
https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration
  • Auth0 发现端点示例:
https://{your-domain}.auth0.com/.well-known/openid-configuration
  • Okta 发现端点示例:
https://{your-domain}.okta.com/.well-known/openid-configuration
  • Amazon Cognito 发现端点示例:
https://cognito-idp.{region}.amazonaws.com/{user-pool-id}/.well-known/openid-configuration

相关资源

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。