Conectar-se ao Pesquisa de IA do Azure  usando papéis

Observação

Pesquisa de IA do Azure  está disponível por meio do portal Azure, APIs REST e SDKs do Azure. Ele também sustenta o IQ do Foundry, a camada de conhecimento gerenciado que transforma o conteúdo da empresa em bases de conhecimento reutilizáveis e com reconhecimento de permissão para agentes no portal do Microsoft Foundry.

Pesquisa de IA do Azure  dá suporte ao controle de acesso baseado em funções por meio de Microsoft Entra ID. O acesso baseado em função é opcional, mas recomendado. A alternativa é a autenticação baseada em chave, que é o padrão.

Ao atribuir várias funções a um principal de segurança, as permissões são combinadas. As atribuições de função se aplicam em todas as ferramentas e bibliotecas de clientes.

Este artigo descreve como atribuir funções internas para administração do serviço, desenvolvimento e acesso somente leitura para consultas e recuperação de dados. Ele também fornece etapas para criar funções personalizadas e testar atribuições de função.

Dica

Pré-requisitos

Funções incorporadas

As funções são uma coleção de permissões que afetam o plano de controle ou o plano de dados:

  • Plano de controle: Operações de provisionamento, configuração e administração de serviços. As operações do plano de controle incluem a criação ou exclusão de serviços de pesquisa, a listagem de chaves de API e o gerenciamento de configurações de rede e autenticação. Disponível por meio das APIs REST Azure Resource Manager, Search Management REST APIs e bibliotecas de cliente SDK do Azure equivalentes.

  • Plano de dados: refere-se às operações realizadas no ponto de extremidade do serviço de pesquisa. As operações do plano de dados se enquadram em duas categorias: gerenciamento de objetos e acesso ao conteúdo. Disponível por meio das APIs REST do serviço Search e bibliotecas de cliente SDK do Azure equivalentes.

Descrições de função

As funções internas a seguir concedem permissões para Pesquisa de IA do Azure . As funções do plano de controle estão sempre disponíveis, enquanto as funções do plano de dados exigem que o acesso baseado em função seja habilitado em seu serviço de pesquisa. Você pode combinar funções internas para acesso mais amplo ou criar uma função personalizada com as permissões específicas necessárias.

Função Avião Descrição
Proprietário Controle
  • Acesso total ao plano de controle, incluindo a capacidade de atribuir funções e alterar as configurações de autenticação.
  • Os administradores de assinatura têm essa função por padrão.
  • Pode gerenciar chaves de API.
  • Não é possível criar objetos de pesquisa, carregar documentos, consultar índices ou recuperar de bases de dados de conhecimento.
Colaborador Controle
  • Mesmo nível de acesso ao plano de controle que o Proprietário, menos a capacidade de atribuir funções.
Leitor Controle
  • Acesso somente leitura ao plano de controle.
  • Pode exibir métricas de serviço e definições de objeto.
  • Não é possível exibir ou gerenciar chaves de API, carregar documentos, consultar índices ou recuperar de bases de dados de conhecimento.
Colaborador do Serviço de Pesquisa Controle e dados
  • Acesso total ao plano de controle. O acesso ao plano de dados é limitado ao gerenciamento de objetos.
  • Pode criar índices, indexadores, conjuntos de habilidades, bases de dados de conhecimento e outros objetos de pesquisa.
  • Pode recuperar chaves de API administrativas e de consulta por meio de operações do plano de controle.
  • Não é possível carregar documentos, índices de consulta ou recuperar de bases de dados de conhecimento diretamente por meio do acesso baseado em função.
  • Para obter a lista completa de permissões, consulte Microsoft.Search/searchServices/*.
Contribuinte de dados do índice de pesquisa Dados
  • Acesso de leitura e gravação ao conteúdo.
  • Pode carregar documentos, consultar índices e recuperar de bases de dados de conhecimento.
  • Não é possível modificar definições de objeto nem recuperar chaves de administrador.
Leitor de dados de índice de pesquisa Dados
  • Acesso de conteúdo somente leitura.
  • Pode consultar índices e recuperar de bases de conhecimento.
  • Não é possível carregar documentos, modificar definições de objeto ou recuperar chaves de administrador.

Importante

  • As funções Proprietário, Colaborador e Colaborador do Serviço de Pesquisa podem recuperar chaves de administrador, que concedem acesso completo de leitura e gravação ao plano de dados. Conceda apenas essas funções a usuários confiáveis.
  • Por padrão, as funções do plano de dados se aplicam a todos os índices no serviço de pesquisa. Para definir o escopo do Colaborador de Dados do Índice de Pesquisa ou do Leitor de Dados de Índice de Pesquisa para um único índice, consulte Conceder acesso a um único índice.

Resumo das permissões

Use a tabela a seguir para localizar rapidamente qual função fornece as permissões necessárias.

Permissões Proprietário/Colaborador Leitor Colaborador do Serviço de Pesquisa Colaborador de dados de índice de pesquisa Leitor de dados de índice de pesquisa
Criar e configurar serviços de Pesquisa de IA do Azure  ✅ ❌ ✅ ❌ ❌
Acessar o serviço no portal do Azure ✅ ✅ ✅ ❌ ❌
Exibir propriedades de serviço, métricas e ponto de extremidade ✅ ✅ ✅ ❌ ❌
Listar todos os objetos no serviço ✅ ✅ ✅ ❌ ❌
Cotas de acesso e estatísticas de serviço ✅ ❌ ✅ ❌ ❌
Exibir, copiar e regenerar chaves ✅ ❌ ✅ ❌ ❌
Definir opções de autenticação ✅ ❌ ✅ ❌ ❌
Exibir funções, políticas e definições ✅ ✅ ✅ ❌ ❌
Configurar a segurança de rede e conexões privadas ✅ ❌ ✅ ❌ ❌
Criar, executar e gerenciar objetos de pesquisa 1 ❌ ❌ ✅ ❌ ❌
Carregar dados para indexação 2 ❌ ❌ ❌ ✅ ❌
Consultar um índice ❌ ❌ ❌ ✅ ✅
Recuperar de uma base de conhecimento ❌ ❌ ❌ ✅ ✅
Ignorar filtros de permissão com leitura elevada (versão prévia) ❌ ❌ ❌ ✅ ❌

1 Inclui índices, indexadores, fontes de dados, conjuntos de habilidades, aliases, mapas de sinônimos, sessões de depuração, bases de dados de conhecimento e fontes de conhecimento. Os indexadores também dão suporte a operações de execução e redefinição.

2 Um Proprietário ou Colaborador pode executar o assistente de importação de dados para criar e carregar índices, mesmo que eles não possam carregar documentos em outros clientes. Da mesma forma, os indexadores podem escrever em qualquer índice no serviço de pesquisa, independentemente das atribuições de funções específicas por índice. Em ambos os casos, o serviço de pesquisa (não o usuário) executa as ações do plano de dados usando suas permissões de Microsoft.Search/searchServices/indexes/documents/*.

Atribuir papéis predefinidos

Nesta seção, você atribui funções para:

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

As funções a seguir permitem que você crie, configure e gerencie um serviço de pesquisa. Essas funções são hierárquicas, portanto, selecione uma com base no nível de acesso necessário.

Função ID
Proprietário 8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Colaborador b24988ac-6180-42a0-ab88-20f7382dd24c
Leitor acdd72a7-3385-48ef-bd42-f606fba81ae7

  1. Acesse o serviço de pesquisa no Azure portal.

  2. No painel esquerdo, selecione Access control (IAM).

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

    Captura de tela da página do gerenciamento de acesso (IAM) para atribuir funções administrativas de serviços.

  4. Selecione uma função: Proprietário, Colaborador ou Leitor.

  5. Na guia Members, selecione a Microsoft Entra identidade do usuário ou do grupo. Se você estiver configurando permissões para outro serviço Azure, selecione uma identidade gerenciada atribuída pelo sistema ou atribuída pelo usuário.

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

Atribuir funções para desenvolvimento

As funções a seguir permitem criar objetos de pesquisa, carregar documentos, consultar índices e recuperar de bases de dados de conhecimento. Atribua todas as três funções para abranger toda a gama de tarefas de desenvolvimento.

Função ID
Colaborador do Serviço de Pesquisa 7ca78c08-252a-4471-8644-bb5ff32d4ba0
Contribuinte de dados do índice de pesquisa 8ebe5a00-799e-43f5-93ac-243d3dce84a7
Leitor de dados de índice de pesquisa 1407120a-92aa-4202-b7e9-c0e197c71c8f

  1. Acesse o serviço de pesquisa no Azure portal.

  2. No painel esquerdo, selecione Access control (IAM).

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

    Captura de tela da página controle de acesso (IAM) para atribuir funções de desenvolvimento.

  4. Selecione Colaborador do Serviço de Pesquisa.

  5. Na guia Members, selecione a Microsoft Entra identidade do usuário ou do grupo. Se você estiver configurando permissões para outro serviço Azure, selecione uma identidade gerenciada atribuída pelo sistema ou atribuída pelo usuário.

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

  7. Repita estas etapas para atribuir o Colaborador de Dados do Índice de Pesquisa e o Leitor de Dados do Índice de Pesquisa.

Atribuir funções para acesso somente leitura

Use a função a seguir para aplicativos e processos que só precisam de acesso de leitura a índices e bases de dados de conhecimento. As operações com suporte incluem pesquisa, pesquisa, preenchimento automático e sugestões de índices e recuperação para bases de dados de conhecimento.

Função ID
Leitor de dados de índice de pesquisa 1407120a-92aa-4202-b7e9-c0e197c71c8f

  1. Acesse o serviço de pesquisa no Azure portal.

  2. No painel esquerdo, selecione Access control (IAM).

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

    Captura de tela da página de controle de acesso (IAM) para atribuir funções de acesso somente leitura a dados.

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

  5. Na guia Members, selecione a Microsoft Entra identidade do usuário ou do grupo. Se você estiver configurando permissões para outro serviço Azure, selecione uma identidade gerenciada atribuída pelo sistema ou atribuída pelo usuário.

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

Testar atribuições de função

Use um cliente para testar atribuições de função. Lembre-se de que as funções são cumulativas. Você não pode excluir ou negar funções herdadas que estão delimitadas para o nível de assinatura ou grupo de recursos no nível do recurso (como um serviço de busca).

Antes de continuar, configure seu aplicativo para conexões sem chave e tenha atribuições de função em vigor.

  1. Acesse o serviço de pesquisa no Azure portal.

  2. No painel esquerdo, selecione gerenciamento de pesquisa>Índices para testar permissões relacionadas ao índice:

    • Os Colaboradores do Serviço de Pesquisa podem criar, modificar e excluir objetos de pesquisa, mas não podem carregar documentos ou executar consultas. Para verificar as permissões, crie um índice de pesquisa.

    • Os Colaboradores de Dados de Índice de Pesquisa podem carregar documentos. Não há nenhuma opção de carregar documentos no portal de Azure fora do Import data wizard, mas você pode reset e executar um indexador para confirmar as permissões de carregamento do documento.

    • Os Leitores de Dados do Índice de Pesquisa podem consultar índices. Para verificar as permissões, use Gerenciador de Pesquisa. Você deve ser capaz de enviar consultas e exibir resultados, mas não deve ser capaz de exibir definições de índice ou criar índices.

Conceder acesso a apenas um índice

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

Atualmente, o portal Azure não dá suporte a atribuições de função no nível do índice. Use o CLI do Azure, o PowerShell ou a API REST para atribuir funções com escopo a um único índice.

Operações de indexador e escopo por índice

As atribuições de função por índice se aplicam somente a operações diretas de API, como consultas ou uploads de documentos de usuários ou aplicativos. Os indexadores não são restritos por permissões por índice porque operam com credenciais de nível de serviço.

Um usuário com a função Colaborador do Serviço de Pesquisa pode criar indexadores que gravam em qualquer índice no serviço de pesquisa, mesmo índices em que esse usuário não tem atribuição de função por índice.

Para o isolamento estrito de dados entre índices, considere estas abordagens:

  • Use serviços de pesquisa separados para equipes ou usuários que exigem isolamento no nível do índice.
  • Atribua o Colaborador do Serviço de Pesquisa somente aos administradores que gerenciam indexadores.
  • Use o controle de acesso no nível do documento com filtros de segurança para restringir os resultados da consulta em um índice compartilhado.

Criar uma função personalizada

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

Os exemplos a seguir clonam o Leitor de Dados do Índice de Pesquisa e, em seguida, adicionam a capacidade de listar índices por nome. Normalmente, listar os índices em um serviço de pesquisa é considerado um direito administrativo.

  1. Entre no portal Azure e navegue até o serviço de pesquisa.

  2. No painel esquerdo, selecione Access control (IAM).

  3. Na guia Funções, localize Leitor de Dados do Índice de Pesquisa (ou outra função), clique nas reticências (...) e selecione Clonar.

  4. Na guia Basics, insira um nome para a função personalizada, como "Pesquisar Índice Data Explorer", e selecione Next.

  5. Na guia Permissões , selecione Adicionar permissões.

  6. No painel Adicionar permissões, selecione o bloco Pesquisa da Microsoft.

  7. Com ações selecionadas na parte superior, defina as seguintes permissões:

    • Em Microsoft.Search/operations, selecione Read: Listar todas as operações disponíveis.
    • Em Microsoft.Search/searchServices/indexes, selecione Ler: Ler Índice.

  8. Alterne para Ações de Dados na parte superior e, em seguida, em Microsoft.Search/searchServices/indexes/documents, selecione Ler: Ler Documentos.

    A definição JSON se parece com o seguinte exemplo:

    {
    "properties": {
        "roleName": "Search Index Data Explorer",
        "description": "List all indexes on the service and query them.",
        "assignableScopes": [
            "/subscriptions/<subscription>/resourceGroups/<resource-group>"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Search/operations/read",
                    "Microsoft.Search/searchServices/indexes/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.Search/searchServices/indexes/documents/read"
                ],
                "notDataActions": []
            }
        ]
    }
}

  9. Selecione Adicionar para fechar o painel.

  10. Selecione Revisar + criar para criar o papel.

    Agora você pode atribuir usuários e grupos à função. Para obter mais informações sobre essas etapas, consulte Criar ou atualizar Azure funções personalizadas usando o portal Azure.

Criar uma política de Acesso Condicional

Se for necessário aplicar políticas organizacionais, como autenticação multifator, utilize o Acesso Condicional do Microsoft Entra.

Para criar uma política de Acesso Condicional para Pesquisa de IA do Azure :

  1. Entre no portal Azure.

  2. Pesquise Acesso Condicional do Microsoft Entra.

  3. Na página Visão geral , selecione Criar nova política.

  4. Em Acionamentos ou ações doCloud, adicione Pesquisa de IA do Azure  como um aplicativo de nuvem, dependendo de como você deseja configurar sua política.

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

  6. Salve a política.

Importante

Se o serviço de pesquisa tiver uma identidade gerenciada atribuída a ele, o serviço de pesquisa específico aparecerá como um aplicativo de nuvem. No entanto, selecionar esse serviço de pesquisa específico não impõe a política. Em vez disso, selecione o aplicativo de nuvem Pesquisa de IA do Azure  geral para aplicar políticas de Acesso Condicional ao serviço de pesquisa.

Solução de problemas

Ao desenvolver aplicativos que usam controle de acesso baseado em função para autenticação, você pode encontrar alguns problemas comuns:

  • A configuração padrão de um serviço de pesquisa é autenticação baseada em chave. Se você não alterar essa configuraçã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.

  • Se sua solicitação incluir uma chave de API junto com credenciais baseadas em função, o serviço será autenticado usando a chave. Remova a chave de API dos cabeçalhos de solicitação para usar a autenticação baseada em função.

  • Se o token de autorização vem de uma identidade gerenciada e você recentemente atribuiu as permissões apropriadas, pode levar várias horas para que as atribuições de permissões entrem em vigor.

  • Se as consultas com permissões no nível do documento não retornarem os resultados esperados, use o Colaborador de Dados do Índice de Pesquisa ou crie uma função personalizada com permissões elevadas (versão prévia) para investigar.

Próxima etapa

Este artigo explica como atribuir funções para operações de controle e plano de dados em Pesquisa de IA do Azure . Para obter instruções abrangentes sobre como adicionar acesso baseado em função ao código do aplicativo:

Conecte seu aplicativo para Pesquisa de IA do Azure  usando identidades

  • Last updated on