Partilhar via

Conectar seu aplicativo à Pesquisa de IA do Azure usando identidades

  • Artigo

No código do aplicativo, você pode configurar uma conexão sem chave com o Azure AI Search que usa a ID do Microsoft Entra e funções para autenticação e autorização. As solicitações de aplicativo para a maioria dos serviços do Azure devem ser autenticadas com chaves ou conexões sem chave. Os desenvolvedores devem ser diligentes para nunca expor as chaves em um local não seguro. Qualquer pessoa que obtenha acesso à chave pode autenticar-se no serviço. A autenticação sem chave oferece benefícios aprimorados de gerenciamento e segurança em relação à chave da conta, pois não há nenhuma chave (ou cadeia de conexão) para armazenar.

As conexões sem chave são habilitadas com as seguintes etapas:

  • Configure sua autenticação.
  • Defina variáveis de ambiente, conforme necessário.
  • Use um tipo de credencial da biblioteca de Identidade do Azure para criar um objeto de cliente do Azure AI Search.

Pré-requisitos

As seguintes etapas precisam ser concluídas para cargas de trabalho de desenvolvimento local e produção:

Criar um recurso de pesquisa de IA

Antes de continuar com este artigo, você precisa de um recurso do Azure AI Search para trabalhar. Se você não tiver um recurso, crie seu recurso agora. Habilite o controle de acesso baseado em função (RBAC) para o recurso.

Instalar a biblioteca de cliente do Azure Identity

Para usar uma abordagem sem chave, atualize seu código habilitado para Pesquisa de IA com a biblioteca de cliente do Azure Identity.

Instale a biblioteca de cliente do Azure Identity para .NET:

dotnet add package Azure.Identity

Atualizar o código-fonte para usar DefaultAzureCredential

A biblioteca de Identidade do DefaultAzureCredential Azure permite executar o mesmo código no ambiente de desenvolvimento local e na nuvem do Azure. Crie uma única credencial e reutilize a instância de credencial conforme necessário para aproveitar o cache de token.

Para obter mais informações sobre DefaultAzureCredential o .NET, consulte Biblioteca de cliente do Azure Identity para .NET.

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

Desenvolvimento local

O desenvolvimento local usando funções inclui estas etapas:

  • Atribua sua identidade pessoal a funções RBAC no recurso específico.
  • Use uma ferramenta como a CLI do Azure ou o Azure PowerShell para autenticar com o Azure.
  • Estabeleça variáveis de ambiente para seu recurso.

Papéis para o desenvolvimento local

Como um desenvolvedor local, sua identidade do Azure precisa de controle total sobre as operações do plano de dados. Estas são as funções sugeridas:

  • Colaborador do Serviço de Pesquisa, criar e gerenciar objetos
  • Pesquisar Contribuidor de Dados de Índice, carregar e consultar um índice

Encontre a sua identidade pessoal com uma das seguintes ferramentas. Use essa identidade como o <identity-id> valor.

  1. Iniciar sessão na CLI do Azure.

    az login

  2. Obtenha a sua identidade pessoal.

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

  3. Atribua a função RBAC (controle de acesso baseado em função) à identidade do grupo de recursos.

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

Quando aplicável, substitua <identity-id>, <subscription-id>e <resource-group-name> pelos seus valores reais.

Autenticação para desenvolvimento local

Use uma ferramenta em seu ambiente de desenvolvimento local para autenticação na identidade do Azure. Depois de autenticado, a DefaultAzureCredential instância no código-fonte localiza e usa a autenticação.

Selecione uma ferramenta para autenticação durante o desenvolvimento local.

Configurar variáveis de ambiente para desenvolvimento local

Para se conectar ao Azure AI Search, seu código precisa conhecer seu ponto de extremidade de recurso.

Crie uma variável de ambiente nomeada AZURE_SEARCH_ENDPOINT para seu ponto de extremidade do Azure AI Search. Este URL geralmente tem o formato https://<YOUR-RESOURCE-NAME>.search.windows.net/.

Cargas de trabalho de produção

Implantar cargas de trabalho de produção inclui estas etapas:

  • Escolha funções RBAC que respeitem o princípio do menor privilégio.
  • Atribua funções RBAC à sua identidade de produção no recurso específico.
  • Configure variáveis de ambiente para seu recurso.

Funções para cargas de trabalho de produção

Para criar seus recursos de produção, você precisa criar uma identidade gerenciada atribuída ao usuário e, em seguida, atribuir essa identidade aos seus recursos com as funções corretas.

A seguinte função é sugerida para um aplicativo de produção:

Nome da função Id
Leitor de dados de índice de pesquisa 1407120a-92aa-4202-b7e9-c0e197c71c8f

Autenticação para cargas de trabalho de produção

Use o seguinte modelo do Azure AI Search Bicep para criar o recurso e definir a autenticação para o identityId. O bíceps requer o ID da função. O name mostrado neste trecho do Bicep não é a função do Azure, é específica para a implantação do 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
    }
}

O main.bicep arquivo chama o seguinte código Bicep genérico para criar qualquer função. Você tem a opção de criar várias funções RBAC, como uma para o usuário e outra para produção. Isso permite habilitar ambientes de desenvolvimento e produção dentro da mesma implantação do 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)
    }
}

Configurar variáveis de ambiente para cargas de trabalho de produção

Para se conectar ao Azure AI Search, seu código precisa conhecer seu ponto de extremidade de recurso e a ID da identidade gerenciada.

Crie variáveis de ambiente para seu recurso de Pesquisa de IA do Azure implantado e sem chave:

  • AZURE_SEARCH_ENDPOINT: Este URL é o ponto de acesso para o seu recurso Azure AI Search. Este URL geralmente tem o formato https://<YOUR-RESOURCE-NAME>.search.windows.net/.
  • AZURE_CLIENT_ID: Esta é a identidade para autenticar como.

Conteúdos relacionados