Habilitar ou desabilitar o controle de acesso baseado em função no Azure AI Search

Artigo
06/20/2024

Antes de atribuir funções para acesso autorizado ao Azure AI Search, habilite o controle de acesso baseado em função em seu serviço de pesquisa.

O acesso baseado em função para operações de plano de dados é opcional, mas recomendado como a opção mais segura. A alternativa é a autenticação baseada em chave, que é o padrão.

As funções para administração de serviços (plano de controle) são incorporadas e não podem ser habilitadas ou desabilitadas.

Nota

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 do SDK do Azure.

Pré-requisitos

Um serviço de pesquisa em qualquer região, em qualquer nível, incluindo gratuito.
Proprietário, Administrador de Acesso de Usuário ou uma função personalizada com permissões Microsoft.Authorization/roleAssignments/write .

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

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.

Quando você habilita funções para o plano de dados, a alteração entra em vigor imediatamente, mas aguarde alguns segundos antes de atribuir funções.

O modo de falha padrão para solicitações não autorizadas é http401WithBearerChallenge. Como alternativa, você pode definir o modo de falha como http403.

Entre no portal do Azure e abra a página do serviço de pesquisa.
Selecione Configurações e, em seguida, selecione Teclas no painel de navegação esquerdo.

Escolha Controle baseado em função ou Ambos se estiver usando chaves no momento e precisar de tempo para fazer a transição de clientes para o controle de acesso baseado em função.

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.

Como administrador, se você escolher uma abordagem somente de funções, atribua funções de plano de dados à sua conta de usuário para restaurar o acesso administrativo total sobre operações de plano de dados no portal do Azure. As funções incluem Colaborador do Serviço de Pesquisa, Colaborador de Dados do Índice de Pesquisa e Leitor de Dados do Índice de Pesquisa. Você precisa das três funções se quiser acesso equivalente.

Às vezes, pode levar de cinco a dez minutos para que as atribuições de função entrem em vigor. Até que isso aconteça, a seguinte mensagem aparece nas páginas do portal usadas para operações de plano de dados.

Execute este script para suportar apenas funções:

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --disable-local-auth

Ou, execute este script para suportar chaves e funções:

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --aad-auth-failure-mode http401WithBearerChallenge `
  --auth-options aadOrApiKey

Para obter mais informações, consulte Gerenciar seu serviço Azure AI Search com a CLI do Azure.

Execute este comando para definir o tipo de autenticação apenas para funções:

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -DisableLocalAuth 1

Ou, execute este comando para suportar teclas e funções:

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -AuthOption AadOrApiKey

Para obter mais informações, consulte Gerenciar seu serviço Azure AI Search com o PowerShell.

Use o Serviço Criar ou Atualizar a API REST de Gerenciamento para configurar seu serviço para controle de acesso baseado em função.

Todas as chamadas para a API REST de gerenciamento são autenticadas por meio da ID do Microsoft Entra. Para obter ajuda com a configuração de solicitações autenticadas, consulte Gerenciar a Pesquisa de IA do Azure usando REST.

Obtenha as configurações de serviço para que você possa revisar a configuração atual.

GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01

Use PATCH para atualizar a configuração do serviço. As modificações a seguir habilitam as chaves e o acesso baseado em função. Se você quiser uma configuração somente de funções, consulte Desabilitar chaves de API.

Em "propriedades", defina "authOptions" como "aadOrApiKey". A propriedade "disableLocalAuth" deve ser false para definir "authOptions".

Opcionalmente, defina "aadAuthFailureMode" para especificar se 401 é retornado em vez de 403 quando a autenticação falha. Os valores válidos são "http401WithBearerChallenge" ou "http403".
```
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
{
    "properties": {
        "disableLocalAuth": false,
        "authOptions": {
            "aadOrApiKey": {
                "aadAuthFailureMode": "http401WithBearerChallenge"
            }
        }
    }
}
```

Desativar o controle de acesso baseado em função

É possível desativar o controle de acesso baseado em função para operações de plano de dados e usar a autenticação baseada em chave. Você pode fazer isso como parte de um fluxo de trabalho de teste, por exemplo, para excluir problemas de permissão.

Inverta as etapas seguidas anteriormente para habilitar o acesso baseado em função.

Entre no portal do Azure e abra a página do serviço de pesquisa.
Selecione Configurações e, em seguida, selecione Teclas no painel de navegação esquerdo.
Selecione Chaves de API.

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 exclusivamente 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.

As chaves da API de administrador podem ser desativadas, mas 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 de segurança.

No portal do Azure, navegue até o serviço de pesquisa.
No painel de navegação esquerdo, selecione Chaves.
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.

Para desativar a autenticação baseada em chave, defina -disableLocalAuth como true. Esta é a mesma sintaxe que o script "enable roles only" apresentado na seção anterior.

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --disable-local-auth

Para reativar a autenticação de chave, defina -disableLocalAuth como false. O serviço de pesquisa retoma automaticamente a aceitação de chaves de API na solicitação (supondo que elas sejam especificadas).

Para obter mais informações, consulte Gerenciar seu serviço Azure AI Search com a CLI do Azure.

Para desativar a autenticação baseada em chave, defina DisableLocalAuth como true. Esta é a mesma sintaxe que o script "enable roles only" apresentado na seção anterior.

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -DisableLocalAuth 1

Para reativar a autenticação de chave, defina DisableLocalAuth como false. O serviço de pesquisa retoma automaticamente a aceitação de chaves de API na solicitação (supondo que elas sejam especificadas).

Para obter mais informações, consulte Gerenciar seu serviço Azure AI Search com o PowerShell.

Para desativar a autenticação baseada em chave, defina "disableLocalAuth" como true.

Obtenha as configurações de serviço para que você possa revisar a configuração atual.

GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01

Use PATCH para atualizar a configuração do serviço. A modificação a seguir define "authOptions" como null.

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
{
    "properties": {
        "disableLocalAuth": true
    }
}

Para reativar a autenticação de chave, defina "disableLocalAuth" como false. O serviço de pesquisa retoma automaticamente a aceitação de chaves de API na solicitação (supondo que elas sejam especificadas).

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.

Próximos passos

Configurar funções para acesso a um serviço de pesquisa

Partilhar via