使用 Microsoft Entra ID 授权访问搜索应用
基于 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, newDefaultAzureCredential()
) 着手以使用 Azure.Identity 通过 Microsoft Entra ID 进行身份验证。
为数据平面配置基于角色的访问
适用于:搜索索引数据参与者、搜索索引数据读取者、搜索服务参与者
在此步骤中配置搜索服务,以识别提供 OAuth2 访问令牌的数据请求上的授权头。
登录到 Azure 门户,然后打开搜索服务页面。
在左侧导航窗格中,选择“密钥”。
选择一个 API 访问控制选项。 如果你希望拥有灵活性或需要迁移应用,建议使用“两者”。
选项 说明 API 密钥 (默认)需要请求标头中的管理员或查询 API 密钥才能授权。 不使用任何角色。 基于角色的访问控制 需要角色分配中的成员身份才能完成任务,如下一步所述。 它还需要授权标头。 两者 使用基于 API 密钥或基于角色的访问控制时,请求都是有效的。
更改会立即生效,但请等待几秒钟,然后再进行测试。
对搜索服务操作和内容的所有网络调用都将遵循你选择的选项:API 密钥、持有者令牌或两者(如果你选择“两者”)。
在门户中启用基于角色的访问控制时,如果授权失败,失败模式将为“http401WithBearerChallenge”。
创建托管标识
在此步骤中,需为客户端应用程序创建托管标识。
登录 Azure 门户。
搜索“托管标识”。
选择创建。
为托管标识指定一个名称并选择一个区域。 然后选择“创建”。
为托管标识分配角色
接下来,需要授予对搜索服务的客户端托管标识访问权限。 Azure AI 搜索具有各种内置角色。 还可以创建自定义角色。
最佳做法是授予最低权限。 如果应用程序只需要处理查询,则你应该分配搜索索引数据读取者角色。 或者,如果客户端需要对搜索索引进行读写访问,则可以使用搜索索引数据参与者角色。
登录 Azure 门户。
导航到你的搜索服务。
在左侧导航窗格中,选择“访问控制 (IAM)”。
选择“+ 添加” > “添加角色分配”。
选择适用的角色:
所有者
参与者
读取器
搜索服务参与者
搜索索引数据参与者
搜索索引数据读取者
注意
所有者、参与者、读取者和搜索服务参与者是控制平面角色,不允许你访问搜索索引中的数据。 对于数据访问,请选择“搜索索引数据参与者”或“搜索索引数据读取者”角色。 有关每个角色的范围和目的的详细信息,请参阅搜索中使用的内置角色。
在“成员”选项卡上,选择要授予搜索服务访问权限的托管标识。
在“查看 + 分配”选项卡上,选择“查看 + 分配”,以分配角色 。
如果应用程序需要全面访问搜索服务、对象和内容,则可以分配多个角色,例如“搜索服务参与者”和“搜索索引数据参与者”。
在客户端中设置 Microsoft Entra 身份验证
针对搜索服务获取托管标识和角色分配后,即可向应用程序添加代码,以对安全主体进行身份验证并获取 OAuth 2.0 令牌。
使用以下客户端库进行基于角色的访问控制:
- azure.search.documents (Azure SDK for .NET)
- azure-search-documents (Azure SDK for Java)
- azure/search-documents (Azure SDK for JavaScript)
- azure.search.documents (Azure SDK for Python)
注意
若要详细了解 Microsoft Entra ID 使用的 OAuth 2.0 代码授权流,请参阅使用 OAuth 2.0 代码授权流来授权访问 Microsoft Entra Web 应用程序。
以下说明引用现有的 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 入门。 对于想要拥有更多控制或其方案缺少默认设置的开发人员,应使用其他凭据类型。