Microsoft Entra 服务主体凭据
Microsoft Entra 服务主体凭据让 n8n 能够以仅应用方式访问 Microsoft Graph。n8n 不以个人身份登录,而是使用管理员在 Microsoft Entra 管理中心一次性设置的应用注册进行身份验证。这种方式适合无人值守和共享工作流:无需担心用户会话过期,也无需管理各个用户的同意。
您可以使用这些凭据来验证以下节点:
- Microsoft Excel (OneDrive)
- Microsoft Excel (SharePoint)
- Microsoft OneDrive
- Microsoft OneDrive 触发器
- Microsoft Outlook
- Microsoft Outlook 触发器
- Microsoft SharePoint
- Microsoft SharePoint 触发器
- Microsoft Teams
- Microsoft Teams 触发器
- Microsoft To Do
提示
节点版本要求
Microsoft Excel (OneDrive)、Microsoft Outlook、Microsoft SharePoint 和 Microsoft Teams 节点从节点版本 2 开始支持此凭据。Microsoft Excel (SharePoint) 节点从节点版本 1 开始支持此凭据。
先决条件
- Microsoft 365 组织租户。个人 Microsoft 账户不支持应用程序权限。
- 能够以管理员身份访问 Microsoft Entra 管理中心,并创建应用注册和授予管理员同意;或者由另一位管理员为您授予同意。
支持的身份验证方法
- OAuth2 客户端凭据,使用 client secret 或证书(已签名的客户端断言)
相关资源
有关更多信息,请参阅 Microsoft 的文档:
- 无需用户即可获取访问权限:仅应用身份验证的工作原理
- Microsoft Graph 权限参考
- 向应用程序授予租户范围的管理员同意
仅应用访问与 OAuth2 有何不同
使用 Microsoft OAuth2 凭据时,节点以登录用户的身份执行操作。使用服务主体凭据时没有登录用户,因此节点的使用方式会有所不同:
- 您需要选择以谁的身份或对什么对象执行操作。选择此凭据时,每个节点都会显示一个额外的必填参数:Microsoft OneDrive、Microsoft OneDrive Trigger 触发器和 Microsoft Excel (OneDrive) 中的 Access As 访问身份(用户或驱动器),Microsoft Outlook 和 Microsoft Outlook Trigger 触发器中的 Mailbox 邮箱,以及 Microsoft To Do 中的 User 用户。请输入用户主体名称(UPN),例如
[email protected],或用户对象 ID。在 Access As 访问身份字段中,也可以选择 Drive 驱动器并输入驱动器 ID。这些字段没有列表选择器,请直接粘贴值。在 Microsoft Teams 节点中,Authentication 身份验证选项标记为 Service Principal (App-Only) 服务主体(仅应用);Task 任务操作会隐藏 Team 团队选择器,并将 Plan 计划、Bucket 存储桶和 Assigned To 分配给选择器替换为纯 ID 字段;Online Meeting 在线会议操作则会添加 Organizer 组织者字段,用于指定应用所管理会议的用户。 - 权限适用于整个租户。应用程序权限不限于单个用户。例如,
Mail.Send应用程序权限允许应用以租户中任意邮箱的身份发送邮件,除非使用 Exchange Online 应用程序访问策略进行限制。n8n 建议使用应用程序访问策略限定租户范围邮件权限的作用域。 - 选择器可以看到整个租户。例如,Microsoft Teams 的 Team 团队选择器会列出组织中的所有团队,而不只是应用已经加入的团队。
- 某些操作不可用。节点会隐藏只适用于登录用户的功能(例如驱动器搜索或 Teams 聊天),或者通过说明性错误阻止操作。请参阅仅应用访问不支持的操作。
设置应用程序注册
在 n8n 中创建凭据之前,请在 Microsoft Entra 管理中心完成以下步骤。如果想从命令行为 Microsoft SharePoint 节点设置应用注册,请参阅使用 Azure CLI 配置 SharePoint 应用注册。
注册应用
- 打开 Microsoft Entra 管理中心,然后转到 Entra ID > App registrations。
- 选择 New registration。
- 输入应用的 Name,例如
n8n service principal。 - 在 Supported account types 中选择 Accounts in this organizational directory only。无需填写重定向 URI。
- 选择 Register。
- 在应用的 Overview 页面中,复制 Application (client) ID 和 Directory (tenant) ID。在 n8n 中需要填写这两个值。
添加应用程序权限
- 在应用注册中,选择 API permissions > Add a permission > Microsoft Graph。
- 选择 Application permissions。不要选择 Delegated permissions:仅应用访问会忽略委派 scope,而且两种类型使用的权限名称不同。
- 添加计划使用的节点所需的权限。请参阅节点所需的应用程序权限。
- 选择 Add permissions。
授予管理员同意
- 在 API permissions 页面中,选择 Grant admin consent for
<your-tenant>并确认。 - 检查每项权限的 Status 列是否都显示 Granted。
警告
缺少管理员同意会导致一般权限错误
如果未授予管理员同意,起初看起来可能一切正常:凭据能够保存,Microsoft 也仍会签发 token。但 token 不包含权限,因此每项操作都会失败,并显示一般的 Microsoft Graph 权限错误,例如 HTTP 403 Authorization_RequestDenied(Insufficient privileges to complete the operation)。这并非凭据值有误。
要解决此问题,请打开应用注册的 API permissions 页面,检查每项权限是否显示 Granted;若没有,请授予管理员同意。n8n 会缓存 access token,因此授予同意后请重新测试凭据。如果仍然失败,请重新创建凭据,以强制获取新的 token。
创建 client secret
- 在应用注册中,选择 Certificates & secrets > Client secrets > New client secret。
- 输入 Description,例如
n8n credential,然后选择到期时间。 - 选择 Add。
- 立即复制 secret 的 Value。Microsoft 只显示一次。
在 n8n 中创建凭据
在 n8n 中创建新的 Microsoft Entra Service Principal Microsoft Entra 服务主体凭据,并填写以下字段:
- Directory (Tenant) ID 目录(租户)ID:应用注册 Overview 页面中的 Directory (tenant) ID。也可以使用经过验证的域,例如
contoso.onmicrosoft.com。 - Application (Client) ID 应用程序(客户端)ID:应用注册 Overview 页面中的 Application (client) ID。
- Client Secret 客户端密钥:您复制的 client secret 值。
- Microsoft Graph API Base URL Microsoft Graph API 基础 URL:除非租户位于主权云中,否则请保留 Global 全局。请参阅主权云环境。
若要使用证书而不是 client secret 进行身份验证,请将 Authentication 身份验证设为 Certificate 证书,然后粘贴私钥和证书。必须将证书上传到应用注册的 Certificates & secrets 中。
保存并测试凭据。从 n8n 2.40.0 开始,连接测试只检查应用能否登录,因此测试本身不需要任何应用程序权限。缺少权限或管理员同意时,测试仍会通过,但节点运行时会失败。在 n8n 2.40.0 之前,测试会从 Microsoft Graph 读取组织信息,因此还需要 Organization.Read.All(或 Directory.Read.All)应用程序权限。
节点所需的应用程序权限
为您计划使用的每个节点添加应用程序权限,然后授予管理员同意。该表中的所有权限都是 Microsoft Graph 应用程序权限,而不是委派权限。
| 节点 | 所需的应用程序权限 |
|---|---|
| 所有节点(n8n 2.40.0 之前的凭据测试) | Organization.Read.All 或 Directory.Read.All。从 n8n 2.40.0 开始,凭据测试不需要应用程序权限。 |
| Microsoft OneDrive 和 Microsoft OneDrive 触发器 | Files.ReadWrite.All(Files.Read.All 足以进行只读操作和触发器) |
| Microsoft Excel (OneDrive) | Files.ReadWrite.All |
| Microsoft Outlook | Mail.ReadWrite(消息、草稿、文件夹和附件;Reply 回复和 Draft: Send 草稿:发送也需要此权限,因为它们会在发送前创建或更新草稿)、Mail.Send(发送和回复)、Calendars.ReadWrite(日历和事件)、Contacts.ReadWrite(联系人)、MailboxSettings.Read(加载 Categories 类别下拉列表)。只添加操作所需的权限。 |
| Microsoft Outlook 触发器 | Mail.Read |
| Microsoft SharePoint | 读取操作使用 Sites.Read.All,写入操作使用 Sites.ReadWrite.All。对于文档库中的数据项,也可以使用 Files.Read.All(Item: Get 数据项:获取)或 Files.ReadWrite.All(Item: Delete 数据项:删除)。若要将应用限制到所选站点,请改为授予 Sites.Selected,并参阅按站点授予访问权限。 |
| Microsoft SharePoint 触发器 | Sites.Read.All。若要将应用限制到所选站点,请改为授予 Sites.Selected,并参阅按站点授予访问权限。 |
| Microsoft Teams 和 Microsoft Teams 触发器 | Team.ReadBasic.All,以及下表中对应操作所需的权限 |
| Microsoft To Do | Tasks.ReadWrite.All |
Microsoft Teams 节点需要 Team.ReadBasic.All 来列出团队,以及每个操作的权限:
| Teams 操作 | 应用程序权限 |
|---|---|
| Activity Notification 活动通知:Send 发送 | TeamsActivity.Send;若要从列表选择接收者,还需要 User.Read.All。接收者还必须安装配套 Teams 应用。请参阅发送活动通知。 |
| Channel 频道:Get 获取、Get Many 获取多个 | Channel.ReadBasic.All |
| Channel 频道:Create 创建 | Channel.Create |
| Channel 频道:Update 更新 | ChannelSettings.ReadWrite.All |
| Channel 频道:Delete 删除 | Channel.Delete.All |
| Channel Message 频道消息:Get 获取、Get Many 获取多个、Get Many Replies 获取多个回复 | ChannelMessage.Read.All |
| Online Meeting 在线会议:Create 创建、Create or Get 创建或获取、Update 更新、Delete 删除 | OnlineMeetings.ReadWrite.All,并为组织者配置应用程序访问策略。请参阅允许仅应用访问在线会议。 |
| Online Meeting 在线会议:Get 获取 | OnlineMeetings.Read.All(或 OnlineMeetings.ReadWrite.All),并为组织者配置应用程序访问策略 |
| Online Meeting 在线会议:从列表选择组织者或通过用户主体名称指定组织者 | User.Read.All。直接输入组织者的 object ID 时不需要此权限。 |
| Task 任务:所有操作 | Tasks.ReadWrite.All |
| Trigger 触发器:New Channel 新频道 | Channel.ReadBasic.All |
| Trigger 触发器:New Channel Message 新频道消息 | ChannelMessage.Read.All |
| Trigger 触发器:New Team Member 新团队成员 | TeamMember.Read.All |
按站点授予访问权限
租户范围的 Sites.Read.All 或 Sites.ReadWrite.All 会让应用有权访问组织中的每个 SharePoint 站点。如果安全团队希望逐个站点授予访问权限,请改用 Sites.Selected 权限。Microsoft SharePoint 节点(从版本 2 开始)、Microsoft SharePoint Trigger 节点和 Microsoft Excel (SharePoint) 节点都支持此权限。
按站点访问需要两个步骤。第二步在 Entra 管理中心和 SharePoint 管理中心都没有对应页面,因此许多设置会遗漏它:
- 添加权限并授予管理员同意。在应用注册中,添加
Sites.Selected应用程序权限来代替租户范围的Sites.*权限,然后授予管理员同意。 - 授予应用对每个站点的访问权限。管理员需要对应用应访问的每个站点调用一次 Microsoft Graph 站点权限端点:
POST https://graph.microsoft.com/v1.0/sites/<site-id>/permissions
Content-Type: application/json
{
"roles": ["write"],
"grantedToIdentities": [
{
"application": {
"id": "<application-client-id>",
"displayName": "<app-registration-name>"
}
}
]
}
只读访问使用 read 角色,节点写入操作使用 write。您可以通过 Graph Explorer 或任何能调用 Microsoft Graph 的工具发送请求。SharePoint 管理员也可以改用 PnP PowerShell 的 Grant-PnPEntraIDAppSitePermission。有关从空白租户到完成站点授权的完整流程,请参阅使用 Azure CLI 配置 SharePoint 应用注册。
发送请求的用户需要有权管理站点权限:在 Graph Explorer 中,发送前打开 Modify permissions 并同意 Sites.FullControl.All。如果此请求返回 403 Access denied,表示发送请求的账户或工具缺少该权限,而不是要授予访问权限的应用有问题。
要查找站点的 <site-id>,请按 hostname 和 path 发出请求:GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/mysite。
使用 Sites.Selected 时,节点无法搜索或列出站点,因为 Microsoft Graph 在没有租户范围读取权限时不支持站点发现。请改为粘贴站点 URL 或 ID 来选择站点。如果缺少按站点授权,操作会返回 403 错误并指出所需权限。
允许仅应用访问在线会议
使用此凭据时,Microsoft Teams 节点的 Online Meeting 在线会议操作会代表您在节点的 Organizer 组织者字段中选择的用户执行。从 n8n 2.40.0 开始,Microsoft Teams 节点支持此功能。只有 Teams 管理员为该用户向应用授予应用程序访问策略后,Microsoft Graph 才允许执行这些操作。没有此策略时,每个 Online Meeting 在线会议操作都会返回 403 错误,n8n 会提示该请求需要 OnlineMeetings.ReadWrite.All 权限以及针对组织者的应用程序访问策略。
设置步骤如下:
- 在应用注册中添加
OnlineMeetings.ReadWrite.All应用程序权限并授予管理员同意。如果只使用 Get 获取操作,OnlineMeetings.Read.All即可。如果希望从列表选择组织者,或使用用户主体名称而不是 object ID,请同时添加User.Read.All。 -
安装 Microsoft Teams PowerShell 模块,然后以 Teams 管理员身份登录:
powershell Connect-MicrosoftTeams -
创建列出应用注册 Application (client) ID 的应用程序访问策略:
powershell New-CsApplicationAccessPolicy -Identity n8n-online-meetings -AppIds "<application-client-id>" -Description "Lets n8n manage online meetings" -
使用每位用户的 object ID,将策略授予节点需要代表其执行操作的用户:
powershell Grant-CsApplicationAccessPolicy -PolicyName n8n-online-meetings -Identity "<user-object-id>"若要覆盖租户中所有尚未拥有独立策略的用户,请改为在租户范围内授予策略:
powershell Grant-CsApplicationAccessPolicy -PolicyName n8n-online-meetings -Global
策略更改最多可能需要 30 分钟才会生效。每个用户同时只能拥有一个应用程序访问策略,因此授予新策略会替换其原有策略。如果多个应用都需要访问,请在同一策略中列出所有应用 ID。
仅应用访问不支持的操作
某些 Microsoft Graph 操作只适用于登录用户。选择此凭据时,节点会隐藏或阻止这些操作,并显示说明性错误。如需使用这些操作,请改用 OAuth2 凭据:
- Microsoft OneDrive:File: Search 文件:搜索和 Folder: Search 文件夹:搜索。Microsoft Graph 只向登录用户提供驱动器搜索。
- Microsoft Excel (OneDrive):Workbook: Get Many 工作簿:获取多个,以及在 Workbook 工作簿字段中按名称搜索工作簿。请改为将字段设为 By ID 按 ID。
- Microsoft Teams:整个 Chat 聊天、Chat Member 聊天成员和 Chat Message 聊天消息资源;Channel Message 频道消息的 Create 创建、Reply 回复、Delete 删除和 Undo Delete 撤销删除操作;Task 任务的 Get Many 获取多个操作中的 Group Member 组成员模式。Online Meeting 在线会议操作可用,但需要应用程序访问策略。请参阅允许仅应用访问在线会议。
- Microsoft Teams Trigger 触发器:New Chat 新聊天和 New Chat Message 新聊天消息事件,以及所有监视全部内容的选项。请改为选择特定团队或频道。
Microsoft Outlook、Microsoft Outlook Trigger、Microsoft SharePoint、Microsoft SharePoint Trigger 和 Microsoft To Do 节点没有被阻止的操作。在 Microsoft SharePoint 节点中,站点搜索需要 Sites.Read.All 应用程序权限;如果只有 Sites.Selected,请改为通过 URL 或 ID 选择站点。
Microsoft OneDrive 中的 File: Share 文件:共享和 Folder: Share 文件夹:共享仍然可用,但以仅应用方式创建共享链接可能需要额外的租户或管理员配置。节点会针对这些操作显示通知。
主权云环境
选择与租户云环境匹配的 Microsoft Graph API Base URL Microsoft Graph API 基础 URL:
- Global (
https://graph.microsoft.com):标准 Microsoft 365 租户(默认) - US Government (
https://graph.microsoft.us):Azure 美国政府租户,包括 GCC High - US Government DOD (
https://dod-graph.microsoft.us):Azure 美国政府国防部租户 - China (
https://microsoftgraph.chinacloudapi.cn):由世纪互联在中国运营的 Microsoft 365
n8n 会自动派生匹配的登录端点,例如美国政府云使用 login.microsoftonline.us,中国云使用 login.partner.microsoftonline.cn,因此无需配置 token 或授权 URL。请在相应云环境的 Entra 管理中心完成应用注册;节点会通过您选择的端点路由所有 Microsoft Graph 调用。
常见问题
以下是 Microsoft Entra 服务主体凭据的常见错误和问题:
- 凭据测试通过,但每项操作都失败。从 n8n 2.40.0 开始,连接测试只检查应用能否登录,不检查它拥有的权限。缺少应用程序权限、管理员同意或按站点授权时,只有在节点运行时才会暴露问题。
- 每项操作都因一般权限错误而失败。这几乎总是因为缺少应用程序权限或管理员同意。请参阅授予管理员同意中的警告。Microsoft SharePoint(版本 2)和 Microsoft Excel (SharePoint) 节点会显示更明确的消息,并指出操作所需的权限:
The app registration is missing a consented application permission for this operation. - 身份验证失败,并显示
Microsoft Entra authentication did not return an access token。Microsoft 拒绝了 token 交换,例如 AADSTS7000215(client secret 无效)、AADSTS7000222(client secret 已过期)或 AADSTS700027(证书断言被拒绝)。请检查粘贴的是 client secret 的 Value 而不是 Secret ID,并确认 secret 尚未过期;使用证书身份验证时,还要确认私钥与上传到应用注册的证书匹配。 - 权限或 secret 更改不会立即生效。n8n 会缓存 access token。授予同意或轮换 secret 后,请重新测试凭据;如果缓存的 token 持续失败,请重新创建凭据。
- 「Microsoft Entra tenant ID is not a valid GUID or domain.」请输入应用注册 Overview 页面中的 Directory (tenant) ID GUID,或
contoso.onmicrosoft.com这样的已验证域。不要输入 URL。 - Microsoft Teams 节点中的 Online Meeting 在线会议操作返回 403 错误。应用注册需要
OnlineMeetings.ReadWrite.All应用程序权限,以及针对组织者的 Microsoft Teams 应用程序访问策略。请参阅允许仅应用访问在线会议。策略更改最多可能需要 30 分钟才会生效。