Conectar seu aplicativo à Pesquisa de IA do Azure usando identidades

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
• Habilitar o acesso baseado em função no seu serviço de pesquisa
• Instalar a biblioteca de clientes da Identidade do Azure

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.

dotnet add package Azure.Identity

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

npm install --save @azure/identity

pip install 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.

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

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

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

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)

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

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.

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:

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

• Guia do desenvolvedor de conexões sem chave
• Funções internas do Azure
• Configurar variáveis de ambiente