Partilhar via

Conectar-se à Pesquisa de IA do Azure usando controles de acesso baseados em função

  • Artigo

O Azure fornece um sistema global de autorização de controle de acesso baseado em função para todos os serviços em execução na plataforma. No Azure AI Search, você pode atribuir funções do Azure para:

O acesso por usuário nos resultados da pesquisa (às vezes chamado de segurança em nível de linha ou segurança em nível de documento) não é suportado por meio de atribuições de função. Como solução alternativa, crie filtros de segurança que cortam os resultados por identidade do usuário, removendo documentos aos quais o solicitante não deve ter acesso. Veja este exemplo de bate-papo corporativo usando o RAG para obter uma demonstração.

As atribuições de função são cumulativas e generalizadas em todas as ferramentas e bibliotecas de clientes. Você pode atribuir funções usando qualquer uma das abordagens com suporte descritas na documentação de controle de acesso baseado em função do Azure.

O acesso baseado em função é opcional, mas recomendado. A alternativa é a autenticação baseada em chave, que é o padrão.

Pré-requisitos

Limitações

  • O controle de acesso baseado em função pode aumentar a latência de algumas solicitações. Cada combinação exclusiva de recurso de serviço (índice, indexador, etc.) e entidade de serviço aciona uma verificação de autorização. Essas verificações de autorização podem adicionar até 200 milissegundos de latência por solicitação.

  • Em casos raros em que as solicitações se originam de um grande número de entidades de serviço diferentes, todas direcionadas a recursos de serviço diferentes (índices, indexadores, etc.), é possível que as verificações de autorização resultem em limitação. A limitação só aconteceria se centenas de combinações exclusivas de recurso de serviço de pesquisa e entidade de serviço fossem usadas em um segundo.

Habilitar o acesso baseado em função para operações de plano de dados

As funções para administração de serviço (plano de controle) são obrigatórias. As funções para operações de plano de dados são opcionais. Você deve habilitar o acesso baseado em função antes de atribuir funções de Colaborador do Serviço de Pesquisa, Colaborador de Dados do Índice de Pesquisa ou Leitor de Dados do Índice de Pesquisa para operações de dados.

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

O plano de dados refere-se a operações no ponto de extremidade do serviço de pesquisa, como indexação ou consultas, ou qualquer outra operação especificada na API REST de Pesquisa ou bibliotecas de cliente equivalentes.

  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 Controle baseado em função ou Ambos se quiser flexibilidade.

    Opção Description
    Chave de API (padrão). Requer chaves de API no cabeçalho da solicitação para autorização.
    Controlo de acesso baseado em funções Requer associação a uma atribuição de função para concluir a tarefa. Também requer um cabeçalho de autorização na solicitação.
    Ambos As solicitações são válidas usando uma chave de API ou um controle de acesso baseado em função, mas se você fornecer ambos na mesma solicitação, a chave de API será usada.

A alteração entra em vigor imediatamente, mas aguarde alguns segundos antes de atribuir funções.

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

As funções a seguir são incorporadas. Se essas funções forem insuficientes, crie uma função personalizada.

Role Avião Description
Proprietário Controlo & Dados Acesso total ao plano de controle do recurso de pesquisa, incluindo a capacidade de atribuir funções do Azure. Somente a função Proprietário pode habilitar ou desabilitar opções de autenticação ou gerenciar funções para outros usuários. Os administradores de subscrição são membros por predefinição.

No plano de dados, essa função tem o mesmo acesso que a função de Colaborador do Serviço de Pesquisa. Inclui acesso a todas as ações do plano de dados, exceto a capacidade de consultar ou indexar documentos.
Contribuinte Controlo & Dados Mesmo nível de acesso ao plano de controle que o proprietário, menos a capacidade de atribuir funções ou alterar opções de autenticação.

No plano de dados, essa função tem o mesmo acesso que a função de Colaborador do Serviço de Pesquisa. Inclui acesso a todas as ações do plano de dados, exceto a capacidade de consultar ou indexar documentos.
Leitor Controlo & Dados Acesso de leitura em todo o serviço, incluindo métricas de pesquisa, métricas de conteúdo (armazenamento consumido, número de objetos) e as definições de objeto de recursos do plano de dados (índices, indexadores e assim por diante). No entanto, ele não pode ler chaves de API ou ler conteúdo dentro de índices.
Colaborador do Serviço de Pesquisa Controlo & Dados Acesso de leitura-gravação a definições de objeto (índices, aliases, mapas de sinônimos, indexadores, fontes de dados e conjuntos de habilidades). Essa função é para desenvolvedores que criam objetos e para administradores que gerenciam um serviço de pesquisa e seus objetos, mas sem acesso ao conteúdo de índice. Use essa função para criar, excluir e listar índices, obter definições de índice, obter informações de serviço (estatísticas e cotas), testar analisadores, criar e gerenciar mapas de sinônimos, indexadores, fontes de dados e conjuntos de habilidades. Consulte Microsoft.Search/searchServices/* a lista de permissões.
Contribuidor de dados do índice de pesquisa Dados Acesso de leitura-gravação ao conteúdo em índices. Essa função é para desenvolvedores ou proprietários de índice que precisam importar, atualizar ou consultar a coleção de documentos de um índice. Esta função não suporta a criação ou gestão de índices. Por padrão, essa função é para todos os índices em um serviço de pesquisa. Consulte Conceder acesso a um único índice para restringir o escopo.
Leitor de dados de índice de pesquisa Dados Acesso somente leitura para consultar índices de pesquisa. Essa função é para aplicativos e usuários que executam consultas. Esta função não suporta acesso de leitura a definições de objeto. Por exemplo, não é possível ler uma definição de índice de pesquisa ou obter estatísticas do serviço de pesquisa. Por padrão, essa função é para todos os índices em um serviço de pesquisa. Consulte Conceder acesso a um único índice para restringir o escopo.

Nota

Se você desabilitar o acesso baseado em função do Azure, as funções internas para o plano de controle (Proprietário, Colaborador, Leitor) continuarão disponíveis. A desativação do acesso baseado em função remove apenas as permissões relacionadas a dados associadas a essas funções. Se as funções do plano de dados estiverem desabilitadas, o Colaborador do Serviço de Pesquisa será equivalente ao Colaborador do plano de controle.

Atribuir funções

Nesta seção, atribua funções para:

Atribuir funções para administração de serviços

Como administrador de serviço, você pode criar e configurar um serviço de pesquisa e executar todas as operações do plano de controle descritas na API REST de gerenciamento ou bibliotecas de cliente equivalentes. Dependendo da função, você também pode executar a maioria das tarefas da API REST de pesquisa do plano de dados.

  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.

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

    • Proprietário (acesso total a todas as operações do plano de dados e do plano de controle, exceto permissões de consulta)
    • Colaborador (o mesmo que Proprietário, exceto para permissões para atribuir funções)
    • Leitor (aceitável para monitoramento e visualização de métricas)

  6. Na guia Membros, selecione a identidade do usuário ou grupo do Microsoft Entra.

  7. No separador Rever + atribuir, selecione Rever + atribuir para atribuir a função.

Atribuir funções para desenvolvimento

As atribuições de função são globais em todo o serviço de pesquisa. Para definir o escopo de permissões para um único índice, use o PowerShell ou a CLI do Azure para criar uma função personalizada.

Importante

Se você configurar o acesso baseado em função para um serviço ou índice e também fornecer uma chave de API na solicitação, o serviço de pesquisa usará a chave de API para autenticar.

  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.

    Página de controle de acesso (IAM) com o menu Adicionar atribuição de função aberto.

  5. Selecione uma função:

    • Colaborador do Serviço de Pesquisa (operações create-read-update-delete em índices, indexadores, conjuntos de habilidades e outros objetos de nível superior)
    • Search Index Data Contributor (carregar documentos e executar trabalhos de indexação)
    • Leitor de dados de índice de pesquisa (consultar um índice)

    Outra combinação de funções que fornece acesso total é Colaborador ou Proprietário, além de Leitor de Dados de Índice de Pesquisa.

  6. Na guia Membros, selecione a identidade do usuário ou grupo do Microsoft Entra.

  7. No separador Rever + atribuir, selecione Rever + atribuir para atribuir a função.

  8. Repita para as outras funções. A maioria dos desenvolvedores precisa dos três.

Atribuir funções para consultas somente leitura

Use a função Leitor de Dados de Índice de Pesquisa para aplicativos e processos que só precisam de acesso de leitura a um índice. Trata-se de um papel muito específico. Ele concede acesso GET ou POST à coleção de documentos de um índice de pesquisa para pesquisa, preenchimento automático e sugestões.

Ele não suporta operações GET ou LIST em um índice ou outros objetos de nível superior, ou estatísticas de serviço GET.

  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.

  5. Selecione a função Leitor de Dados de Índice de Pesquisa .

  6. Na guia Membros, selecione a identidade do usuário ou grupo do Microsoft Entra. Se estiver a configurar permissões para outro serviço, poderá estar a utilizar um sistema ou uma identidade gerida pelo utilizador. Escolha essa opção se a atribuição de função for para uma identidade de serviço.

  7. No separador Rever + atribuir, selecione Rever + atribuir para atribuir a função.

Atribuições de função de teste

Use um cliente para testar atribuições de função. Lembre-se de que as funções são cumulativas e herdadas com escopo para o nível de assinatura ou grupo de recursos não podem ser excluídas ou negadas no nível de recurso (serviço de pesquisa).

Certifique-se de registrar seu aplicativo cliente com o Microsoft Entra ID e ter atribuições de função antes de testar o acesso.

  1. Inicie sessão no portal do Azure.

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

  3. Na página Visão geral, selecione a guia Índices :

    • Os Colaboradores do Serviço de Pesquisa podem exibir e criar qualquer objeto, mas não podem carregar documentos ou consultar um índice. Para verificar as permissões, crie um índice de pesquisa.

    • Os contribuidores de dados do índice de pesquisa podem carregar documentos. Não há nenhuma opção de carregamento de documentos no portal fora do assistente Importar dados, mas você pode redefinir e executar um indexador para confirmar as permissões de carregamento de documentos.

    • Os leitores de dados do índice de pesquisa podem consultar o índice. Para verificar as permissões, use o Gerenciador de pesquisa. Você deve ser capaz de enviar consultas e exibir resultados, mas não deve ser capaz de visualizar a definição de índice ou criar uma.

Testar como usuário atual

Se já for um Colaborador ou Proprietário do seu serviço de pesquisa, pode apresentar um token de portador para a sua identidade de utilizador para autenticação no Azure AI Search.

  1. Obtenha um token de portador para o usuário atual usando a CLI do Azure:

    az account get-access-token --scope https://search.azure.com/.default

    Ou usando o PowerShell:

    Get-AzAccessToken -ResourceUrl https://search.azure.com

  2. Em um novo arquivo de texto no Visual Studio Code, cole estas variáveis:

    @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
@index-name = PASTE-YOUR-INDEX-NAME-HERE
@token = PASTE-YOUR-TOKEN-HERE

  3. Cole e envie uma solicitação para confirmar o acesso. Aqui está um que consulta o índice de início rápido de hotéis

    POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2023-11-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

    {
         "queryType": "simple",
         "search": "motel",
         "filter": "",
         "select": "HotelName,Description,Category,Tags",
         "count": true
     }

Conceder acesso a um único índice

Em alguns cenários, talvez você queira limitar o acesso de um aplicativo a um único recurso, como um índice.

Atualmente, o portal não oferece suporte a atribuições de função nesse nível de granularidade, mas pode ser feito com o PowerShell ou a CLI do Azure.

No PowerShell, use New-AzRoleAssignment, fornecendo o nome de usuário ou grupo do Azure e o escopo da atribuição.

  1. Carregue os Azure módulos e e conecte-se AzureAD à sua conta do Azure:

    Import-Module -Name Az
Import-Module -Name AzureAD
Connect-AzAccount

  2. Adicione uma atribuição de função com escopo a um índice individual:

    New-AzRoleAssignment -ObjectId <objectId> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

Criar uma função personalizada

Se as funções internas não fornecerem a combinação correta de permissões, você poderá criar uma função personalizada para dar suporte às operações necessárias.

Este exemplo clona o Search Index Data Reader e, em seguida, adiciona a capacidade de listar índices por nome. Normalmente, a listagem dos índices num serviço de pesquisa é considerada um direito administrativo.

Essas etapas são derivadas de Criar ou atualizar funções personalizadas do Azure usando o portal do Azure. A clonagem de uma função existente é suportada em uma página de serviço de pesquisa.

Estas etapas criam uma função personalizada que aumenta os direitos de consulta de pesquisa para incluir índices de listagem por nome. Normalmente, listar índices é considerado uma função de administração.

  1. No portal do Azure, navegue até o serviço de pesquisa.

  2. No painel de navegação esquerdo, selecione Controle de acesso (IAM).

  3. Na barra de ações, selecione Funções.

  4. Clique com o botão direito do mouse em Leitor de Dados de Índice de Pesquisa (ou outra função) e selecione Clonar para abrir o assistente Criar uma função personalizada.

  5. Na guia Noções básicas, forneça um nome para a função personalizada, como "Search Index Data Explorer" e selecione Avançar.

  6. Na guia Permissões, selecione Adicionar permissão.

  7. Na guia Adicionar permissões, procure e selecione o bloco Pesquisa da Microsoft.

  8. Defina as permissões para sua função personalizada. Na parte superior da página, usando a seleção padrão Ações :

    • Em Microsoft.Search/operations, selecione Read : List all available operations.
    • Em Microsoft.Search/searchServices/indexes, selecione Ler : Ler Índice.

  9. Na mesma página, alterne para Ações de dados e, em Microsoft.Search/searchServices/indexes/documents, selecione Ler: Ler documentos.

    A definição JSON se parece com o exemplo a seguir:

    {
 "properties": {
     "roleName": "search index data explorer",
     "description": "",
     "assignableScopes": [
         "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
     ],
     "permissions": [
         {
             "actions": [
                 "Microsoft.Search/operations/read",
                 "Microsoft.Search/searchServices/indexes/read"
             ],
             "notActions": [],
             "dataActions": [
                 "Microsoft.Search/searchServices/indexes/documents/read"
             ],
             "notDataActions": []
         }
     ]
   }
 }

  10. Selecione Rever + criar para criar a função. Agora você pode atribuir usuários e grupos à função.

Desativar autenticação de chave de API

O acesso à chave, ou autenticação local, pode ser desabilitado em seu serviço se você estiver usando as funções internas e a autenticação do Microsoft Entra. A desativação de chaves de API faz com que o serviço de pesquisa recuse todas as solicitações relacionadas a dados que passam uma chave de API no cabeçalho.

Nota

As chaves da API de administração só podem ser desativadas, não excluídas. As chaves da API de consulta podem ser excluídas.

As permissões de Proprietário ou Colaborador são necessárias para desativar os recursos.

Para desabilitar a autenticação baseada em chave, use o portal do Azure ou a API REST de gerenciamento.

  1. No portal do Azure, navegue até o serviço de pesquisa.

  2. No painel de navegação esquerdo, selecione Chaves.

  3. Selecione Controle de acesso baseado em função.

A alteração entra em vigor imediatamente, mas aguarde alguns segundos antes do teste. Supondo que você tenha permissão para atribuir funções como membro de Proprietário, administrador de serviço ou coadministrador, você pode usar os recursos do portal para testar o acesso baseado em função.

Acesso Condicional

Recomendamos o Acesso Condicional do Microsoft Entra se você precisar impor políticas organizacionais, como a autenticação multifator.

Para habilitar uma política de Acesso Condicional para o Azure AI Search, siga estas etapas:

  1. Inicie sessão no portal do Azure.

  2. Procure acesso condicional do Microsoft Entra.

  3. Selecione Políticas.

  4. Selecione Nova política.

  5. Na seção Aplicativos ou ações na nuvem da política, adicione o Azure AI Search como um aplicativo na nuvem, dependendo de como você deseja configurar sua política.

  6. Atualize os parâmetros restantes da política. Por exemplo, especifique a quais usuários e grupos essa política se aplica.

  7. Guardar a política.

Importante

Se o seu serviço de pesquisa tiver uma identidade gerenciada atribuída a ele, o serviço de pesquisa específico aparecerá como um aplicativo na nuvem que pode ser incluído ou excluído como parte da política de Acesso Condicional. As políticas de Acesso Condicional não podem ser aplicadas a um serviço de pesquisa específico. Em vez disso, certifique-se de selecionar o aplicativo de nuvem geral do Azure AI Search .

Solução de problemas de controle de acesso baseado em função

Ao desenvolver aplicativos que usam controle de acesso baseado em função para autenticação, alguns problemas comuns podem ocorrer:

  • Se o token de autorização veio de uma identidade gerenciada e as permissões apropriadas foram atribuídas recentemente, pode levar várias horas para que essas atribuições de permissões entrem em vigor.

  • A configuração padrão para um serviço de pesquisa é a autenticação baseada em chave. Se você não alterou a configuração de chave padrão para Ambos ou Controle de acesso baseado em função, todas as solicitações que usam autenticação baseada em função serão negadas automaticamente, independentemente das permissões subjacentes.