你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用标识将应用连接到 Azure AI 搜索

项目
11/11/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.windows.net"
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 login
```

获取个人标识。

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
```

获取个人标识。

(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.windows.net/ 格式。

生产工作负荷

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

选择遵循最低特权原则的 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.windows.net/ 格式。
AZURE_CLIENT_ID：这是要进行身份验证的标识。

通过

使用标识将应用连接到 Azure AI 搜索

先决条件

创建 AI 搜索资源

安装 Azure 标识客户端库

更新源代码以使用 DefaultAzureCredential

本地开发

用于本地开发的角色

用于本地开发的身份验证

为本地开发配置环境变量

生产工作负荷

用于生产工作负载的角色

生产工作负载的身份验证

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

反馈

其他资源

通过

使用标识将应用连接到 Azure AI 搜索

先决条件

创建 AI 搜索资源

安装 Azure 标识客户端库

更新源代码以使用 DefaultAzureCredential

本地开发

用于本地开发的角色

用于本地开发的身份验证

为本地开发配置环境变量

生产工作负荷

用于生产工作负载的角色

生产工作负载的身份验证

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

相关内容

反馈

其他资源