Partilhar via

Ligue a sua aplicação ao Azure AI Search usando identidades

No código da sua aplicação, pode configurar uma ligação sem chave ao Azure AI Search que utiliza o ID Microsoft Entra e funções para autenticação e autorização. Os pedidos de aplicação para a maioria dos serviços Azure devem ser autenticados com chaves ou ligaçõ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.

Este artigo explica como usar DefaultAzureCredential no código da sua aplicação.

Para implementar ligações sem chave no seu código, siga estes passos:

  • Ative o acesso baseado em função no seu serviço de pesquisa
  • Defina variáveis de ambiente, conforme necessário.
  • Use um tipo de credencial de biblioteca Azure Identity para criar um objeto cliente Azure AI Search.

Pré-requisitos

  • Azure AI Search, qualquer região mas deve ser um nível faturável (básico ou superior).

  • Acesso baseado em função ativado no seu serviço de pesquisa.

  • Atribuições de funções no Azure AI Search. Atribui estes papéis à tua identidade:

    • Contribuidor de Serviços de Pesquisa e Contribuidor de Dados de Índice de Pesquisa para desenvolvimento local (acesso completo)
    • Index Data Reader para consultas de produção de leitura apenas

    Para instruções passo a passo, veja Atribuir papéis para desenvolvimento.

Instalar a biblioteca de cliente do Azure Identity

Para usar uma abordagem sem chave, atualize o seu código habilitado para AI Search com a biblioteca cliente Azure Identity.

Instale a biblioteca cliente Azure Identity para .NET e a biblioteca cliente Azure Search Documents:

dotnet add package Azure.Identity
dotnet add package Azure.Search.Documents

Atualizar código-fonte para usar o DefaultAzureCredential

A biblioteca DefaultAzureCredential Azure Identity permite-lhe executar o mesmo código no ambiente de desenvolvimento local e na cloud Azure. Crie uma única credencial e reutilize a instância da credencial conforme necessário para tirar partido do cache de tokens.

Para mais informações sobre DefaultAzureCredential .NET, consulte a biblioteca cliente 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);

Referência:SearchClient, SearchIndexClient, DefaultAzureCredential

Verifique a sua ligação

Depois de configurar o cliente, verifique a sua ligação executando uma operação simples. O exemplo seguinte lista índices no seu serviço de pesquisa:

// List indexes to verify connection
var indexes = searchIndexClient.GetIndexNames();
foreach (var name in indexes)
{
    Console.WriteLine(name);
}

Uma ligação bem-sucedida imprime os nomes dos seus índices (ou uma lista vazia se não existirem índices). Se receber um erro de autenticação, verifique se o acesso baseado em funções está ativado e que a sua identidade tem as atribuições de funções necessárias.

A autoridade padrão é a cloud pública Azure. Valores personalizados audience para clouds soberanas ou especializadas incluem:

  • https://search.azure.us para Azure Government
  • https://search.azure.cn para Azure operado pela 21Vianet
  • https://search.microsoftazure.de para Azure Alemanha

Desenvolvimento local

O desenvolvimento local utilizando funções inclui estes passos:

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

Papéis para o desenvolvimento local

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

  • Pesquisar Contribuidor de Serviços, criar e gerir objetos
  • Pesquisar Índice Contribuidor de Dados, carregar e consultar um índice

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

Substitua os marcadores de posição <role-name>, <identity-id>, <subscription-id>, e <resource-group-name> pelos seus valores reais nos comandos seguintes.

  1. Entre na CLI do Azure.

    az login

    Abre-se uma janela do navegador para autenticação. Após o início de sessão bem-sucedido, o terminal mostra a sua informação de subscrição.

  2. Obtém a tua identidade pessoal.

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

    O comando devolve o ID do seu objeto de utilizador (um GUID). Guarde este valor para o próximo passo.

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

    Uma atribuição bem-sucedida devolve um objeto JSON com os detalhes da atribuição de funções.

Autenticação para desenvolvimento local

Use uma ferramenta no seu ambiente de desenvolvimento local para autenticação na identidade Azure. Depois de autenticado, a DefaultAzureCredential instância no seu código-fonte encontra e usa a sua identidade para fins de 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, o seu código precisa de conhecer o ponto final de recurso.

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

Cargas de trabalho de produção

Desdobrar cargas de trabalho de produção inclui os seguintes passos:

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

Papéis para cargas de trabalho de produção

Para criar os seus recursos de produção, precisa de criar uma identidade gerida atribuída pelo utilizador e depois atribuir essa identidade aos seus recursos com os papéis corretos.

O seguinte papel é sugerido para uma aplicação 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 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 ficheiro chama o seguinte código Bicep genérico para criar qualquer função. Tens a opção de criar múltiplos papéis RBAC, como um para o utilizador e outro para produção. Isto permite-lhe ativar tanto ambientes de desenvolvimento como de produção dentro da mesma implementaçã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 ligar ao Azure AI Search, o seu código precisa de conhecer o seu endpoint de recurso e o ID da identidade gerida.

Crie variáveis de ambiente para o seu recurso de Azure AI Search implementado 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 com a qual deve ser autenticado.

Solucionar erros comuns

Erro Motivo Solução
AuthenticationFailedException Credenciais em falta ou inválidas Assegura-te de que tens sessão iniciada com az login (CLI) ou Connect-AzAccount (PowerShell). Verifica se a tua conta Azure tem acesso à subscrição.
403 Forbidden A identidade carece de um papel obrigatório Atribuir o papel apropriado (Leitor de Dados do Índice de Pesquisa para consultas, Contribuidor de Dados do Índice de Pesquisa para indexação). As atribuições de funções podem demorar até 10 minutos a propagar-se.
401 Unauthorized RBAC não ativado no serviço de pesquisa Ative o acesso baseado em funções no portal Azure em Definições>Chaves>Controlo de acesso baseado em funções.
ResourceNotFoundException Nome de índice ou endpoint inválido Verifique se a AZURE_SEARCH_ENDPOINT variável de ambiente corresponde ao URL do seu serviço de pesquisa (formato: https://<service-name>.search.windows.net).
CredentialUnavailableException Nenhuma credencial válida encontrada DefaultAzureCredential Tenta múltiplos métodos de autenticação. Garante que pelo menos uma está configurada (Azure CLI, Visual Studio, variáveis de ambiente).

Conteúdo relacionado

  • Last updated on