Compartilhar via

Conectar seu aplicativo à Pesquisa de IA do Azure usando identidades

  • Artigo

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

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

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

Pré-requisitos

As etapas a seguir precisam ser executadas tanto para as cargas de trabalho locais de desenvolvimento quanto de produção:

Criar um recurso de Pesquisa de IA

Antes de continuar com este artigo, você precisa de um recurso da Pesquisa de IA do Azure com o qual possa trabalhar. Se 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 clientes da Identidade do Azure

Para usar uma abordagem sem chave, atualize o código habilitado para Pesquisa de IA com a biblioteca de clientes da Identidade do Azure.

Instalar a biblioteca de clientes da Identidade do Azure para .NET:

dotnet add package Azure.Identity

Atualize o código-fonte para usar DefaultAzureCredential

A DefaultAzureCredential da biblioteca Identidade do Azure permite que você execute 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 tirar proveito do armazenamento do token em cache.

Para obter mais informações sobre a DefaultAzureCredential para .NET, confira a biblioteca de clientes da Identidade do Azure 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 o seu recurso.

Funções para o desenvolvimento local

Como 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:

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

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

  1. Entrar na CLI do Azure.

    az login

  2. Obtenha sua identidade pessoal.

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

  3. Atribua a função de controle de acesso baseado em função (RBAC) à identidade para o 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> por seus valores reais.

Autenticação para desenvolvimento local

Use uma ferramenta no seu ambiente de desenvolvimento local para sua autenticação na Identidade do Azure. Após você ter sido autenticado, a instância de DefaultAzureCredential no seu código-fonte encontra e usa a autenticação.

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

Configurar variáveis de ambiente para o desenvolvimento local

Para se conectar à Pesquisa de IA do Azure, seu código precisa saber qual é o ponto de extremidade do seu recurso.

Crie uma variável de ambiente chamada AZURE_SEARCH_ENDPOINT para o ponto de extremidade da sua Pesquisa de IA do Azure. Essa 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 essas etapas:

  • Escolha as funções RBAC que aderem ao princípio do privilégio mínimo.
  • Atribua funções RBAC à sua identidade de produção no recurso específico.
  • Configure variáveis de ambiente para o 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 pelo usuário e 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 Bicep da Pesquisa de IA do Azure para criar o recurso e definir a autenticação para a identityId. O Bicep requer a ID da função. O name mostrado nesse snippet do Bicep não é a função do Azure; é específico 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 arquivo main.bicep chama o código Bicep genérico a seguir 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 a produção. Isso permite que você habilite tanto ambientes de desenvolvimento quanto de produção na 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 à Pesquisa de IA do Azure, seu código precisa saber qual é o ponto de extremidade do seu recurso e a ID da identidade gerenciada.

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

  • AZURE_SEARCH_ENDPOINT: essa URL é o ponto de acesso para o seu recurso da Pesquisa de IA do Azure. Essa URL geralmente tem o formato https://<YOUR-RESOURCE-NAME>.search.windows.net/.
  • AZURE_CLIENT_ID: essa é a identidade com a qual se autenticar.

Conteúdo relacionado