在不使用密钥的情况下使用 Azure AI 搜索
在应用程序代码中,可以设置与 Azure AI 搜索的无密钥连接,使用 Microsoft Entra ID 和角色进行身份验证和授权。 应用程序对大多数 Azure 服务的请求必须使用密钥或无密钥连接进行身份验证。 开发人员必须尽量避免在不安全的位置公开密钥。 能够访问密钥的任何人都可以对服务进行身份验证。 与帐户密钥相比,无密钥身份验证具有更好的管理和安全优势,因为无需存储密钥(或连接字符串)。
通过以下步骤启用无密钥连接:
- 配置身份验证。
- 根据需要设置环境变量。
- 使用 Azure 标识库凭据类型创建 Azure AI 搜索客户端对象。
先决条件
需要为本地开发和生产工作负载完成以下步骤:
创建 AI 搜索资源
在继续阅读本文之前,需要一个 Azure AI 搜索资源以便进行操作。 如果没有资源,请立即创建资源。 为资源启用基于角色的访问控制 (RBAC)。
安装 Azure 标识客户端库
在不使用无密钥方式在本地工作之前,请使用 Azure 标识客户端库更新已启用 AI 搜索的代码。
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>
值。
登录到 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>"
如果适用,请将 <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
:这是要进行身份验证的标识。