Microsoft Dataverse 凭据
你可以使用 Microsoft Dataverse OAuth2 API 凭据对 Microsoft Dataverse 节点进行身份验证。
先决条件
- Microsoft Dataverse 环境及其环境 URL。
- Microsoft Entra ID 应用注册,或创建应用注册的权限。
- 配置委托访问 API 同意的权限,或可以授予同意的管理员。
- 对于委托访问,需要具备适当安全角色的 Dataverse 用户;对于仅应用访问,需要可以创建应用程序用户的管理员。
请使用只包含工作流所需表权限的安全角色。通过身份验证并不代表有权读取或更改所有表。
支持的身份验证方法
该凭据支持 OAuth2,并提供两个 Grant Type 授权类型 选项:
| 授权类型 | 访问方式 | 要求 |
|---|---|---|
| Authorization Code 授权码(默认) | 以已登录用户身份操作。n8n 使用 refresh token 更新访问权限。 | Web 重定向 URI、委托 Dataverse 权限,以及有权访问该环境的用户。 |
| Client Credentials 客户端凭据 | 在没有已登录用户的情况下以应用程序身份操作。n8n 会在需要时获取新的 access token。 | 特定 tenant ID,以及拥有安全角色的 Dataverse 应用程序用户。无需交互式登录或重定向 URI。 |
以下设置使用 Client Secret 身份验证。该凭据还继承 Microsoft OAuth2 凭据的 Certificate 证书 身份验证。若要使用私钥和证书而非 client secret,请参阅使用证书进行身份验证。
配置凭据
在 n8n 中创建 Microsoft Dataverse OAuth2 API 凭据。连接或保存完整凭据之前,请注册应用并配置准备使用的授权类型。
注册应用程序
- 打开 Microsoft Entra 管理中心,前往 App registrations > New registration。
- 输入名称,例如
n8n Dataverse。 - 选择适合组织的支持账户类型。若只需访问一个租户,请选择 Accounts in this organizational directory only。
- 如果计划使用 Authorization Code 授权码,请从 n8n 凭据编辑器复制 OAuth Redirect URL。在 Redirect URI 下选择 Web,然后准确粘贴该 URL。对于 Client Credentials 客户端凭据,请将重定向 URI 留空。
- 选择 Register。
- 在应用的 Overview 页面中,将 Application (client) ID 复制到 n8n 的 Client ID,并将 Directory (tenant) ID 复制到 n8n 的 Tenant ID。
对于现有应用,请在应用注册的 Authentication 设置中,将 n8n 重定向 URL 添加为 Web 重定向 URI。
生成 client secret
- 在应用注册中,打开 Certificates & secrets > Client secrets。
- 选择 New client secret,输入说明,并选择符合组织策略的到期时间。
- 选择 Add,然后复制 secret 的 Value,而不是 Secret ID。Microsoft 只会显示一次该值。
- 在 n8n 中,将 Authentication 身份验证 设为 Client Secret,并将该值粘贴到 Client Secret。
请将 secret 存储在 n8n 凭据中,而不是工作流字段中。轮换 secret 时,请在旧 secret 过期前更新凭据。
设置环境和租户
在 n8n 凭据中填写以下字段:
| n8n 字段 | 值 |
|---|---|
| Grant Type 授权类型 | 用户访问选择 Authorization Code 授权码,仅应用访问选择 Client Credentials 客户端凭据。 |
| Client ID | Entra 应用注册中的 Application (client) ID。 |
| Client Secret | 使用 Client Secret 身份验证时,secret 的 Value。 |
| Tenant ID | 应用注册中的 Directory (tenant) ID。使用 Client Credentials 客户端凭据 时,请使用 tenant GUID。 |
| Environment URL 环境 URL | 环境的 HTTPS 基础 URL,例如 https://contoso.crm.dynamics.com。不要附加 /api/data/v9.2、表名称或应用路径。 |
| National Cloud 国家/地区云 | 托管 Dataverse 环境的 Microsoft 云。默认值为 Global (Public Cloud) 全球(公有云)。 |
在 Power Platform 管理中心的环境详细信息中查找环境 URL。凭据接受末尾斜杠,并在构建 scopes 和请求时将其移除。
对于 Authorization Code 授权码,Tenant ID 也接受已验证的 tenant domain。默认值 common 用于多租户 Authorization Code 应用。对于单租户应用,请将其替换为特定的 tenant GUID 或域。请勿对 Client Credentials 客户端凭据 使用 common。
配置委托用户访问
要使用 Authorization Code 授权码:
- 在 Entra 应用注册中,前往 API permissions > Add a permission。
- 选择 Dynamics CRM > Delegated permissions,然后选择 user_impersonation。这是 Access Dynamics 365 as organization users 权限。
- 选择 Add permissions。如果租户有此要求,请让管理员授予同意。
- 确保登录用户有权访问 Dataverse 环境,并拥有具备所需表权限的安全角色。
- 在 n8n 中,将 Grant Type 授权类型 设为 Authorization Code 授权码,并确认应用的 Web 重定向 URI 与凭据编辑器中的 OAuth Redirect URL 一致。
- 选择 Connect my account 连接我的账户,登录并接受所请求的访问权限,或完成组织的审批流程。
- 保存凭据。
有关委托权限要求,请参阅 Microsoft 的 Dataverse OAuth 文档。
配置仅应用访问
要使用 Client Credentials 客户端凭据,请在目标 Dataverse 环境中创建应用程序用户:
- 在 Power Platform 管理中心中,前往 Manage > Environments 并选择你的环境。
- 打开 Settings > Users + permissions > Application users。
- 选择 New app user,然后选择 Add an app。使用应用程序 ID 查找 Entra 应用注册,并选择 Add。
- 选择适当的 Business Unit,按要求输入电子邮件地址,并分配包含工作流所需权限的安全角色。
- 选择 Create 创建应用程序用户。
- 在 n8n 中,将 Grant Type 授权类型 设为 Client Credentials 客户端凭据。在 Tenant ID 中输入 tenant GUID,并确认应用凭据、Environment URL 环境 URL 和 National Cloud 国家/地区云。
- 保存凭据。此流程没有交互式账户连接步骤。
Dataverse 仅应用访问使用应用程序用户的安全角色。它不需要委托的 user_impersonation 权限或 Microsoft Graph 权限。有关详细信息,请参阅 Microsoft 的应用程序用户设置。
提示
凭据测试
保存凭据时,n8n 会针对已配置环境使用 GET /api/data/v9.2/WhoAmI 进行测试。仅获取 access token 不能证明应用程序用户存在或有权访问 Dataverse。凭据测试成功也不能保证拥有每项表操作的权限。
国家/地区云和 scopes
National Cloud 国家/地区云 控制 Microsoft Entra 登录 host。请选择与环境匹配的云:
| 国家/地区云 | 登录 host |
|---|---|
| Global (Public Cloud) 全球(公有云) | https://login.microsoftonline.com |
| US Government (GCC High) | https://login.microsoftonline.us |
| US Government (DoD) | https://login.microsoftonline.us |
| China (21Vianet) 中国(世纪互联) | https://login.partner.microsoftonline.cn |
凭据根据 National Cloud 国家/地区云 和 Tenant ID 构建授权与 token URL,并根据 Environment URL 环境 URL 构建 scope:
- Authorization Code 授权码:
<environment-url>/.default offline_access - Client Credentials 客户端凭据:
<environment-url>/.default
例如,https://contoso.crm.dynamics.com 的 Authorization Code scope 为 https://contoso.crm.dynamics.com/.default offline_access。
你无需手动输入这些 URL 或 scopes。节点调用 Dataverse 环境,而不是 Microsoft Graph,因此凭据会隐藏 Microsoft Graph base URL 字段。
常见问题
重定向 URI 不匹配
从 n8n 复制 OAuth Redirect URL,并在 Entra 中将该准确 URL 注册为 Web 重定向 URI。检查 scheme、host、port 和 path。不要用 Dataverse 环境 URL 代替。重定向 URI 适用于 Authorization Code 授权码,不适用于 Client Credentials 客户端凭据。
需要管理员批准
请让 Entra 管理员审核并授予所请求的委托 Dataverse 权限,然后重新连接凭据。Entra 同意和 Dataverse 安全角色是两项独立要求:仅有同意不会让用户获得环境中各行的访问权限。
Token 请求失败
检查 Client ID 是否属于该应用注册,以及 Client Secret 是否包含当前 secret 值而不是 ID。对于 Client Credentials 客户端凭据,请将 common 替换为 tenant GUID。确保 National Cloud 国家/地区云 与环境匹配,并且 Environment URL 环境 URL 是其 HTTPS 基础 URL。
凭据测试或节点请求返回访问错误
对于委托访问,请验证已登录用户能否访问该环境,以及是否拥有所需的 Dataverse 安全角色。
对于仅应用访问,请验证活动应用程序用户是否存在于 Environment URL 环境 URL 对应的同一环境中、是否使用与 Client ID 相同的应用程序 ID,以及是否拥有所需角色。只添加缺失权限,不要分配宽泛的管理员访问权限。
如果凭据测试成功,但表或列选择器失败,请检查选择器所需的 metadata 访问权限。如果写入失败,请检查目标表和任何相关行的权限。