Usar as chaves de API para autenticação no Azure Cognitive Search

O Cognitive Search oferece autenticação baseada em chave como a metodologia de autenticação primária. Nas solicitações de entrada para um ponto de extremidade de serviço de pesquisa, como solicitações que criam ou consultam um índice, as chaves de API são a única opção de autenticação com disponibilidade geral. Alguns cenários de solicitação de saída, especialmente aqueles que envolvem indexadores, podem usar identidades e funções do Azure Active Directory.

Observação

O RBAC (controle de acesso baseado em função) do Azure para solicitações de entrada para um ponto de extremidade de pesquisa agora está em versão prévia. É possível usar esse recurso em versão prévia para complementar ou substituir as chaves de API em solicitações de índice de pesquisa.

As chaves de API são geradas quando o serviço é criado. Passar uma chave de API válida na solicitação é considerado uma prova de que a solicitação é de um cliente autorizado. Há dois tipos de chaves. As chaves de administração transmitem permissões de gravação no serviço, e também concedem direitos para consultar informações do sistema. As chaves de consulta transmitem permissões de leitura e podem ser usadas por aplicativos para consultar um índice específico.

Ao se conectar a um serviço de pesquisa, todas as solicitações precisam incluir uma chave de API gerada especificamente para seu serviço.

  • Em soluções REST, a chave de API normalmente é especificada em um cabeçalho de solicitação

  • Em Soluções .NET, uma chave frequentemente é especificada como uma definição de configuração e, em seguida, transmitida como AzureKeyCredential

Você pode exibir e gerenciar as chaves de API no portal do Azure ou por meio do PowerShell, da CLI do Azure ou da API REST.

Página do portal, configurações de recuperação, seção de chaves

O que é uma chave de API?

Uma chave de API é uma cadeia de caracteres exclusiva composta de números e letras gerados aleatoriamente que são passadas em cada solicitação para o serviço de pesquisa. O serviço aceitará a solicitação, se a solicitação em si e a chave forem válidas.

Dois tipos de chaves são usados para acessar seu serviço de pesquisa: administrador (leitura-gravação) e consulta (somente leitura).

Chave Descrição Limites
Admin Concede direitos totais para todas as operações, incluindo a capacidade de gerenciar o serviço, criar e excluir índices, indexadores e fontes de dados.

Duas chaves de API de administrador, chamadas de chaves primária e secundária no portal, são geradas quando o serviço é criado e podem ser regeneradas individualmente sob demanda. Ter duas chaves permite que você substitua uma chave enquanto usa a segunda chave de acesso contínuo para o serviço.

As chaves de administrador são especificadas somente nos cabeçalhos de solicitação HTTP. Não é possível colocar uma chave de API de administrador em uma URL.
Máximo de dois por serviço
Consulta Concede acesso somente leitura a índices e documentos e normalmente são distribuídas para aplicativos cliente que emitem solicitações de pesquisa.

As chaves de consulta são criadas sob demanda.

As chaves de consulta podem ser especificadas em um cabeçalho de solicitação HTTP para pesquisa, sugestões ou operação de pesquisa. Como alternativa, você pode passar uma chave de consulta como um parâmetro em uma URL. Dependendo de como seu aplicativo cliente formula a solicitação, pode ser mais fácil passar a chave como um parâmetro de consulta:

GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key]
50 por serviço

Visualmente, não há nenhuma distinção entre as chaves de administrador ou de consulta. As duas chaves são cadeias de caracteres compostas de 32 caracteres alfanuméricos gerados aleatoriamente. Se você perder o controle de qual tipo de chave está especificado em seu aplicativo, poderá verificar os valores de chave no portal.

Observação

Passar dados confidenciais, como um api-key, no URI de solicitação, é considerado uma prática de segurança inadequada. Por esse motivo, o Azure Cognitive Search só aceita uma chave de consulta como uma api-key na cadeia de consulta, e você deve evitar fazer isso, a menos que o conteúdo do índice precise estar publicamente disponível. Em vez disso, recomendamos passar a api-key como um cabeçalho de solicitação.

Localizar chaves existentes

Você pode obter chaves de acesso no portal ou por meio do PowerShell,da CLI do Azure ou da API REST.

  1. Entre no portal do Azure.

  2. Liste os serviços de pesquisa para sua assinatura.

  3. Selecione o serviço e, na página de visão gera, localize Configurações>Chaves para exibir as chaves de administrador e de consulta.

    Página do portal, configurações de exibição, seção chaves

Excluir chaves de consulta

As chaves de consulta são usadas para acesso somente leitura a documentos dentro de um índice para operações direcionadas a uma coleção de documentos. Consultas de pesquisa, filtro e sugestão são todas operações que usam uma chave de consulta. Qualquer operação somente leitura que retorna dados do sistema ou definições de objeto, como uma definição de índice ou um status de indexador, requer uma chave de administração.

Restringir o acesso e as operações em aplicativos cliente é essencial para proteger os ativos de pesquisa em seu serviço. Sempre use uma chave de consulta em vez de uma chave de administração para qualquer consulta proveniente de um aplicativo cliente.

  1. Entre no portal do Azure.

  2. Liste os serviços de pesquisa para sua assinatura.

  3. Selecione o serviço e, na página Visão geral, clique em Configurações>Chaves.

  4. Clique em Gerenciar chaves de consulta.

  5. Use a chave de consulta já gerada para seu serviço ou crie até 50 chaves de consulta novas. A chave de consulta padrão não é nomeada, mas as chaves de consulta adicionais podem ser nomeadas para melhor gerenciamento.

    Criar ou usar uma chave de consulta

Observação

Um exemplo de código mostrando o uso da chave de consulta pode ser encontrado em DotNetHowTo.

Regenerar chaves de administrador

Duas chaves de administrador são criadas para cada serviço, para que você possa girar uma chave primária usando a chave secundária para acesso continuado.

  1. Na página Configurações>Chaves, copie a chave secundária.
  2. Para todos os aplicativos, atualize as configurações de chave de API para usar a chave secundária.
  3. Regenere a chave primária.
  4. Atualize todos os aplicativos para usar a nova chave primária.

Se você regenerar inadvertidamente as duas chaves ao mesmo tempo, todas as solicitações de cliente que usam essas chaves falharão com HTTP 403 Proibido. No entanto, o conteúdo não será excluído e você não será bloqueado permanentemente.

Você ainda pode acessar o serviço por meio do Portal ou programaticamente. As funções de gerenciamento são operacionais por meio de uma ID de assinatura, não de uma chave de API de serviço e, portanto, ainda estão disponíveis, mesmo que suas chaves de API não estejam.

Depois de criar novas chaves por meio do portal ou da camada de gerenciamento, o acesso é restaurado ao conteúdo (índices, indexadores, fontes de dados, mapas de sinônimos), quando você já tiver as novas chaves e fornecer essas chaves nas solicitações.

Proteger chaves de API

Atribuições de função determina quem pode ler e gerenciar chaves. Membros das funções a seguir podem exibir e regenerar chaves: Proprietário, Colaborador, Colaboradores do Serviço de Pesquisa. A função Leitor não tem acesso às chaves de API.

Os administradores de assinatura podem exibir e gerar novamente todas as chaves de API. Como precaução, revise as atribuições de função para entender quem tem acesso às chaves admin.

  1. Navegue até a folha de serviço de pesquisa no Portal do Azure.
  2. No painel de navegação à esquerda, selecione Controle de acesso (IAM) e, em seguida, selecione a guia Atribuições de função.
  3. Defina Escopo como Este recurso para visualizar atribuições de função para o seu serviço.

Confira também