Skip to content

Azure AD SAML 设置(Azure AD SAML setup)#

本文件提供了配置 Azure AD 以通过 SAML 属性向 n8n 发送角色信息的说明。这使得可以根据 Azure AD 群组成员资格自动分配角色。

🌐 This document provides instructions for configuring Azure AD to send role information to n8n via SAML attributes. This enables automatic role assignment based on Azure AD group membership.

先决条件(Prerequisites)#

你需要一个具有访问企业应用权限的 Azure AD 账户，以及来自 n8n 的 SAML 设置的重定向 URL 和实体 ID。

🌐 You need an Azure AD account with access to Enterprise Applications, and the redirect URL and entity ID from n8n's SAML settings.

请先阅读 设置 SAML 指南。

🌐 Read the Set up SAML guide first.

n8n 所需的(What n8n requires)#

n8n 期望在 SAML 声明中包含自定义 SAML 属性：

🌐 n8n expects a custom SAML attribute to be included in the SAML assertion:

属性名称 数据类型 用途
n8n_instance_role 字符串 控制用户在 n8n 中的全局角色

n8n_instance_role 的有效值：

🌐 Valid values for n8n_instance_role:

值 描述
global:owner 完整实例所有者访问权限
global:admin 管理员访问权限
global:member 普通成员访问权限（如果未指定，则默认）
global:chatUser n8n 中的受限非技术角色，设计用于通过 Chat Hub 界面安全地与 AI 代理交互

设置(Setup)#

步骤 1：配置标准 SAML 属性

  1. 在你的 Azure AD 门户中，导航到你的 n8n 企业应用。
  2. 转到 单点登录 > 属性和声明。

  3. 确保配置了这些标准属性：

    声明名称 来源属性
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress user.mail
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/firstname user.givenname
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/lastname user.surname
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn user.userprincipalname

步骤 2：添加 n8n_instance_role 权限声明

此声明使用条件逻辑根据 Azure AD 组成员身份发出不同的角色值。

🌐 This claim uses conditional logic to emit different role values based on Azure AD group membership.

  1. 在 属性和声明 中，点击 添加新的声明。
  2. 配置基本设置：
    • 名称: n8n_instance_role
    • 命名空间：留空
    • 来源: Attribute
  3. 展开 索赔条件 并点击 添加条件。

  4. 为每个 Azure AD 组添加条件（按优先顺序）：

    用户类型 范围组 来源 值
    成员 n8n-chatusers 属性 global:chatUser
    成员 n8n-users 属性 global:member
    成员 n8n-admins 属性 global:admin
    成员 n8n-owners 属性 global:owner

条件顺序

条件按顺序进行评估。把最有特权的群体（所有者）放在最后。

  1. 点击 保存。

测试配置(Testing the configuration)#

  1. 在 n8n 中，前往 设置 > 单点登录 (SSO)。
  2. 将 角色分配 设置为 通过 SSO 的实例角色。
  3. 将 角色映射方法 设置为 在你的身份提供商上映射规则。
  4. 点击 测试设置。
  5. 验证 SAML 响应显示正确的 n8n_instance_role 值。

故障排除(Troubleshooting)#

声明未出现在 SAML 响应中

  • 验证用户是否是至少一个已配置组的成员。
  • 检查这些组是否已分配到企业应用。
  • 确保条件已配置 Attribute 作为来源。
  • 使用类似 'SAML Chrome Panel' 的浏览器扩展插件来查看应用的 SAML 响应。

用户获得错误角色

  • 检查条件顺序（最优先的组应放在最后）。

使用应用角色而不是基于组的声明来分配多个项目角色(Assigning multiple project roles using app roles instead of group-based claims)#

使用基于 Azure AD 组的声明条件为用户分配多个项目角色时，通常只会在 SAML 断言中发送第一个匹配的组声明。这意味着用户可能只能看到一个项目的访问权限，尽管他们属于多个组。

🌐 Using Azure AD group-based claim conditions for assigning multiple project roles to users often results in only the first matching group claim being sent in the SAML assertion. This means users may see access to only one project despite belonging to several groups.

为了可靠地分配多个项目及其各自的角色，请使用在应用注册中定义的 应用角色，而不是基于组的声明：

🌐 To reliably assign multiple projects with their respective roles, use App Roles defined in the App Registration instead of group-based claims:

  1. 在你的 n8n SAML 应用的 应用注册 中，定义表示每个项目和权限组合的应用角色（例如，<projectId>:<role>）。
  2. 保存更新后的应用清单。
  3. 在企业应用中，在用户和组下将用户或组分配到这些应用角色。
  4. 在 单点登录 > 属性与声明 中更新 n8n_projects SAML 声明以从 user.assignedroles 获取来源。这会在 SAML 响应中以数组形式发出所有已分配的角色。

此设置确保 n8n 正确接收所有项目分配，从而在多个项目中实现适当的访问权限。虽然定义应用角色会增加初始管理负担，但它简化了持续的用户角色管理，并保证了项目角色的完整同步。

🌐 This setup ensures n8n receives all project assignments correctly, enabling appropriate access across multiple projects. While defining App Roles adds initial administrative overhead, it simplifies ongoing user-role management and guarantees complete project role sync.

在从基于组的声明迁移到应用角色时，请相应调整角色定义和声明映射，以防止项目访问不完整。

🌐 When migrating from group-based claims to App Roles, adjust your role definitions and claims mapping accordingly to prevent incomplete project access.

参考文献(References)#