Ligar a Azure Cognitive Search com o controlo de acesso baseado em funções do Azure (RBAC do Azure)

O Azure fornece um sistema de autorização de controlo de acesso baseado em funções global para todos os serviços em execução na plataforma. Na Pesquisa Cognitiva, pode:

  • Utilize funções geralmente disponíveis para administração de serviços.

  • Utilize novas funções de pré-visualização para pedidos de dados, incluindo criar, carregar e consultar índices.

O acesso por utilizador através dos resultados da pesquisa (por vezes referido como segurança ao nível da linha ou segurança ao nível do documento) não é suportado. Como solução, crie filtros de segurança que reduzam os resultados por identidade de utilizador, removendo documentos para os quais o requerente não deve ter acesso.

As funções incorporadas incluem funções de pré-visualização e disponibilidade geral. Se estas funções forem insuficientes, crie uma função personalizada .

Função Descrição e disponibilidade
Proprietário (Disponível em geral) Acesso total ao recurso de pesquisa, incluindo a capacidade de atribuir funções do Azure. Os administradores de subscrições são membros por predefinição.

(Pré-visualização) Esta função tem o mesmo acesso que a função Contribuidor do Serviço de Pesquisa no plano de dados. Inclui acesso a todas as ações do plano de dados, exceto a capacidade de consultar o índice de pesquisa ou indexar documentos.
Contribuinte (Disponível em geral) O mesmo nível de acesso que Proprietário, menos a capacidade de atribuir funções ou alterar as opções de autorização.

(Pré-visualização) Esta função tem o mesmo acesso que a função Contribuidor do Serviço de Pesquisa no plano de dados. Inclui acesso a todas as ações do plano de dados, exceto a capacidade de consultar o índice de pesquisa ou indexar documentos.
Leitor (Disponível em geral) Acesso limitado a informações de serviço parciais. No portal, a função Leitor pode aceder às informações na página Descrição Geral do serviço, na secção Essentials e no separador Monitorização. Todos os outros separadores e páginas estão fora dos limites.

Esta função tem acesso às informações do serviço: nome do serviço, grupo de recursos, estado do serviço, localização, nome da subscrição e ID, etiquetas, URL, escalão de preço, réplicas, partições e unidades de pesquisa. Esta função também tem acesso às métricas do serviço: latência de pesquisa, percentagem de pedidos limitados, consultas médias por segundo.

Esta função não permite o acesso a chaves de API, atribuições de funções, conteúdo (índices ou mapas de sinónimos) ou métricas de conteúdo (armazenamento consumido, número de objetos).

(Pré-visualização) Quando ativa a pré-visualização do RBAC para o plano de dados, a função Leitor tem acesso de leitura em todo o serviço. Isto permite-lhe ler métricas de pesquisa, métricas de conteúdo (armazenamento consumido, número de objetos) e as definições de recursos do plano de dados (índices, indexadores, etc.). A função Leitor ainda não terá acesso a chaves de API de leitura ou a conteúdos de leitura nos índices.
Contribuidor do Serviço de Pesquisa (Disponível em geral) Esta função é idêntica à função Contribuidor e aplica-se às operações do plano de controlo.

(Pré-visualização) Quando ativa a pré-visualização do RBAC para o plano de dados, esta função também fornece acesso total a todas as ações do plano de dados em índices, mapas de sinónimos, indexadores, origens de dados e conjuntos de competências, conforme definido pelo Microsoft.Search/searchServices/*. Esta função não lhe dá acesso a índices de pesquisa de consultas ou a documentos de índice. Esta função destina-se a administradores de serviços de pesquisa que precisam de gerir o serviço de pesquisa e os respetivos objetos, mas sem a capacidade de ver ou aceder a dados de objetos.

Tal como Contribuidor, os membros desta função não podem efetuar ou gerir atribuições de funções ou alterar as opções de autorização. Para utilizar as capacidades de pré-visualização desta função, o seu serviço tem de ter a funcionalidade de pré-visualização ativada, conforme descrito neste artigo.
Contribuidor de Dados do Índice de Pesquisa (Pré-visualização) Fornece acesso total ao plano de dados aos conteúdos em todos os índices no serviço de pesquisa. Esta função destina-se a programadores ou proprietários de índices que precisam de importar, atualizar ou consultar a coleção de documentos de um índice.
Leitor de Dados do Índice de Pesquisa (Pré-visualização) Fornece acesso de plano de dados só de leitura aos índices de pesquisa no serviço de pesquisa. Esta função destina-se a aplicações e utilizadores que executam consultas.

Nota

Os recursos do Azure têm o conceito de categorias de plano de controlo e plano de dados de operações. No Cognitive Search, "plano de controlo" refere-se a qualquer operação suportada na API REST de Gestão ou bibliotecas de cliente equivalentes. O "plano de dados" refere-se a operações no ponto final 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.

Capacidades e limitações de pré-visualização

  • O controlo de acesso baseado em funções para operações do plano de dados, como criar um índice ou consultar um índice, está atualmente em pré-visualização pública e disponível em termos suplementares de utilização.

  • Não existem restrições regionais, de escalão ou de preços para utilizar a pré-visualização do RBAC do Azure, mas o serviço de pesquisa tem de estar na cloud pública do Azure. A pré-visualização não está disponível no Azure Government, no Azure Alemanha ou no Azure China 21Vianet.

  • Se migrar a subscrição do Azure para um novo inquilino, a pré-visualização do RBAC do Azure terá de ser reativada.

  • A adoção do controlo de acesso baseado em funções pode aumentar a latência de alguns pedidos. Cada combinação exclusiva de recurso de serviço (índice, indexador, etc.) e principal de serviço utilizado num pedido irá acionar uma verificação de autorização. Estas verificações de autorização podem somar até 200 milissegundos de latência a um pedido.

  • Em casos raros em que os pedidos têm origem num elevado número de principais de serviço diferentes, todos direcionados para diferentes recursos de serviço (índices, indexadores, etc.), é possível que as verificações de autorização resultem em limitação. A limitação só ocorreria se fossem utilizadas centenas de combinações exclusivas do recurso do serviço de pesquisa e do principal de serviço num segundo.

  • O controlo de acesso baseado em funções é suportado no portal do Azure e nos seguintes clientes de pesquisa:

Configurar o acesso baseado em funções para o plano de dados

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

Neste passo, configure o seu serviço de pesquisa para reconhecer um cabeçalho de autorização em pedidos de dados que fornecem um token de acesso OAuth2.

  1. Inicie sessão 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 controlo de acesso à API . Recomendamos Ambos se quiser flexibilidade ou precisar de migrar aplicações.

    Opção Estado Descrição
    Chave de API Disponível geralmente (predefinição) Requer um administrador ou chaves de API de consulta no cabeçalho do pedido para autorização. Não são utilizadas funções.
    Controlo de acesso baseado em funções Pré-visualizar Requer a associação a uma atribuição de função para concluir a tarefa, descrita no passo seguinte. Também requer um cabeçalho de autorização.
    Ambos Pré-visualizar Os pedidos são válidos através de uma chave de API ou de controlo de acesso baseado em funções.

A alteração tem efeito imediato, mas aguarde alguns segundos antes do teste.

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

Quando ativa o controlo de acesso baseado em funções no portal, o modo de falha será "http401WithBearerChallenge" se a autorização falhar.

Atribuir funções

As atribuições de funções são cumulativas e abrangentes em todas as ferramentas e bibliotecas de cliente. Pode atribuir funções com qualquer uma das abordagens suportadas descritas na documentação do controlo de acesso baseado em funções do Azure.

Tem de ser Proprietário ou ter permissões Microsoft.Authorization/roleAssignments/write para gerir atribuições de funções.

As atribuições de funções no portal são ao nível do serviço. Se quiser conceder permissões a um único índice, utilize o PowerShell ou a CLI do Azure.

  1. Abra o portal do Azure.

  2. Navegue para o seu serviço de pesquisa.

  3. Selecione Controlo de Acesso (IAM) no painel de navegação esquerdo.

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

    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
    • Contribuidor do Serviço de Pesquisa (pré-visualização para pedidos de planos de dados)
    • Contribuidor de Dados do Índice de Pesquisa (pré-visualização)
    • Leitor de Dados do Índice de Pesquisa (pré-visualização)
  6. No separador Membros, selecione o Azure AD identidade de utilizador ou grupo.

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

Testar atribuições de funções

Ao testar funções, lembre-se de que as funções são funções cumulativas e herdadas que estão no âmbito da subscrição ou grupo de recursos não podem ser eliminadas ou negadas ao nível do recurso (serviço de pesquisa).

  1. Abra o portal do Azure.

  2. Navegue para o seu serviço de pesquisa.

  3. Na página Descrição geral, selecione o separador Índices :

    • Os membros da função Contribuidor podem ver e criar qualquer objeto, mas não podem consultar um índice com o Explorador de Pesquisa.

    • Os membros do Leitor de Dados do Índice de Pesquisa podem utilizar o Explorador de Pesquisas para consultar o índice. Pode utilizar qualquer versão da API para procurar acesso. Deverá conseguir emitir consultas e ver resultados, mas não deverá conseguir ver a definição do índice.

    • Os membros do Contribuidor de Dados do Índice de Pesquisa podem selecionar Novo Índice para criar um novo índice. Guardar um novo índice irá verificar o acesso de escrita no serviço.

Conceder acesso a um único índice

Em alguns cenários, poderá querer limitar o acesso da aplicação a um único recurso, como um índice.

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

No PowerShell, utilize New-AzRoleAssignment, fornecendo o nome de utilizador ou grupo do Azure e o âmbito da atribuição.

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

    Import-Module -Name Az
    Import-Module -Name AzureAD
    Connect-AzAccount
    
  2. Adicionar uma atribuição de função no âmbito de 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 incorporadas não fornecerem a combinação certa de permissões, pode criar uma função personalizada para suportar as operações necessárias

Este exemplo clona o Leitor de Dados do Índice de Pesquisa 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.

Estes passos derivam de Criar ou atualizar funções personalizadas do Azure com o portal do Azure. A clonagem a partir de uma função existente é suportada numa página de serviço de pesquisa.

Estes passos criam uma função personalizada que aumenta os direitos de consulta de pesquisa para incluir a listagem de índices por nome. Normalmente, a listagem de índices é considerada uma função de administrador.

  1. No portal do Azure, navegue para o seu serviço de pesquisa.

  2. No painel de navegação esquerdo, selecione Controlo de Acesso (IAM).

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

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

  5. No separador Noções Básicas, forneça um nome para a função personalizada, como "Índice de Pesquisa Data Explorer" e, em seguida, selecione Seguinte.

  6. No separador Permissões, selecione Adicionar permissão.

  7. No separador Adicionar permissões, procure e, em seguida, selecione o mosaico Microsoft Search .

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

    • Em Microsoft.Search/operations, selecione Ler: Listar todas as operações disponíveis.
    • Em Microsoft.Search/searchServices/indexes, selecione Ler: Índice de Leitura.
  9. Na mesma página, mude para Ações de dados e, em Microsoft.Search/searchServices/indexes/documents, selecione Ler: Ler Documentos.

    A definição JSON tem o seguinte exemplo:

    {
     "properties": {
         "roleName": "search index data explorer",
         "description": "",
         "assignableScopes": [
             "/subscriptions/a5b1ca8b-bab3-4c26-aebe-4cf7ec4791a0/resourceGroups/heidist-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 pode atribuir utilizadores e grupos à função.

Desativar a autenticação da chave de API

As chaves de API não podem ser eliminadas, mas podem ser desativadas no seu serviço se estiver a utilizar as funções Contribuidor do Serviço de Pesquisa, Contribuidor de Dados do Índice de Pesquisa e Leitor de Dados do Índice de Pesquisa e autenticação Azure AD. A desativação das chaves de API faz com que o serviço de pesquisa recuse todos os pedidos relacionados com dados que transmitem uma chave de API no cabeçalho.

As permissões de Proprietário ou Contribuidor são necessárias para desativar as funcionalidades.

Para desativar a autenticação baseada em chaves, utilize portal do Azure ou a API REST de Gestão.

  1. No portal do Azure, navegue para o seu serviço de pesquisa.

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

  3. Selecione Controlo de acesso baseado em funções.

A alteração é efetuada imediatamente, mas aguarde alguns segundos antes de testar. Partindo do princípio de que tem permissão para atribuir funções como membro do Proprietário, administrador de serviços ou coadministrador, pode utilizar as funcionalidades do portal para testar o acesso baseado em funções.

Acesso Condicional

O Acesso Condicional é uma ferramenta no Azure Active Directory utilizada para impor políticas organizacionais. Ao utilizar políticas de Acesso Condicional, pode aplicar os controlos de acesso corretos quando necessário para manter a sua organização segura. Ao aceder a um serviço Azure Cognitive Search através do controlo de acesso baseado em funções, o Acesso Condicional pode impor políticas organizacionais.

Para ativar uma política de Acesso Condicional para Azure Cognitive Search, siga os passos abaixo:

  1. Inicie sessão no portal do Azure.

  2. Procure acesso condicional Azure AD.

  3. Selecione Políticas.

  4. Selecione + Nova política.

  5. Na secção Aplicações ou ações da cloud da política, adicione Azure Cognitive Search como uma aplicação na cloud, consoante a forma como pretende configurar a sua política.

  6. Atualize os restantes parâmetros da política. Por exemplo, especifique a que utilizadores e grupos esta política se aplica.

  7. Guarde a política.

Importante

Se o seu serviço de pesquisa tiver uma identidade gerida atribuída, o serviço de pesquisa específico será apresentado como uma aplicação na cloud que pode ser incluída ou excluída como parte da política de Acesso Condicional. As políticas de Acesso Condicional não podem ser impostas num serviço de pesquisa específico. Em vez disso, certifique-se de que seleciona a aplicação geral Azure Cognitive Search cloud.