n8n 中文文档

使用 Azure CLI 配置 SharePoint 应用注册

本页介绍如何在新的 Microsoft 365 租户中创建应用注册,使 Microsoft SharePoint 节点能够使用 Microsoft Entra Service Principal 凭据登录。其中提供了可粘贴的权限 manifest 片段、可运行的脚本,以及大多数设置容易遗漏的按站点授权步骤。

本指南面向负责审批和创建应用注册的管理员。如果您的安全团队需要审核权限请求,请向他们提供 manifest 片段和权限表。

Microsoft SharePoint 节点从节点版本 2 开始支持仅应用访问。

开始之前

您需要:

  • 已安装 Azure CLI,并已使用 az login --tenant <your-tenant-id> 登录。
  • 有权创建应用注册并授予管理员同意的账户。授予管理员同意需要 Global Administrator 或 Privileged Role Administrator 角色。
  • 工作流将使用的每个 SharePoint 站点的地址,例如 https://contoso.sharepoint.com/sites/mysite。

选择权限级别

以下三个选项都是 Microsoft Graph Application 应用程序权限。同名的 Delegated 委派权限属于另一种权限,不适用于仅应用访问。

权限 应用可访问的范围 适用场景
Sites.Selected 仅限您授予访问权限的站点,并使用您为各站点指定的角色 默认选择。应用初始时无法访问任何站点,因此安全团队无需批准整个租户的访问即可批准此权限。
Sites.Read.All 租户中的所有站点,仅限读取 工作流会从多个站点读取内容,或需要使用节点的站点搜索。
Sites.ReadWrite.All 租户中的所有站点,可读取和写入 工作流会写入多个站点,或需要使用节点的站点搜索。

使用 Sites.Selected 时,读取和写入权限不是在 manifest 中选择的。应用注册只请求一项权限;随后在您授予应用对站点的访问权限时,逐个站点决定授予读取还是写入权限。

站点搜索(节点 Site 站点字段中的 From List 从列表选择选项)需要租户范围的读取权限。使用 Sites.Selected 时,请改为将 Site 站点字段设为 By URL 按 URL或 By ID 按 ID,这两种方式都不需要搜索。

权限 manifest 片段

将以下内容保存为 n8n-sharepoint-permissions.json。它只请求 Microsoft Graph 的 Sites.Selected,不请求其他权限:

[
    {
        "resourceAppId": "00000003-0000-0000-c000-000000000000",
        "resourceAccess": [
            {
                "id": "883ea226-0bf2-4a8f-9f9d-92c9162a727d",
                "type": "Role"
            }
        ]
    }
]

若要改用租户范围的权限,请替换唯一的 id 值:

应用程序权限 id 值 type
Sites.Selected 883ea226-0bf2-4a8f-9f9d-92c9162a727d Role
Sites.Read.All 332a536c-c7ef-4017-ab91-336970924f0d Role
Sites.ReadWrite.All 9492366f-7969-46a4-8d15-ed1a20078fff Role

resourceAppId 表示 Microsoft Graph。SharePoint 节点调用 Microsoft Graph,因此指向旧版 SharePoint Online API(00000003-0000-0ff1-ce00-000000000000)的片段不会授予节点可使用的任何权限。type 始终为 Role:Role 表示应用程序权限,Scope 表示委派权限。

可以用两种方式使用此文件:

  • Azure CLI:像下面的脚本一样,通过 --required-resource-accesses @n8n-sharepoint-permissions.json 传入。
  • Microsoft Entra 管理中心:打开应用注册,选择 Manifest,将数组粘贴为 requiredResourceAccess 的值。

使用 Azure CLI 配置应用注册

在包含 n8n-sharepoint-permissions.json 的文件夹中运行以下命令。它们会创建应用注册和客户端密钥,然后授予管理员同意,同时创建应用的服务主体:

# Create the app registration for this tenant only, with the permission already requested
APP_ID=$(az ad app create \
    --display-name "n8n SharePoint" \
    --sign-in-audience AzureADMyOrg \
    --required-resource-accesses @n8n-sharepoint-permissions.json \
    --query appId --output tsv)

# Create a client secret valid for one year, and print it once
az ad app credential reset \
    --id "$APP_ID" \
    --display-name "n8n credential" \
    --years 1 \
    --query password --output tsv

# Grant admin consent. This also creates the app's service principal in the tenant
az ad app permission admin-consent --id "$APP_ID"

# Print the two IDs you enter in n8n
echo "Application (client) ID: $APP_ID"
echo "Directory (tenant) ID: $(az account show --query tenantId --output tsv)"

复制第二条命令输出的密钥。Microsoft 只会显示一次。

请注意以下事项:

  • 对现有应用注册运行时,请为 az ad app credential reset 添加 --append。如果不添加,该命令会移除应用上已有的密钥和证书,所有使用它们的服务都会停止工作。
  • 在授予同意之前,不要运行 az ad sp create。az ad app permission admin-consent 会自行创建服务主体。如果服务主体已经存在,同意操作会失败并返回 Request_BadRequest,消息为「The <application-client-id> service principal name is already present for the tenant」。
  • 第一次运行管理员同意命令可能会失败。Microsoft Entra 需要几秒钟来复制新的应用注册。命令会报告 Directory_ObjectNotFound,并显示「Unable to read the company information from the directory」。等待片刻后再次运行即可。
  • 如果管理员同意持续失败,请改为在门户中授予。az ad app permission admin-consent 调用了一个并非对所有账户都有效的旧版 Azure 端点。请在 Microsoft Entra 管理中心打开应用注册的 API permissions API 权限页面,然后选择 Grant admin consent for <your-tenant> 为 <your-tenant> 授予管理员同意。

授予应用对站点的访问权限

如果选择了租户范围的权限,请跳过本节。只有 Sites.Selected 的应用在管理员逐站点授予访问权限前无法访问任何站点。Microsoft Entra 管理中心和 SharePoint 管理中心都没有完成此步骤的页面,因此设置时经常遗漏它。完成此步骤之前,每项操作都会返回 403 错误。

只读工作流请授予 read;上传文件或更改列表数据项的工作流请授予 write。

您需要站点 ID。可以按地址请求:

GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/mysite

PnP PowerShell

SharePoint 管理员可以使用 PnP PowerShell。连接到站点,然后授予应用访问权限:

Connect-PnPOnline -Url "https://contoso.sharepoint.com/sites/mysite" -Interactive -ClientId <pnp-app-client-id>

Grant-PnPEntraIDAppSitePermission -AppId <application-client-id> -DisplayName "n8n SharePoint" -Permissions Write

-Permissions 可使用 Read、Write、Manage 或 FullControl。节点需要 Read 或 Write。

交互式登录需要 PnP PowerShell 自己的应用注册,可以使用 Register-PnPEntraIDAppForInteractiveLogin 创建。将该应用的客户端 ID 作为 -ClientId 传入。

Microsoft Graph

由具有 Sites.FullControl.All 权限的管理员为每个站点发送一次请求:

POST https://graph.microsoft.com/v1.0/sites/<site-id>/permissions
Content-Type: application/json

{
    "roles": ["write"],
    "grantedToIdentities": [
        {
            "application": {
                "id": "<application-client-id>",
                "displayName": "n8n SharePoint"
            }
        }
    ]
}

Graph Explorer 可以发送此请求。请先打开 Modify permissions 修改权限并同意 Sites.FullControl.All。有关请求返回 403 的含义,请参阅按站点授予访问权限。

Azure CLI 无法完成此步骤的原因

即使以 Global Administrator 身份运行,针对同一端点的 az rest --method POST 也会返回 403。Azure CLI 会以 Microsoft 自有应用的身份登录,而该应用没有 Sites.FullControl.All。在您自己的应用注册中同意该权限,并不会改变 Azure CLI token 携带的权限。请改用 PnP PowerShell 或 Graph Explorer。

在 n8n 中完成设置

  1. 创建 Microsoft Entra Service Principal 凭据。输入 Directory (tenant) ID、Application (client) ID,以及脚本输出的客户端密钥。有关证书选项和主权云,请参阅 Microsoft Entra Service Principal 凭据。
  2. 在 Microsoft SharePoint 节点中,将 Authentication 身份验证设为 Microsoft Entra Service Principal (App-Only) Microsoft Entra 服务主体(仅应用),然后选择该凭据。
  3. 将 Site 站点字段设为 By URL 按 URL,并粘贴已向应用授予访问权限的站点地址。
  4. 运行节点。

从 n8n 2.40.0 开始,凭据的连接测试只检查应用能否登录。缺少权限、管理员同意或按站点授权时,测试仍会通过;节点运行时会失败,并返回 403 错误,指出该操作所需的权限。

相关资源

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。