设置 OIDC(Set up OIDC)#

Feature availability

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

使用环境变量进行配置

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

设置并启用 OIDC(Setting up and enabling OIDC)#

在 n8n 中，前往设置 > 单点登录 (SSO)。
在 选择认证协议 下拉菜单中，选择 OIDC。
复制显示的重定向 URL（例如，https://yourworkspace.app.n8n.cloud/rest/sso/oidc/callback）。

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

如果你在负载均衡器后运行 n8n，请确保设置 N8N_EDITOR_BASE_URL 环境变量。
使用你的身份提供者（IdP）设置 OIDC。你需要：
- 在你的身份提供商 (IdP) 中创建一个新的 OIDC 客户端/应用。
- 配置上一步中的重定向 URL。
- 记下你的身份提供者(IdP)提供的客户端ID和客户端密钥。
在你的身份提供商(IdP)中，找到发现端点（也称为知名配置端点）。它通常具有以下格式：
1
https://your-idp-domain/.well-known/openid-configuration
在 n8n 中，完成 OIDC 配置：
- 发现端点：输入你身份提供者(IdP)的发现端点 URL。
- 客户端ID：输入你在向身份提供商（IdP）注册应用时收到的客户端ID。
- 客户端密钥：输入你在向身份提供商注册应用时收到的客户端密钥。
选择 保存设置。
将 OIDC 设置为 已激活。

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

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

🌐 n8n supports provisioning the instance role and project roles via SSO. When a user signs in via OIDC, n8n can assign their instance role and project access automatically based on claims in the IdP 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:

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

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

向你的 OIDC 授权服务器添加一个名为 n8n 的额外范围，并包含以下两个声明：

🌐 Add an additional scope called n8n to your OIDC authorization server with these two claims:

名称	数据类型	范围	令牌类型
`n8n_instance_role`	字符串	`n8n`	ID
`n8n_projects`	字符串数组	`n8n`	ID

这两个声明必须始终包含在来自你的授权服务器的 ID 令牌中。在你的 IdP 中配置拥有 n8n 访问权限的用户组的这些声明。

🌐 Both claims must always be included in the ID Token from your authorization server. Configure them on the user groups in your IdP that have access to n8n.

配置 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 响应中的 OIDC 声明进行评估。

🌐 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 OIDC claims in the IdP response.

表达式的工作原理

表达式通过 $claims 对象访问来自 IdP 响应的所有 OIDC 声明。
如果表达式返回 true，n8n 会在该规则上分配你所选择的角色。
规则按从上到下的顺序进行评估。第一个匹配的规则获胜。
规则在每次登录时重新评估，因此角色更改将在用户的下一次会话中生效。
$claims 会暴露原始的 IdP 响应。n8n 不会对其进行规范化，因此请根据你的 IdP 实际发送的结构来编写表达式。

从你的身份提供者发送群组声明

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

示例用户信息响应

认证后，n8n 会调用 IdP 的 userinfo 端点来获取用户的声明。一个典型的响应如下所示：

🌐 After authenticating, n8n calls the IdP's userinfo endpoint to fetch the user's claims. A typical response looks like this:

{
  "sub": "00uwyqw9raWrKRJ0Q697",
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "email_verified": true,
  "given_name": "Jane",
  "family_name": "Doe",
  "groups": [
    "Everyone",
    "n8n admins",
    "n8n members",
    "Operations"
  ]
}

$claims 反映了这个负载。因此 $claims.email 是一个字符串，$claims.groups 是一个字符串数组，你可以对它们使用标准的 JavaScript 方法。具体的组名取决于你的身份提供者（IdP）。一些提供者（例如 Azure AD）发送的是组的 UUID 而不是显示名称，在这种情况下你的表达式需要引用 UUID。

要在 Okta 中检查你自己的 userinfo 响应，请使用有效的访问令牌直接调用 userinfo 端点。你可以从 Security > API > Authorization Servers > 你的服务器 > Token Preview 选项卡获取测试访问令牌，然后运行：

🌐 To inspect your own userinfo response in Okta, call the userinfo endpoint directly with a valid access token. You can get a test access token from Security > API > Authorization Servers > your server > Token Preview tab, then run:

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

实例角色规则

在实例角色规则下，选择添加规则以创建规则。输入条件表达式，并在条件返回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:

1	`{{ $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:

1	`{{ $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 会在应用此更改前要求你确认。

特定提供商的 OIDC 设置(Provider-specific OIDC setup)#

Okta#

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

🌐 The steps to setup OIDC in Okta are similar as with Auth0 described below.

对于 Okta，你可以下载 PDF 格式的图文分步指南：

🌐 For Okta, you can download a visual step-by-step guide as PDF:

n8n-oidc-with-okta.pdf

Auth0#

在 Auth0 中创建一个应用：
- 登录你的 Auth0 控制面板。
- 进入应用 > 应用。
- 点击 创建应用。
- 输入一个名称（例如，“n8n SSO”），并选择 常规 Web 应用。
- 点击创建。
配置应用：
- 转到新应用的设置选项卡。
- 允许的回调 URL：从设置 > SSO > OIDC 添加你的 n8n 重定向 URL。
- 允许的网页来源：添加你的 n8n 基础 URL（例如，https://yourworkspace.app.n8n.cloud）。
- 点击 保存更改。
获取你的凭证：
- 客户端 ID：在设置标签中找到。
- 客户端密钥：位于设置选项卡中。
- 发现端点: https://{your-auth0-domain}.auth0.com/.well-known/openid-configuration。
在 n8n 中，完成 OIDC 配置：
- 发现端点：输入来自 Auth0 的发现端点 URL。
- 客户端 ID：输入你在 Auth0 设置中找到的客户端 ID。
- 客户端密钥：输入你在 Auth0 设置中找到的客户端密钥。
选择 保存设置。
将 OIDC 设置为 已激活。

Discovery 端点参考(Discovery endpoints reference)#

谷歌发现端点示例：

1	`https://accounts.google.com/.well-known/openid-configuration`

Microsoft Azure AD 发现端点示例：

https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration

Auth0 发现端点示例：

1	`https://{your-domain}.auth0.com/.well-known/openid-configuration`

Okta 发现端点示例：

1	`https://{your-domain}.okta.com/.well-known/openid-configuration`

Amazon Cognito 发现端点示例：

https://cognito-idp.{region}.amazonaws.com/{user-pool-id}/.well-known/openid-configuration