使用 Microsoft Entra ID 授权访问搜索应用

项目
03/25/2024

基于 Azure AI 搜索生成的搜索应用程序现在可以使用 Microsoft 标识平台实现经身份认证和授权的访问。在 Azure 上，标识提供者是 Microsoft Entra ID。使用 Microsoft Entra ID 的一个重要优势是不再需要将凭据和 API 密钥存储在代码中。 Microsoft Entra 会对运行应用程序的安全主体（用户、组或服务）进行身份验证。如果身份验证成功，Microsoft Entra ID 会将访问令牌返回给应用程序，应用程序然后可使用该访问令牌对 Azure AI 搜索请求授权。

本文介绍如何针对 Microsoft Entra ID 配置客户端：

若要进行身份验证，需要创建托管标识作为安全原则。还可以使用不同类型的服务主体对象，不过本文将使用托管标识，因为其无需管理凭据。
关于授权，需要将一个 Azure 角色分配给托管标识，该标识负责授予运行查询或管理索引作业的权限。
更新客户端代码以调用 TokenCredential()。例如，可以从 new SearchClient(endpoint, new DefaultAzureCredential()) 着手以使用 Azure.Identity 通过 Microsoft Entra ID 进行身份验证。

为数据平面配置基于角色的访问

适用于：搜索索引数据参与者、搜索索引数据读取者、搜索服务参与者

在此步骤中配置搜索服务，以识别提供 OAuth2 访问令牌的数据请求上的授权头。

Azure 门户
REST API

登录到 Azure 门户，然后打开搜索服务页面。
在左侧导航窗格中，选择“密钥”。

选择一个 API 访问控制选项。如果你希望拥有灵活性或需要迁移应用，建议使用“两者”。

选项	说明
API 密钥	（默认）需要请求标头中的管理员或查询 API 密钥才能授权。不使用任何角色。
基于角色的访问控制	需要角色分配中的成员身份才能完成任务，如下一步所述。它还需要授权标头。
两者	使用基于 API 密钥或基于角色的访问控制时，请求都是有效的。

更改会立即生效，但请等待几秒钟，然后再进行测试。

对搜索服务操作和内容的所有网络调用都将遵循你选择的选项：API 密钥、持有者令牌或两者（如果你选择“两者”）。

在门户中启用基于角色的访问控制时，如果授权失败，失败模式将为“http401WithBearerChallenge”。

使用管理 REST API 创建或更新服务来配置服务。

对管理 REST API 的所有调用都通过 Microsoft Entra ID 进行身份验证，具有参与者或所有者权限。如果在 REST 客户端中设置经过身份验证的请求时需要帮助，请参阅使用 REST 管理 Azure AI 搜索。

获取服务设置，以便可以查看当前配置。

GET https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01

使用 PATCH 更新服务配置。以下修改启用基于密钥的访问和基于角色的访问。如果你需要仅限角色的配置，请参阅禁用 API 密钥。

在“属性”下，将“authOptions”设置为“aadOrApiKey”。 “disableLocalAuth”属性必须为 false 才能设置“authOptions”。

（可选）设置“aadAuthFailureMode”，以指定是否在身份验证失败时返回 401 而非 403。有效值为“http401WithBearerChallenge”或“http403”。
```
PATCH https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
{
    "properties": {
        "disableLocalAuth": false,
        "authOptions": {
            "aadOrApiKey": {
                "aadAuthFailureMode": "http401WithBearerChallenge"
            }
        }
    }
}
```

创建托管标识

在此步骤中，需为客户端应用程序创建托管标识。

登录 Azure 门户。
搜索“托管标识”。
选择“+ 新建”。
为托管标识指定一个名称并选择一个区域。然后选择“创建”。

为托管标识分配角色

接下来，需要向托管标识授予对搜索服务的访问权限。 Azure AI 搜索具有各种内置角色。还可以创建自定义角色。

最佳做法是授予最低权限。如果应用程序只需要处理查询，则你应该分配搜索索引数据读取者角色。或者，如果它需要对搜索索引进行读写访问，则可以使用搜索索引数据参与者角色。

登录 Azure 门户。
导航到你的搜索服务。
在左侧导航窗格中，选择“访问控制 (IAM)”。
选择“+ 添加” > “添加角色分配”。
选择适用的角色：
- 所有者
- 参与者
- 读取器
- 搜索服务参与者
- 搜索索引数据参与者
- 搜索索引数据读取者
有关可用角色的详细信息，请参阅搜索中使用的内置角色。

备注

“所有者”、“参与者”、”读取者”和“搜索服务参与者”角色不提供对搜索索引中的数据的访问权限，因此无法使用这些角色查询搜索索引或索引数据。若要对搜索索引进行数据访问，则需要“搜索索引数据参与者”或“搜索索引数据读取者”角色。
在“成员”选项卡上，选择要授予搜索服务访问权限的托管标识。
在“查看 + 分配”选项卡上，选择“查看 + 分配”，以分配角色。

如果应用程序需要全面访问搜索服务、对象和内容，则可以分配多个角色，例如“搜索服务参与者”和“搜索索引数据参与者”。

还可以使用 PowerShell 分配角色。

在客户端中设置 Microsoft Entra 身份验证

针对搜索服务获取托管标识和角色分配后，即可向应用程序添加代码，以对安全主体进行身份验证并获取 OAuth 2.0 令牌。

使用以下客户端库进行基于角色的访问控制：

注意

若要详细了解 Microsoft Entra ID 使用的 OAuth 2.0 代码授权流，请参阅使用 OAuth 2.0 代码授权流来授权访问 Microsoft Entra Web 应用程序。

.NET SDK
REST API

以下说明引用现有的 C# 示例来演示代码更改。

首先，克隆快速入门：使用 Azure SDK 进行全文搜索的 C# 部分的源代码。

该示例目前使用基于密钥的身份验证和 AzureKeyCredential 来创建 SearchClient 和 SearchIndexClient，但只需做出一项轻微的更改即可切换到基于角色的身份验证。
将 Nuget 包 Azure.Search.Documents 更新到版本 11.4 或更高版本。
导入 Azure.Identity 库以便访问其他身份验证技术。

与其在 Program.cs 的 Main() 开头使用 AzureKeyCredential，不如使用 DefaultAzureCredential，如下面的代码片段所示：

// Create a SearchIndexClient to send create/delete index commands
SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());
// Create a SearchClient to load and query documents
SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());

本地测试

用户分配的托管标识仅适用于 Azure 环境。如果在本地运行此代码，则 DefaultAzureCredential 将回退到使用凭据进行身份验证。如果计划在本地运行代码，请确保也为自己提供了对搜索服务所需的访问权限。

验证你的帐户是否具有可运行快速入门示例中的所有操作的角色分配。若要创建和查询索引，需要“搜索索引数据读取者”和“搜索索引数据参与者”角色。
转到“工具”>“选项”>“Azure 服务身份验证”，并选择你的 Azure 登录帐户。

现在，应该可以使用基于角色的访问控制进行授权，在本地系统上从 Visual Studio 运行项目。

注意

Azure.Identity 文档包含有关 DefaultAzureCredential 和通过用于 .NET 的 Azure SDK 使用 Microsoft Entra 身份验证的其他详细信息。 DefaultAzureCredential 旨在通过使用合理的默认行为处理常见方案来简化 SDK 入门。对于想要拥有更多控制或其方案缺少默认设置的开发人员，应使用其他凭据类型。

使用 Azure SDK 可以简化 OAuth 2.0 流，但你也可以直接针对应用程序中的协议进行编程。有关完整详细信息，请参阅 Microsoft 标识平台和 OAuth 2.0 客户端凭据流。

首先从 Microsoft 标识平台获取令牌：

POST /[tenant id]/oauth2/v2.0/token HTTP/1.1
Host: login.partner.microsoftonline.cn
Content-Type: application/x-www-form-urlencoded

client_id=[client id]
&scope=https%3A%2F%2Fsearch.azure.com%2F.default
&client_secret=[client secret]
&grant_type=client_credentials

所需的范围为“https://search.azure.com/.default"”。

获取令牌后，便可以向搜索服务发出请求了。

GET https://[service name].search.azure.cn/indexes/[index name]/docs?[query parameters]
Content-Type: application/json   
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...