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

项目
12/18/2024

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

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

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

先决条件

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

创建 AI 搜索资源

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

安装 Azure 标识客户端库

要使用无密钥方法，请使用 Azure 标识客户端库更新启用了 AI 搜索的代码。

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

dotnet add package Azure.Identity

使用以下 POM 文件安装适用于 Java 的 Azure 标识客户端库：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.10.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

安装适用于 JavaScript 的 Azure 标识客户端库：

npm install --save @azure/identity

安装适用于 Python 的 Azure 标识客户端库：

pip install 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);

有关适用于 Java 的 DefaultAzureCredential 的详细信息，请参阅适用于 Java 的 Azure 标识客户端库。

import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.search.documents.SearchAsyncClient;
import com.azure.search.documents.SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.indexes.SearchIndexAsyncClient;
import com.azure.search.documents.indexes.SearchIndexClientBuilder;

String ENDPOINT = System.getenv("AZURE_SEARCH_ENDPOINT");
String INDEX_NAME = "my-index";

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();

// Sync SearchClient
SearchClient searchClient = new SearchClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .indexName(INDEX_NAME)
    .buildClient();

// Sync IndexClient
SearchIndexClient searchIndexClient = new SearchIndexClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .buildClient();

// Async SearchClient
SearchAsyncClient searchAsyncClient = new SearchClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .indexName(INDEX_NAME)
    .buildAsyncClient();

// Async IndexClient
SearchIndexAsyncClient searchIndexAsyncClient = new SearchIndexClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .buildAsyncClient();

有关适用于 JavaScript 的 DefaultAzureCredential 的详细信息，请参阅适用于 JavaScript 的 Azure 标识客户端库。

import { DefaultAzureCredential } from "@azure/identity";
import {
  SearchClient,
  SearchIndexClient
} from "@azure/search-documents";

const AZURE_SEARCH_ENDPOINT = process.env.AZURE_SEARCH_ENDPOINT;
const index = "my-index";
const credential = new DefaultAzureCredential();

// To query and manipulate documents
const searchClient = new SearchClient(
  AZURE_SEARCH_ENDPOINT,
  index,
  credential
);

// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient(
  AZURE_SEARCH_ENDPOINT, 
  credential
);

有关适用于 Python 的 DefaultAzureCredential 的详细信息，请参阅适用于 Python 的 Azure 标识客户端库。

import os
from azure.search.documents import SearchClient
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts

# Azure Public Cloud
audience = "https://search.azure.cn"
authority = AzureAuthorityHosts.AZURE_PUBLIC_CLOUD

service_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
index_name = os.environ["AZURE_SEARCH_INDEX_NAME"]
credential = DefaultAzureCredential(authority=authority)

search_client = SearchClient(
    endpoint=service_endpoint, 
    index=index_name, 
    credential=credential, 
    audience=audience)

search_index_client = SearchIndexClient(
    endpoint=service_endpoint, 
    credential=credential, 
    audience=audience)

本地开发

使用角色的本地开发过程包括以下步骤：

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

用于本地开发的角色

作为本地开发人员，你的 Azure 标识需要能够完全控制数据平面操作。以下是建议的角色：

搜索服务参与者，创建和管理对象
搜索索引数据参与者，加载索引
搜索索引数据读取者，查询索引

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

登录到 Azure CLI。

az cloud set -n AzureChinaCloud
az login
# az cloud set -n AzureCloud   //means return to Public Azure.

获取个人标识。

az ad signed-in-user show \
    --query id -o tsv

将基于角色的访问控制 (RBAC) 角色分配给资源组的标识。

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

使用 PowerShell 登录。

Connect-AzAccount -Environment AzureChinaCloud

获取个人标识。

(Get-AzContext).Account.ExtendedProperties.HomeAccountId.Split('.')[0]

将基于角色的访问控制 (RBAC) 角色分配给资源组的标识。

New-AzRoleAssignment -ObjectId "<identity-id>" -RoleDefinitionName "<role-name>" -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：这是要进行身份验证的标识。

通过