使用 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 中完成设置
- 创建 Microsoft Entra Service Principal 凭据。输入 Directory (tenant) ID、Application (client) ID,以及脚本输出的客户端密钥。有关证书选项和主权云,请参阅 Microsoft Entra Service Principal 凭据。
- 在 Microsoft SharePoint 节点中,将 Authentication 身份验证设为 Microsoft Entra Service Principal (App-Only) Microsoft Entra 服务主体(仅应用),然后选择该凭据。
- 将 Site 站点字段设为 By URL 按 URL,并粘贴已向应用授予访问权限的站点地址。
- 运行节点。
从 n8n 2.40.0 开始,凭据的连接测试只检查应用能否登录。缺少权限、管理员同意或按站点授权时,测试仍会通过;节点运行时会失败,并返回 403 错误,指出该操作所需的权限。
相关资源
- Microsoft Entra Service Principal 凭据
- Microsoft SharePoint 节点
- Microsoft 凭据
- Sites.Selected 概述
- 为站点创建权限
- Grant-PnPEntraIDAppSitePermission