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

  • Artigo

Os aplicativos de pesquisa criados na Pesquisa de IA do Azure 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 suas credenciais e chaves de API não precisam mais ser armazenadas em seu código. O Microsoft Entra autentica a entidade de segurança (um usuário, grupo ou serviço) que executa o aplicativo. Se a autenticação for bem-sucedida, a ID do Microsoft Entra retornará o token de acesso ao aplicativo e o aplicativo poderá usar o token de acesso para autorizar solicitações ao Azure AI Search.

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

  • Para autenticação, crie uma identidade gerenciada para seu aplicativo. Você pode usar um tipo diferente de objeto principal de segurança, mas este artigo usa identidades gerenciadas porque elas eliminam a necessidade de gerenciar credenciais.

  • Para autorização, atribua 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 com o novo SearchClient(endpoint, new DefaultAzureCredential()) para autenticar por meio de uma ID do Microsoft Entra usando Azure.Identity.

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

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

Nesta etapa, configure seu serviço de pesquisa para reconhecer um cabeçalho 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 Teclas no painel de navegação esquerdo.

    Captura de ecrã da página de chaves com opções de autenticação.

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

    Opção Description
    Chave de API (padrão) Requer um administrador ou chaves de API de consulta no cabeçalho da solicitação de autorização. Nenhuma função é usada.
    Controlo de acesso baseado em funções Requer associação a 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 usando uma chave de API ou um controle de acesso baseado em função.

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

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

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

Criar uma identidade gerenciada

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

  1. Inicie sessão no portal do Azure.

  2. Pesquise identidades gerenciadas.

  3. Selecione Criar.

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

    Captura de ecrã do assistente Criar Identidade Gerida.

Atribuir uma função à identidade gerenciada

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

É uma prática recomendada conceder permissões mínimas. Se seu aplicativo só precisa lidar com consultas, você deve atribuir a função de Leitor de Dados de Índice de Pesquisa . Como alternativa, se o cliente precisar de acesso de leitura e gravação em um índice de pesquisa, você deverá usar a função Colaborador de Dados do Índice de Pesquisa .

  1. Inicie sessão no portal do Azure.

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

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

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

    Captura de ecrã da página Controlo de acesso (IAM) com o menu Adicionar atribuição de função aberto.

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

    • Proprietário

    • Contribuinte

    • Leitor

    • Colaborador do Serviço de Pesquisa

    • Contribuidor de dados do índice de pesquisa

    • Leitor de dados de índice de pesquisa

      Nota

      O Proprietário, o Colaborador, o Leitor e o Colaborador do Serviço de Pesquisa são funções do plano de controle e não lhe dão acesso aos dados dentro de um índice de pesquisa. Para acesso a dados, escolha a função Contribuidor de Dados de Índice de Pesquisa ou Leitor de Dados de Índice de Pesquisa. Para obter mais informações sobre o escopo e a finalidade de cada função, consulte Funções internas usadas na Pesquisa.

  6. Na guia Membros, selecione a identidade gerenciada que você deseja dar acesso ao seu serviço de pesquisa.

  7. No separador Rever + atribuir, selecione Rever + 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 seu 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 seu cliente

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

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

Nota

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

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

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

    O exemplo atualmente usa a autenticação baseada em chave e o AzureKeyCredential para criar o SearchClient e SearchIndexClient mas você pode fazer uma pequena alteração para alternar 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 Program.cs, use DefaultAzureCredential como no trecho de Main() 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());

Testes locais

As identidades gerenciadas atribuídas pelo usuário funcionam somente em ambientes do Azure. Se você executar esse código localmente, DefaultAzureCredential voltará à autenticação com suas credenciais. Certifique-se de dar a si mesmo o acesso necessário ao serviço de pesquisa se você planeja 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, use "Search Index Data Reader" e "Search Index Data Contributor".

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

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

Nota

A documentação do Azure.Identity tem mais detalhes sobre DefaultAzureCredential e 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 manipulando cenários comuns com comportamentos padrão razoáveis. Os desenvolvedores que desejam mais controle ou cujo cenário não é atendido pelas configurações padrão devem usar outros tipos de credenciais.

Consulte também