设置 OIDC#

功能可用性

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

使用环境变量配置

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

设置并启用 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 配置：
- Discovery Endpoint 发现端点：输入来自你的 IdP 的发现端点 URL。
- Client ID 客户端 ID：输入你在 IdP 注册应用程序时收到的客户端 ID。
- Client Secret 客户端密钥：输入你在 IdP 注册应用程序时收到的客户端密钥。
选择 Save settings 保存设置。
将 OIDC 设置为 Activated 已激活。

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

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

角色配置能力自 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 直接从 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`	string	`n8n`	ID
`n8n_projects`	string array	`n8n`	ID

这两个 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 内部映射规则 自 2.19.0 版本起可用。

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

表达式的工作方式

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

让你的 IdP 发送 groups claim

大多数基于组的规则都需要 OIDC 响应中包含 groups claim。该 claim 默认不会返回，因此你需要在 IdP 中显式配置。例如，可在 Okta 中添加 groups scope，或在 Azure AD 的 token 配置中设置 groups claim。编写规则前，请先检查 IdP 的响应，以明确实际的 claim 名称和结构。

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 组的所有用户：

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 会要求你确认。

Provider-specific OIDC setup#

Okta#

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

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。
- 允许的 Web 来源：添加您的 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 设置为已激活。

发现端点参考#

Google 发现端点示例：

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