n8n 中文文档

Microsoft Entra 服务主体凭据

Microsoft Entra 服务主体凭据让 n8n 能够以仅应用方式访问 Microsoft Graph。n8n 不以个人身份登录,而是使用管理员在 Microsoft Entra 管理中心一次性设置的应用注册进行身份验证。这种方式适合无人值守和共享工作流:无需担心用户会话过期,也无需管理各个用户的同意。

您可以使用这些凭据来验证以下节点:

提示

节点版本要求

Microsoft Excel (OneDrive)、Microsoft Outlook、Microsoft SharePoint 和 Microsoft Teams 节点从节点版本 2 开始支持此凭据。Microsoft Excel (SharePoint) 节点从节点版本 1 开始支持此凭据。

先决条件

  • Microsoft 365 组织租户。个人 Microsoft 账户不支持应用程序权限。
  • 能够以管理员身份访问 Microsoft Entra 管理中心,并创建应用注册和授予管理员同意;或者由另一位管理员为您授予同意。

支持的身份验证方法

  • OAuth2 客户端凭据,使用 client secret 或证书(已签名的客户端断言)

相关资源

有关更多信息,请参阅 Microsoft 的文档:

仅应用访问与 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 应用注册。

注册应用

  1. 打开 Microsoft Entra 管理中心,然后转到 Entra ID > App registrations。
  2. 选择 New registration。
  3. 输入应用的 Name,例如 n8n service principal。
  4. 在 Supported account types 中选择 Accounts in this organizational directory only。无需填写重定向 URI。
  5. 选择 Register。
  6. 在应用的 Overview 页面中,复制 Application (client) ID 和 Directory (tenant) ID。在 n8n 中需要填写这两个值。

添加应用程序权限

  1. 在应用注册中,选择 API permissions > Add a permission > Microsoft Graph。
  2. 选择 Application permissions。不要选择 Delegated permissions:仅应用访问会忽略委派 scope,而且两种类型使用的权限名称不同。
  3. 添加计划使用的节点所需的权限。请参阅节点所需的应用程序权限。
  4. 选择 Add permissions。

授予管理员同意

  1. 在 API permissions 页面中,选择 Grant admin consent for <your-tenant> 并确认。
  2. 检查每项权限的 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

  1. 在应用注册中,选择 Certificates & secrets > Client secrets > New client secret。
  2. 输入 Description,例如 n8n credential,然后选择到期时间。
  3. 选择 Add。
  4. 立即复制 secret 的 Value。Microsoft 只显示一次。

在 n8n 中创建凭据

在 n8n 中创建新的 Microsoft Entra Service Principal Microsoft Entra 服务主体凭据,并填写以下字段:

  1. Directory (Tenant) ID 目录(租户)ID:应用注册 Overview 页面中的 Directory (tenant) ID。也可以使用经过验证的域,例如 contoso.onmicrosoft.com。
  2. Application (Client) ID 应用程序(客户端)ID:应用注册 Overview 页面中的 Application (client) ID。
  3. Client Secret 客户端密钥:您复制的 client secret 值。
  4. 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 管理中心都没有对应页面,因此许多设置会遗漏它:

  1. 添加权限并授予管理员同意。在应用注册中,添加 Sites.Selected 应用程序权限来代替租户范围的 Sites.* 权限,然后授予管理员同意。
  2. 授予应用对每个站点的访问权限。管理员需要对应用应访问的每个站点调用一次 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 权限以及针对组织者的应用程序访问策略。

设置步骤如下:

  1. 在应用注册中添加 OnlineMeetings.ReadWrite.All 应用程序权限并授予管理员同意。如果只使用 Get 获取操作,OnlineMeetings.Read.All 即可。如果希望从列表选择组织者,或使用用户主体名称而不是 object ID,请同时添加 User.Read.All。
  2. 安装 Microsoft Teams PowerShell 模块,然后以 Teams 管理员身份登录:

    powershell Connect-MicrosoftTeams

  3. 创建列出应用注册 Application (client) ID 的应用程序访问策略:

    powershell New-CsApplicationAccessPolicy -Identity n8n-online-meetings -AppIds "<application-client-id>" -Description "Lets n8n manage online meetings"

  4. 使用每位用户的 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 分钟才会生效。
不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。