Skip to content

Azure AD SAML 设置#

本文档提供了配置 Azure AD 以通过 SAML 属性向 n8n 发送角色信息的说明。这使得可以基于 Azure AD 组成员身份自动分配角色。

前提条件#

您需要一个具有企业应用程序访问权限的 Azure AD 帐户，以及 n8n SAML 设置中的重定向 URL 和实体 ID。

请先阅读设置 SAML 指南。

n8n 的要求#

n8n 要求在 SAML 断言中包含一个自定义 SAML 属性：

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

n8n_instance_role 的有效值：

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

设置#

步骤 1：配置标准 SAML 属性

  1. 在 Azure AD 门户中，导航到您的 n8n 企业应用程序。
  2. 转到 Single sign-on 单点登录 > Attributes & Claims 属性和声明。

  3. 确保配置了以下标准属性：

    Claim Name 声明名称 Source Attribute 源属性
    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 组成员身份发出不同的角色值。

  1. 在 Attributes & Claims 属性和声明中，点击 Add new claim 添加新声明。
  2. 配置基本设置：
    • Name 名称：n8n_instance_role
    • Namespace 命名空间：留空
    • Source 源：Attribute
  3. 展开 Claim conditions 声明条件并点击 Add condition 添加条件。

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

    User Type 用户类型 Scoped Groups 范围组 Source 源 Value 值
    Members n8n-chatusers Attribute global:chatUser
    Members n8n-users Attribute global:member
    Members n8n-admins Attribute global:admin
    Members n8n-owners Attribute global:owner

条件顺序

条件按顺序求值。将最高权限的组（owners）放在最后。

  1. 点击 Save 保存。

测试配置#

  1. 在 n8n 中，进入 Settings > SSO。
  2. 将 Role assignment 设置为 Instance roles via SSO。
  3. 将 Role mapping method 设置为 Map rules on your IdP。
  4. 点击 Test settings。
  5. 验证 SAML 响应中是否显示了正确的 n8n_instance_role 值。

故障排除#

声明未出现在 SAML 响应中

  • 验证用户是否为至少一个已配置组的成员。
  • 检查组是否已分配给企业应用程序。
  • 确保条件中已将 Attribute 配置为源。
  • 使用浏览器扩展插件（如"SAML Chrome Panel"）查看应用程序的 SAML 响应。

用户获得了错误的角色

  • 检查条件顺序（最高权限的组应在最后）。

使用 App Roles 而不是基于组的 claims 分配多个项目角色#

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

若要可靠地分配多个项目及其对应角色，请使用 App Registration 中定义的 App Roles，而不是基于组的 claims：

  1. 在 n8n SAML 应用的 App Registration 中，定义表示每个项目和权限组合的 App Roles（例如 <projectId>:<role>）。
  2. 保存更新后的 App Manifest。
  3. 在 Enterprise Application 中，在 Users and groups 下将用户或组分配给这些 App Roles。
  4. 在 Single sign-on > Attributes & Claims 中更新 n8n_projects SAML claim，使其来源为 user.assignedroles。这会在 SAML 响应中以数组形式发出所有已分配角色。

此设置可确保 n8n 正确接收所有项目分配，从而在多个项目中启用适当访问。虽然定义 App Roles 会增加初始管理工作量，但它可以简化后续用户角色管理，并保证项目角色完整同步。

从基于组的 claims 迁移到 App Roles 时，请相应调整角色定义和 claims 映射，以防止项目访问权限不完整。

参考资料#