在不使用密钥的情况下使用 Azure AI 搜索

在应用程序代码中,可以设置与 Azure AI 搜索的无密钥连接,使用 Microsoft Entra ID 和角色进行身份验证和授权。 应用程序对大多数 Azure 服务的请求必须使用密钥或无密钥连接进行身份验证。 开发人员必须尽量避免在不安全的位置公开密钥。 能够访问密钥的任何人都可以对服务进行身份验证。 与帐户密钥相比,无密钥身份验证具有更好的管理和安全优势,因为无需存储密钥(或连接字符串)。

通过以下步骤启用无密钥连接:

  • 配置身份验证。
  • 根据需要设置环境变量。
  • 使用 Azure 标识库凭据类型创建 Azure AI 搜索客户端对象。

先决条件

需要为本地开发和生产工作负载完成以下步骤:

创建 AI 搜索资源

在继续阅读本文之前,需要一个 Azure AI 搜索资源以便进行操作。 如果没有资源,请立即创建资源。 为资源启用基于角色的访问控制 (RBAC)

安装 Azure 标识客户端库

在不使用无密钥方式在本地工作之前,请使用 Azure 标识客户端库更新已启用 AI 搜索的代码。

安装适用于 .NET 的 Azure 标识客户端库

dotnet add package Azure.Identity

更新源代码以使用 DefaultAzureCredential

使用 Azure 标识库的 DefaultAzureCredential,可以在本地开发环境和 Azure 云中运行相同的代码。 创建一个单一凭据,并在需要时重复使用该凭据实例,以利用令牌缓存。

有关适用于 .NET 的 DefaultAzureCredential 的详细信息,请参阅适用于 .NET 的 Azure 标识客户端库

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;
using Azure.Identity;
using System;
using static System.Environment;

string endpoint = GetEnvironmentVariable("AZURE_SEARCH_ENDPOINT");
string indexName = "my-search-index";

DefaultAzureCredential credential = new();
SearchClient searchClient = new(new Uri(endpoint), indexName, credential);
SearchIndexClient searchIndexClient = new(endpoint, credential);

本地开发

不使用无密钥方式进行本地开发包括以下步骤:

  • 为个人标识分配对特定资源的 RBAC 角色。
  • 使用工具向 Azure 进行身份验证。
  • 为资源建立环境变量。

用于本地开发的角色

作为本地开发人员,Azure 标识需要完全控制你的服务。 RBAC 角色提供了这种控制。 若要在开发过程中管理资源,建议使用以下角色:

  • 搜索服务参与者
  • 搜索索引数据参与者
  • 搜索索引数据读取者

使用以下工具之一查找个人标识。 使用该标识作为 <identity-id> 值。

  1. 登录到 Azure CLI。

    az cloud set -n AzureChinaCloud
    az login
    # az cloud set -n AzureCloud   //means return to Public Azure.
    
  2. 获取个人标识。

    az ad signed-in-user show \
        --query id -o tsv
    
  3. 将基于角色的访问控制 (RBAC) 角色分配给资源组的标识。

    az role assignment create \
        --role "<role-name>" \
        --assignee "<identity-id>" \
        --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"
    

如果适用,请将 <identity-id><subscription-id><resource-group-name> 替换为实际值。

用于本地开发的身份验证

在本地开发环境中使用工具向 Azure 标识进行身份验证。 进行身份验证后,源代码中的 DefaultAzureCredential 实例会查找并使用该身份验证。

为本地开发配置环境变量

若要连接到 Azure AI 搜索,代码需要知道资源终结点。

为 Azure AI 搜索终结点创建一个名为 AZURE_SEARCH_ENDPOINT 的环境变量。 此 URL 通常采用 https://<YOUR-RESOURCE-NAME>.search.azure.cn/ 格式。

生产工作负荷

部署生产工作负载包括以下步骤:

  • 选择遵循最低特权原则的 RBAC 角色。
  • 将对特定资源的 RBAC 角色分配给生产标识。
  • 为资源设置环境变量。

用于生产工作负载的角色

若要创建生产资源,需要创建用户分配的托管标识,然后使用正确的角色将该标识分配给资源。

建议对生产应用程序使用以下角色:

角色名称 Id
搜索索引数据读取者 1407120a-92aa-4202-b7e9-c0e197c71c8f

生产工作负载的身份验证

使用以下 Azure AI 搜索 Bicep 模板创建资源并设置 的身份验证identityId。 Bicep 需要角色 ID。 此 Bicep 代码片段中显示的 name 不是 Azure 角色;它特定于 Bicep 部署。

// main.bicep
param environment string = 'production'
param roleGuid string = ''

module aiSearchRoleUser 'core/security/role.bicep' = {
    scope: aiSearchResourceGroup
    name: 'aiSearch-role-user'
    params: {
        principalId: (environment == 'development') ? principalId : userAssignedManagedIdentity.properties.principalId 
        principalType: (environment == 'development') ? 'User' : 'ServicePrincipal'
        roleDefinitionId: roleGuid
    }
}

main.bicep 文件调用以下通用 Bicep 代码,用于创建任何角色。 可以选择创建多个 RBAC 角色,例如为用户创建一个角色,再为生产创建另一个角色。 这样,就可以在同一 Bicep 部署中同时启用开发和生产环境。

// core/security/role.bicep
metadata description = 'Creates a role assignment for an identity.'
param principalId string // passed in from main.bicep

@allowed([
    'Device'
    'ForeignGroup'
    'Group'
    'ServicePrincipal'
    'User'
])
param principalType string = 'ServicePrincipal'
param roleDefinitionId string // Role ID

resource role 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
    name: guid(subscription().id, resourceGroup().id, principalId, roleDefinitionId)
    properties: {
        principalId: principalId
        principalType: principalType
        roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    }
}

为生产工作负载配置环境变量

若要连接到 Azure AI 搜索,代码需要知道资源终结点以及托管标识的 ID。

为已部署的无密钥 Azure AI 搜索资源创建环境变量:

  • AZURE_SEARCH_ENDPOINT:此 URL 是 Azure AI 搜索资源的接入点。 此 URL 通常采用 https://<YOUR-RESOURCE-NAME>.search.azure.cn/ 格式。
  • AZURE_CLIENT_ID:这是要进行身份验证的标识。