Autorizar o acesso a um aplicativo de pesquisa usando o Microsoft Entra ID

  • Artigo

Os aplicativos de pesquisa criados no Azure AI Search agora podem usar a plataforma de identidade da Microsoft para acesso autenticado e autorizado. No Azure, o provedor de identidade é o Microsoft Entra ID. Um dos principais benefícios de usar o Microsoft Entra ID é que as credenciais e chaves da API não precisam mais ser armazenadas no código. O Microsoft Entra autentica a entidade de segurança (um usuário, um grupo ou um serviço) que executa o aplicativo. Se a autenticação tiver sucesso, o Microsoft Entra ID retornará o token de acesso ao aplicativo e o aplicativo poderá usá-lo para autorizar solicitações ao Azure AI Search.

Este artigo mostra como configurar o cliente para o Microsoft Entra ID:

  • Para autenticação, você criará uma identidade gerenciada como o princípio de segurança. Você também pode usar um tipo diferente de objeto de entidade de serviço, mas este artigo usa identidades gerenciadas porque eliminam a necessidade de gerenciar as credenciais.

  • Para autorização, você atribuirá uma função do Azure à identidade gerenciada que concede permissões para executar consultas ou gerenciar trabalhos de indexação.

  • Atualize o código do cliente para chamar TokenCredential(). Por exemplo, você pode começar a usar o novo SearchClient (ponto de extremidade, novo DefaultAzureCredential()) para autenticar por meio de um Microsoft Entra ID usando Azure.Identity.

Configurar o acesso baseado em função para o plano de dados

Aplica-se a: Colaborador de Dados de Índice de Pesquisa, Leitor de Dados de Índice de Pesquisa, Colaborador do Serviço de Pesquisa

Nesta etapa, configure seu serviço de pesquisa para reconhecer um header de autorização em solicitações de dados que fornecem um token de acesso OAuth2.

  1. Entre no portal do Azure e abra a página do serviço de pesquisa.

  2. Selecione Chaves no painel de navegação esquerdo.

    Screenshot of the keys page with authentication options.

  3. Escolha uma opção de controle de acesso a API. Recomendamos Ambos se você quiser ter flexibilidade ou precisar migrar aplicativos.

    Opção Descrição
    Chave de API (padrão) Requer uma chave de API de administrador ou de consulta no cabeçalho de solicitação para autorização. Nenhuma função é usada.
    Controle de acesso baseado em função Requer a associação em uma atribuição de função para concluir a tarefa; descrita na próxima etapa. Também requer um cabeçalho de autorização.
    Ambos As solicitações são válidas com o uso de uma chave de API ou de um controle de acesso baseado em função.

A alteração entra em vigor imediatamente, mas aguarde alguns segundos antes de testar.

Todas as chamadas de rede para operações de serviço de pesquisa e conteúdo respeitarão a opção selecionada: chaves de API, token de portador ou qualquer uma se você selecionar Ambas.

Quando você habilitar o controle de acesso baseado em função no portal, o modo de falha será "http401WithBearerChallenge" se a autorização falhar.

Criar uma identidade gerenciada

Nesta etapa, crie uma identidade gerenciada para o aplicativo cliente.

  1. Entre no portal do Azure.

  2. Procure Identidades Gerenciadas.

  3. Selecione + Criar.

  4. Dê um nome à identidade gerenciada e selecione uma região. Em seguida, selecione Criar.

    Screenshot of the Create Managed Identity wizard.

Atribuir uma função à identidade gerenciada

Em seguida, você precisa conceder à identidade gerenciada o acesso ao serviço de pesquisa. O Azure AI Search tem várias funções internas. Você também pode criar uma função personalizada.

A melhor prática é conceder permissões mínimas. Se o aplicativo precisar apenas lidar com consultas, você deverá atribuir a função Leitor de Dados do Índice de Pesquisa. Como alternativa, se for necessário ler e gravar o acesso em um índice de pesquisa, você deve usar a função Colaborador de Dados do Índice de Pesquisa.

  1. Entre no portal do Azure.

  2. Navegue até seu serviço de pesquisa.

  3. Selecione Controle de acesso (IAM) no painel de navegação à esquerda.

  4. Selecione +Adicionar>Adicionar atribuição de função.

    Screenshot of Access control (IAM) page with Add role assignment menu open.

  5. Selecione uma função aplicável:

    • Proprietário
    • Colaborador
    • Leitor
    • Colaborador do Serviço de Pesquisa
    • Colaborador de dados de índice de pesquisa
    • Leitor de dados de índice de pesquisa

    Para obter mais informações sobre as funções disponíveis, confira Funções internas usadas na Pesquisa.

    Observação

    As funções Proprietário, Colaborador, Leitor e Colaborador do Serviço de Pesquisa não fornecem acesso aos dados em um índice de pesquisa. Portanto, você não pode consultar um índice de pesquisa ou os dados de índice usando essas funções. Para acesso a dados em um índice de pesquisa, você precisa da função Colaborador de Dados do Índice de Pesquisa ou Leitor de Dados do Índice de Pesquisa.

  6. Na guia Membros, selecione a identidade gerenciada à qual você deseja conceder acesso ao serviço de pesquisa.

  7. Na guia Examinar + atribuir, selecione Examinar + atribuir para atribuir a função.

Você pode atribuir várias funções, como Colaborador do Serviço de Pesquisa e Colaborador de Dados do Índice de Pesquisa, se o aplicativo precisar de acesso abrangente aos serviços, objetos e conteúdo de pesquisa.

Você também pode atribuir funções usando o PowerShell.

Configurar a autenticação do Microsoft Entra no cliente

Depois de ter uma identidade gerenciada e uma atribuição de função no serviço de pesquisa, você estará pronto para adicionar o código ao aplicativo, para autenticar a entidade de segurança e adquirir um token OAuth 2.0.

Use as seguintes bibliotecas de cliente para o controle de acesso baseado em função:

Observação

Para saber mais sobre o fluxo de concessão do código do OAuth 2.0 usado pelo Microsoft Entra ID, confira Autorizar acesso a aplicativos Web do Microsoft Entra usando o fluxo de concessão do código do OAuth 2.0.

As instruções a seguir fazem referência a um exemplo existente em C# para demonstrar as alterações de código.

  1. Como ponto de partida, clone o código-fonte da seção C# do Início Rápido: pesquisa de texto completo usando os SDKs do Azure.

    No momento, o exemplo usa a autenticação baseada em chave e o AzureKeyCredential para criar o SearchClient e o SearchIndexClient, mas você pode fazer uma pequena alteração para mudar para a autenticação baseada em função.

  2. Atualize o pacote NuGet Azure.Search.Documents para a versão 11.4 ou posterior.

  3. Importe a biblioteca Azure.Identity para obter acesso a outras técnicas de autenticação.

  4. Em vez de usar AzureKeyCredential no início do Main() em Programa.cs, use DefaultAzureCredential como no snippet de código abaixo:

    // Create a SearchIndexClient to send create/delete index commands
SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());
// Create a SearchClient to load and query documents
SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());

Teste local

As identidades gerenciadas atribuídas pelo usuário funcionam apenas nos ambientes do Azure. Se você executar esse código localmente, DefaultAzureCredential retornará à autenticação com as credenciais. Verifique se você também concedeu a si mesmo o acesso necessário ao serviço de pesquisa, caso planeje executar o código localmente.

  1. Verifique se sua conta tem atribuições de função para executar todas as operações no exemplo de início rápido. Para criar e consultar um índice, você precisará de "Leitor de Dados do Índice de Pesquisa" e "Colaborador de Dados do Índice de Pesquisa".

  2. Vá para Ferramentas>Opções>Autenticação de Serviço do Azure para escolher a conta de logon do Azure.

Agora você deve ser capaz de executar o projeto no Visual Studio em seu sistema local, usando o controle de acesso baseado em função para autorização.

Observação

A documentação Azure.Identity tem mais detalhes sobre DefaultAzureCredential e sobre como usar a autenticação do Microsoft Entra com o SDK do Azure para .NET. DefaultAzureCredential destina-se a simplificar a introdução ao SDK, lidando com cenários comuns com comportamentos padrão aceitáveis. Os desenvolvedores que desejam mais controle ou cujo cenário não é abordado nas configurações padrão devem usar outros tipos de credencial.

Confira também