快速入门：为自定义连接器配置 Microsoft Entra

项目
11/23/2024

本指南介绍了配置 Microsoft Entra 应用程序以与 Power Query 自定义连接器一起使用的步骤。建议连接器开发人员在继续操作之前先查看 Microsoft 标识平台的概念。

由于应用程序术语在 Microsoft Entra 平台的多个上下文中使用，因此本指南使用以下术语来区分连接器和数据源应用程序 ID：

客户端应用程序：Power Query 连接器使用的 Microsoft Entra 客户端 ID。
资源应用程序：连接器连接到的终结点（即服务或数据源）的 Microsoft Entra 应用程序注册。

为自定义连接器启用 Microsoft Entra 支持涉及以下各项：

在连接器使用的资源应用程序中定义一个或多个范围。
预授权 Power Query 客户端 ID 以使用这些范围。
在连接器定义中设置正确 Resource 值和 Scopes 值。

本指南假定 Microsoft Entra 中注册了新的资源应用程序。具有现有资源应用程序的开发人员可以跳到配置范围部分。

注意

有关在服务或应用程序中使用 Microsoft Entra 的更多详细信息，请转到快速入门指南之一。

注册资源应用程序

数据源或 API 终结点使用此资源应用程序在服务和 Microsoft 标识平台之间建立信任。

按照以下步骤注册新资源应用程序：

至少以云应用程序管理员身份登录到 Microsoft Entra 管理中心。
浏览至“标识”>“应用程序”>“应用注册”，选择“新建注册”。
输入应用程序的显示名称。
对于“支持的帐户类型”，如果只能从组织内部访问终结点，请选择“仅此组织目录中的帐户”。对于可公开访问的多租户服务，选择“任何组织目录中的帐户”。
选择“注册”。

无需指定“重定向 URI”值。

注册完成后，将显示应用程序的“概述”页面。记下“目录（租户）ID”和“应用程序（客户端）ID”值，因为其将在服务的源代码中使用。按照与服务环境和体系结构类似的 Microsoft 标识平台代码示例中指南之一，确定如何配置和使用新应用程序。

设置应用程序 ID URI

必须先为资源应用程序设置“应用程序 ID URI”，然后才能为终结点配置范围。连接器中 Aad 记录的 Resource 字段将使用此 ID。该值设置为服务的根 URL。还可以使用 Microsoft Entra 生成的默认值 api://{clientId}，其中 {clientId} 是资源应用程序客户端 ID。

转到资源应用程序的“概述”页面。
在中心屏幕上的“Essentials”下，选择“添加应用程序 ID URI”。
输入 URI 或接受基于应用 ID 的默认值。
选择“保存并继续”。

本指南中的示例假定你使用的是默认应用程序 ID URI 格式（例如 - api://00001111-aaaa-2222-bbbb-3333cccc4444）。

配置范围

范围用于定义访问服务中的 API 或数据的权限或功能。支持的范围列表是特定于服务的。如果想要确定连接器所需的最小范围集。需要为 Power Query 客户端 ID 预授权至少一个范围。

如果资源应用程序已定义范围，则可以跳到下一步。

如果服务不使用基于作用域的权限，仍可以定义连接器使用的单个范围。将来可以（可选）在服务代码中使用此范围。

在此示例中，定义名为 Data.Read 的单个范围。

转到资源应用程序的“概述”页面。
在“管理”下，选择“公开 API > 添加范围”。
对于“范围名称”，输入“Data.Read”。
对于“谁可以同意”，选择“管理员和用户”选项。
填写剩余的显示名称和说明框。
确保将“状态”设置为“已启用”。
选择“添加作用域”。

预授权 Power Query 客户端应用程序

Power Query 连接器使用两个不同的 Microsoft Entra 客户端 ID。预授权这些客户端 ID 的范围可简化连接体验。

客户端 ID	应用程序名称	使用者
a672d62c-fc7b-4e81-a576-e60dc46e951d	Power Query for Excel	桌面环境
b52893c8-bc2e-47fc-918b-77022b299bbc	Power BI 数据刷新	服务环境

要预授权 Power Query 客户端 ID，请执行以下步骤：

转到资源应用程序的“概述”页面。
在“管理”下，选择“公开 API” 。
选择添加客户端应用程序。
输入其中一个 Power Query 客户端 ID。
选择适当的“授权范围”。
选择“添加应用程序”。
对每个 Power Query 客户端 ID 重复步骤 3 - 6。

在连接器中启用 Aad 身份验证类型

通过将 Aad 身份验证类型添加到连接器的数据源记录，为连接器启用 Microsoft Entra ID 支持。

MyConnector = [
    Authentication = [
        Aad = [
            AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize",
            Resource = "{YourApplicationIdUri}"
            Scope = ".default"
        ]
    ]
];

将 {YourApplicationIdUri} 值替换为资源应用程序的“应用程序 ID URI”值，例如 api://00001111-aaaa-2222-bbbb-3333cccc4444。

在此示例中：

AuthorizationUri：用于启动身份验证流的 Microsoft Entra URL。大多数连接器可以将该值硬编码为 https://login.microsoftonline.com/common/oauth2/authorize，但如果服务支持 Azure B2B/来宾帐户，也可以动态确定该值。有关更多信息，请转到示例。
资源：连接器的应用程序 ID URI。
范围：使用 .default 范围自动接收所有预授权范围。使用 .default 可以更改资源应用程序注册中所需的连接器范围，而无需更新连接器。

有关在连接器中配置 Microsoft Entra 支持的更多详细信息和选项，请转到 Microsoft Entra ID 身份验证示例页。

重新生成连接器，现在应该能够使用 Microsoft Entra ID 向服务进行身份验证。

故障排除

本部分介绍 Microsoft Entra 应用程序配置错误时可能会收到的常见错误。

Power Query 应用程序尚未经预授权

access_denied：AADSTS650057：资源无效。客户端已请求访问某个资源，但该资源未在客户端应用程序注册中的所需权限中列出。客户端应用 ID：a672d62c-fc7b-4e81-a576-e60dc46e951d(Microsoft Power Query for Excel)。请求中的资源值：0000111-aaaa-2222-bbbb-33333cccc4444。资源应用 ID：0000111-aaaa-2222-bbbb-33333cccc4444

如果资源应用程序尚未预授权 Power Query 客户端应用程序，则可能会看到此错误。按照步骤操作以预授权 Power Query 客户端 ID。

连接器的 Aad 记录缺少范围值

access_denied：AADSTS650053：应用程序“Microsoft Power Query for Excel”要求在资源“000011111-aaaa-2222-bbbb-3333cccc4444”上不存在的范围“user_impersonation”。与应用供应商联系。

如果连接器的 Aad 记录未定义 Scope 字段，或 Scope 值为 null，则 Power Query 会请求 user_impersonation 范围。可以通过在连接器中定义 Scope 值来解决此问题。建议使用 .default 范围，但也可以在连接器级别指定范围（例如 - Data.Read）。

范围或客户端应用程序需要经管理员批准

需要管理员批准。 <租户> 需要访问组织中只有管理员才能授权的资源。使用应用前，请先向管理员请求授予此应用的权限。

如果资源应用程序需要管理员限制的权限，或者用户的租户阻止非管理员用户同意新的应用程序权限请求，则用户在身份验证流期间可能会收到此错误。通过确保连接器不需要任何管理员限制的范围并预授权资源应用程序的 Power Query 客户端 ID 可以避免此问题。

通过