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 属性
- 在 Azure AD 门户中,导航到您的 n8n 企业应用程序。
- 转到 Single sign-on 单点登录 > Attributes & Claims 属性和声明。
-
确保配置了以下标准属性:
Claim Name 声明名称 Source Attribute 源属性 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress用户邮箱 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/firstname用户名 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/lastname用户.姓 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn用户.userprincipalname
步骤 2:添加 n8n_instance_role 声明
此声明使用条件逻辑根据 Azure AD 组成员身份发出不同的角色值。
- 在 Attributes & Claims 属性和声明中,点击 Add new claim 添加新声明。
- 配置基本设置:
- Name 名称:
n8n_instance_role - Namespace 命名空间:留空
- Source 源:
Attribute
- Name 名称:
- 展开 Claim conditions 声明条件并点击 Add condition 添加条件。
-
按优先级顺序为每个 Azure AD 组添加条件:
User Type 用户类型 Scoped Groups 范围组 Source 源 Value 值 会员 n8n-聊天者 属性 global:chatUser会员 n8n-用户 属性 global:member会员 n8n-管理员 属性 global:admin会员 n8n-所有者 属性 global:owner
提示
Condition order 条件订单
条件按顺序评估。将最有特权的组(所有者)放在最后。
- 点击 Save 保存。
测试配置
- 在 n8n 中,进入 Settings > Authentication > Single sign-on (SSO)。
- 将 Role assignment 设置为 Instance roles via SSO。
- 将 Role mapping method 设置为 Map rules on your IdP。
- 点击 Test settings。
- 验证 SAML 响应中是否显示了正确的
n8n_instance_role值。
故障排除
声明未出现在 SAML 响应中
- 验证用户是否为至少一个已配置组的成员。
- 检查组是否已分配给企业应用程序。
- 确保条件中已将
Attribute配置为源。 - 使用浏览器扩展插件(如"SAML Chrome Panel")查看应用程序的 SAML 响应。
用户获得了错误的角色
- 检查条件顺序(最高权限的组应在最后)。
使用应用程序角色而不是基于组的声明来分配多个项目角色
使用 Azure AD 基于组的 claim 条件为用户分配多个项目角色时,通常只会在 SAML 断言中发送第一个匹配的组 claim。这意味着用户虽然属于多个组,但可能只看到一个项目的访问权限。
若要可靠地分配多个项目及其对应角色,请使用 App Registration 中定义的 App Roles,而不是基于组的 claims:
- 在 n8n SAML 应用的 App Registration 中,定义表示每个项目和权限组合的 App Roles(例如
<projectId>:<role>)。 - 保存更新后的 App Manifest。
- 在 Enterprise Application 中,在 Users and groups 下将用户或组分配给这些 App Roles。
- 在 Single sign-on > Attributes & Claims 中更新
n8n_projectsSAML claim,使其来源为user.assignedroles。这会在 SAML 响应中以数组形式发出所有已分配角色。
此设置可确保 n8n 正确接收所有项目分配,从而在多个项目中启用适当访问。虽然定义 App Roles 会增加初始管理工作量,但它可以简化后续用户角色管理,并保证项目角色完整同步。
从基于组的 claims 迁移到 App Roles 时,请相应调整角色定义和 claims 映射,以防止项目访问权限不完整。
参考文献
相关资源
不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。