Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
O Azure AI Search criptografa automaticamente dados em repouso com chaves gerenciadas pela Microsoft. Se você precisar de outra camada de criptografia ou da capacidade de revogar chaves e desligar o acesso ao conteúdo, poderá usar as chaves que criar e gerenciar no Azure Key Vault. Este artigo explica como configurar a criptografia cmk (chave gerenciada pelo cliente).
Você pode armazenar chaves usando o Azure Key Vault ou o HSM Gerenciado do Azure Key Vault (Módulo de Segurança de Hardware). Um HSM Gerenciado do Azure Key Vault é um HSM validado pelo FIPS 140-2 nível 3. O suporte ao HSM é novo no Azure AI Search. Para migrar para o HSM, gire suas chaves e escolha HSM Gerenciado para armazenamento.
Importante
A criptografia cmk é irreversível. Você pode girar chaves e alterar a configuração do CMK, mas a criptografia de índice dura o tempo de vida do índice. Criptografia pós-CMK, um índice só será acessível se o serviço de pesquisa tiver acesso à chave. Se você revogar o acesso à chave excluindo ou alterando a atribuição de função, o índice será inutilizável e o serviço não poderá ser dimensionado até que o índice seja excluído ou o acesso à chave seja restaurado. Se você excluir ou rotacionar chaves, a chave mais recente será armazenada em cache por até 60 minutos.
Objetos criptografados pela CMK
A criptografia cmk se aplica a objetos individuais quando eles são criados. Isso significa que você não pode criptografar objetos que já existem. A criptografia CMK ocorre sempre que um objeto é salvo em disco, tanto para dados em repouso (armazenamento de longo prazo) quanto para dados em cache temporários (armazenamento de curto prazo). Com a CMK, o disco nunca visualiza dados não criptografados.
Os objetos que podem ser criptografados incluem índices, listas de sinônimos, indexadores, fontes de dados e conjuntos de habilidades. A criptografia é computacionalmente cara de descriptografar, por isso somente o conteúdo sensível é criptografado.
A criptografia é executada no seguinte conteúdo:
Todo o conteúdo dos índices e das listas de sinônimos.
Conteúdo confidencial em indexadores, fontes de dados, conjuntos de habilidades e vetorizadores. Conteúdo confidencial refere-se a cadeias de conexão, descrições, identidades, chaves e entradas do usuário. Por exemplo, os conjuntos de habilidades têm chaves de serviços de IA do Azure e algumas habilidades aceitam entradas de usuário, como entidades personalizadas. Em ambos os casos, as chaves e as entradas do usuário são criptografadas. Quaisquer referências a recursos externos (como fontes de dados do Azure ou modelos do OpenAI do Azure) também são criptografadas.
Se você precisar de CMK em seu serviço de pesquisa, defina uma política de imposição.
Pré-requisitos
Pesquisa de IA do Azure em uma camada faturável (Básica ou superior, em qualquer região).
Azure Key Vault e um cofre de chaves com exclusão temporária e proteção contra limpeza habilitados. Ou, Azure Key Vault Managed HSM. Esse recurso pode estar em qualquer assinatura, mas deve estar no mesmo locatário do Azure AI Search.
Capacidade de configurar permissões para acesso de chave e atribuir funções. Para criar chaves, você deve ser o Oficial de Criptografia do Key Vault no Azure Key Vault ou Oficial de Criptografia HSM Gerenciado no Managed HSM do Azure Key Vault.
Para atribuir funções, você deve ser Proprietário, Administrador de Acesso do Usuário, Administrador de Controle de Acesso baseado em Função da assinatura ou ser atribuído a uma função personalizada com permissões Microsoft.Authorization/roleAssignments/write.
Etapa 1: Criar uma chave de criptografia
Use o Azure Key Vault ou o HSM Gerenciado do Azure Key Vault para criar uma chave. A criptografia da Pesquisa de IA do Azure é compatível com chaves RSA de tamanhos 2048, 3072 e 4096. Para obter mais informações sobre os tipos de chave com suporte, confira Sobre chaves.
É recomendável revisar essas dicas antes de começar.
As operações necessárias são Encapsular, Desembrulhar, Criptografar e Descriptografar.
Você pode criar um cofre de chaves usando o portal do Azure, a CLI do Azure ou o Azure PowerShell.
Entre no portal do Azure e abra a visão geral do cofre de chaves.
Selecione Objetos>Chaves à esquerda e, em seguida, selecione Gerar/Importar.
No painel Criar uma chave, na lista de Opções, escolha Gerar para criar uma chave.
Insira um Nome para sua chave e aceite os padrões para outras propriedades da chave.
Opcionalmente, defina uma política de rotação de chaves para habilitar a rotação automática.
Selecione Criar para iniciar a implantação.
Depois que a chave for criada, obtenha seu identificador de chave. Selecione a chave, selecione a versão atual e copie o identificador de chave. Ele é composto pelo URI do valor da chave, pelo nome da chave e pela versão da chave. Você precisará do identificador para definir um índice criptografado na Pesquisa de IA do Azure. Lembre-se de que as operações necessárias são Wrap, Unwrap, Encrypt e Decrypt.
Etapa 2: criar uma entidade de segurança
Crie uma entidade de segurança que seu serviço de pesquisa usa para acessar a chave de criptografia. Você pode usar uma identidade gerenciada e atribuição de função ou registrar um aplicativo e fazer com que o serviço de pesquisa forneça a ID do aplicativo nas solicitações.
É recomendável usar uma identidade gerenciada e funções. Você pode usar uma identidade gerenciada pelo sistema ou uma identidade gerenciada pelo usuário. Uma identidade gerenciada permite que seu serviço de pesquisa se autentique por meio da ID do Microsoft Entra, sem armazenar credenciais (ApplicationID ou ApplicationSecret) no código. O ciclo de vida desse tipo de identidade gerenciada está vinculado ao ciclo de vida do serviço de pesquisa, que só pode ter uma identidade gerenciada atribuída ao sistema. Para obter mais informações sobre como identidades gerenciadas funcionam, consulte O que são identidades gerenciadas para recursos do Azure?.
- Identidade gerenciada pelo sistema
- Identidade gerenciada pelo usuário (versão prévia)
- Registrar um aplicativo
Habilite a identidade gerenciada atribuída pelo sistema para seu serviço de pesquisa. É uma operação de dois cliques, habilitar e salvar.
Etapa 3: conceder permissões
Se você configurou seu serviço de pesquisa para usar uma identidade gerenciada, atribua funções que lhe dão acesso à chave de criptografia.
O controle de acesso baseado em função é recomendado no modelo de permissão da Política de Acesso. Para obter mais informações ou etapas de migração, comece com o RBAC (controle de acesso baseado em função) do Azure versus as políticas de acesso (herdadas).
Entre no portal do Azure e localize seu cofre de chaves.
Selecione Controle de Acesso (IAM) e selecione Adicionar atribuição de função.
Selecione uma função:
- No Azure Key Vault, selecione Usuário de Criptografia do Serviço de Criptografia do Key Vault.
- No HSM Gerenciado, selecione Usuário de Criptografia do Serviço de Criptografia Gerenciada do HSM.
Selecione identidades gerenciadas, selecione membros e, em seguida, selecione a identidade gerenciada de seu serviço de pesquisa. Se estiver testando localmente, atribua essa função a si mesmo também.
Selecione Examinar + Atribuir.
Aguarde alguns minutos para que a atribuição de função se torne operacional.
Etapa 4: criptografar o conteúdo
A criptografia ocorre quando você cria ou atualiza um objeto. Você pode usar o portal do Azure para objetos selecionados. Para qualquer objeto, use a API REST de Pesquisa ou um SDK do Azure. Examine o exemplo do Python neste artigo para ver como o conteúdo é criptografado programaticamente.
Ao criar um novo objeto no portal do Azure, você pode especificar uma chave gerenciada pelo cliente predefinida em um cofre de chaves. O portal do Azure permite habilitar a criptografia cmk para:
- Índices
- Fontes de dados
- Indexadores
Para usar o portal do Azure, é necessário que o cofre de chaves e a chave existam e que você tenha concluído as etapas anteriores para obter acesso autorizado à chave.
No portal do Azure, os conjuntos de habilidades são definidos na exibição JSON. Use o JSON mostrado nos exemplos da API REST para fornecer uma chave gerenciada pelo cliente em um conjunto de habilidades.
Entre no portal do Azure e abra a página do serviço de pesquisa.
Em Gerenciamento de pesquisa, selecione Índices, Indexadores ou Fontes de Dados.
Adicione um novo objeto. Na definição de objeto, selecione criptografia gerenciada pela Microsoft.
Selecione chaves gerenciadas pelo cliente e escolha sua assinatura, cofre, chave e versão.
Etapa 5: testar criptografia
Para verificar se a criptografia está funcionando, revogue a chave de criptografia, consulte o índice (ele deve estar inutilizável) e, em seguida, restabeleça a chave de criptografia.
Use o portal do Azure para essa tarefa. Verifique se você tem uma atribuição de função que concede acesso de leitura à chave.
Na página do Azure Key Vault, selecione Objetos>Chaves.
Selecione a chave que você criou e, em seguida, selecione Excluir.
Na página Pesquisa de IA do Azure, selecione Gerenciamento de pesquisa>Índices.
Selecione seu índice e use o Explorador de Pesquisa para executar uma consulta. Você deverá receber um erro.
Retorne à página Objetos>Chaves do Azure Key Vault.
Selecione Gerenciar chaves excluídas.
Selecione sua chave e, em seguida, Recuperar.
Retorne ao seu índice na Pesquisa de IA do Azure e execute novamente a consulta. Você deverá ver os resultados da pesquisa. Se os resultados não forem imediatos, aguarde um minuto e tente novamente.
Configurar uma política para impor a conformidade com o CMK
As políticas do Azure ajudam a impor padrões organizacionais e a avaliar a conformidade em escala. O Azure AI Search tem duas políticas internas opcionais relacionadas ao CMK. Essas políticas se aplicam a serviços de pesquisa novos e existentes.
| Efeito | Efeito se habilitado |
|---|---|
| AuditIfNotExists | Verifica se há conformidade com a política: os objetos têm uma chave gerenciada pelo cliente definida e é o conteúdo criptografado. Esse efeito se aplica aos serviços existentes com conteúdo. Ele é avaliado sempre que um objeto é criado ou atualizado, ou de acordo com o agendamento de avaliação. Saiba mais... |
| Negar | Verifica se há imposição de política: o serviço de pesquisa tem SearchEncryptionWithCmk definido como Enabled. Esse efeito se aplica somente a novos serviços, que devem ser criados com a criptografia habilitada. Os serviços existentes permanecem operacionais, mas você não pode atualizá-los, a menos que você corrija o serviço. Nenhuma das ferramentas usadas para serviços de provisionamento expõe essa propriedade, portanto, lembre-se de que definir a política limita a configuração programática. |
Atribuir uma política
No portal do Azure, navegue até uma política interna e selecione Atribuir.
Aqui está um exemplo da política AuditIfExists no portal do Azure:
Defina o escopo da política selecionando a assinatura e o grupo de recursos. Exclua os serviços de pesquisa para os quais a política não deve ser aplicada.
Aceite ou modifique os padrões. Selecione Revisar +criar, seguido por Criar.
Habilitar a imposição de política da CMK
Uma política atribuída a um grupo de recursos em sua assinatura entra em vigor imediatamente. As políticas de auditoria sinalizam recursos não compatíveis, mas as políticas de negação impedem a criação e a atualização de serviços de pesquisa não compatíveis. Esta seção explica como criar um serviço de pesquisa em conformidade ou atualizar um serviço para torná-lo compatível. Para colocar objetos em conformidade, comece na etapa um deste artigo.
Criar um serviço de pesquisa em conformidade
Para novos serviços de pesquisa, crie-os com SearchEncryptionWithCmk definido como Enabled.
Nem o portal do Azure nem as ferramentas de linha de comando (a CLI do Azure e o Azure PowerShell) fornecem essa propriedade nativamente, mas você pode usar a API REST de Gerenciamento para provisionar um serviço de pesquisa com uma definição de política do CMK.
Este exemplo é de Gerenciar seu serviço do Azure AI Search com APIs REST, modificadas para incluir a propriedade SearchEncryptionWithCmk .
### Create a search service (provide an existing resource group)
@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"location": "North Central US",
"sku": {
"name": "basic"
},
"properties": {
"replicaCount": 1,
"partitionCount": 1,
"hostingMode": "default",
"encryptionWithCmk": {
"enforcement": "Enabled"
}
}
}
Atualizar um serviço de pesquisa existente
Para os serviços de pesquisa existentes que agora não estão em conformidade, corrija-os usando Serviços – Atualizar a API ou o comando az resource update da CLI do Azure . A aplicação de patches nos serviços restaura a capacidade de atualizar as propriedades do serviço de pesquisa.
PATCH https://management.azure.com/subscriptions/<your-subscription-Id>/resourceGroups/<your-resource-group-name>/providers/Microsoft.Search/searchServices/<your-search-service-name>?api-version=2023-11-01
{
"properties": {
"encryptionWithCmk": {
"enforcement": "Enabled"
}
}
}
Girar ou atualizar as chaves de criptografia
Use as instruções a seguir para girar chaves ou migrar do Azure Key Vault para o HSM (Modelo de Segurança de Hardware).
Para rotação de chaves, é recomendável usar os recursos de autorotação do Azure Key Vault. Se você usar a rotação automática, omita a versão da chave nas definições de objeto. A chave mais recente é usada, em vez de uma versão específica.
Quando você altera uma chave ou sua versão, qualquer objeto que use a chave deve ser atualizado primeiro para usar os novos valores antes de excluir os valores antigos. Caso contrário, o objeto se tornará inutilizável porque não poderá ser descriptografado.
Lembre-se de que as chaves são armazenadas em cache por 60 minutos. Lembre-se disso ao testar e girar chaves.
Determine a chave usada por um mapa de índice ou de sinônimo.
Criar uma nova chave no cofre de chaves, mas deixar a chave original disponível. Nesta etapa, você pode alternar do cofre de chaves para o HSM.
Atualize as propriedades do encryptionKey em um mapa de índice ou de sinônimos para usar os novos valores. Somente os objetos que foram criados originalmente com essa propriedade poderão ser atualizados para usar um valor diferente.
Desabilitar ou excluir a chave anterior no cofre de chaves. Monitorar o acesso à chave para verificar se a nova chave está sendo usada.
Por motivos de desempenho, o serviço de pesquisa armazena em cache a chave por até várias horas. Se a chave for desabilitada ou excluída sem o fornecimento de uma nova, as consultas continuarão a funcionar de forma temporária até que o cache expire. No entanto, depois que o serviço de pesquisa não puder mais descriptografar o conteúdo, você receberá esta mensagem: "Access forbidden. The query key used might have been revoked - please retry."
Dicas do Key Vault
Se você é novo no Azure Key Vault, confira o início rápido para saber mais sobre as tarefas básicas: Definir e recuperar um segredo do Azure Key Vault usando o PowerShell.
Use quantos cofres de chaves forem necessários. As chaves gerenciadas podem estar em cofres de chaves diferentes. Um serviço de pesquisa pode ter diversos objetos criptografados, cada um com uma chave de criptografia gerenciada pelo cliente diferente, armazenados em diferentes cofres de chaves.
Use o mesmo locatário do Azure para que você possa recuperar sua chave gerenciada por meio de atribuições de função e conectando-se por meio de um sistema ou identidade gerenciada pelo usuário. Para obter mais informações sobre a criação de um locatário, consulte Configurar um novo locatário.
Habilite a proteção contra limpeza e a exclusão temporária em um cofre de chaves. Devido à natureza da criptografia com chaves gerenciadas pelo cliente, ninguém pode recuperar seus dados quando sua chave do Azure Key Vault é excluída. Para evitar a perda de dados causada por exclusões acidentais de chaves do Key Vault, devem ser habilitadas a exclusão temporária e a proteção contra limpeza no cofre de chaves. A exclusão lógica é habilitada por padrão, portanto, você só terá problemas se a desabilitar intencionalmente. A proteção contra limpeza não está habilitada por padrão, mas é necessária para a CMK na Pesquisa de IA do Azure.
Habilite o registro no cofre de chaves para poder monitorar o uso de chaves.
Habilite a rotação automática de chaves ou siga procedimentos rigorosos durante a rotação de rotina das chaves do cofre de chaves e dos segredos e registros de aplicativos. Sempre atualize todo o conteúdo criptografado para usar novos segredos e chaves antes de excluir os antigos. O conteúdo não será descriptografado se essa etapa for ignorada.
Trabalhar com conteúdo criptografado
Com a criptografia CMK, você pode notar latência na indexação e nas consultas devido ao trabalho de criptografia/descriptografia extra. O Azure AI Search não registra a atividade de criptografia, mas você pode monitorar o acesso à chave através do log do cofre de chaves.
Recomendamos habilitar o registro em log como parte da configuração do cofre de chaves.
Adicione uma configuração de diagnóstico no Key Vault que use o espaço de trabalho para retenção de dados.
Selecione auditoria ou allLogs para a categoria, dê um nome à configuração de diagnóstico e salve-a.
Exemplo em Python de uma configuração de chave de criptografia
Esta seção mostra a representação do Python de um encryptionKey em uma definição de objeto. A mesma definição se aplica a índices, fontes de dados, conjunto de habilidades, indexadores e mapas de sinônimos. Para experimentar esse exemplo no serviço de pesquisa e no cofre de chaves, baixe o notebook em azure-search-python-samples.
Instale alguns pacotes.
! pip install python-dotenv
! pip install azure-core
! pip install azure-search-documents==11.5.1
! pip install azure-identity
Crie um índice que tenha uma chave de criptografia.
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
SimpleField,
SearchFieldDataType,
SearchableField,
SearchIndex,
SearchResourceEncryptionKey
)
from azure.identity import DefaultAzureCredential
endpoint="<PUT YOUR AZURE SEARCH SERVICE ENDPOINT HERE>"
credential = DefaultAzureCredential()
index_name = "test-cmk-index"
index_client = SearchIndexClient(endpoint=endpoint, credential=credential)
fields = [
SimpleField(name="Id", type=SearchFieldDataType.String, key=True),
SearchableField(name="Description", type=SearchFieldDataType.String)
]
scoring_profiles = []
suggester = []
encryption_key = SearchResourceEncryptionKey(
key_name="<PUT YOUR KEY VAULT NAME HERE>",
key_version="<PUT YOUR ALPHANUMERIC KEY VERSION HERE>",
vault_uri="<PUT YOUR KEY VAULT ENDPOINT HERE>"
)
index = SearchIndex(name=index_name, fields=fields, encryption_key=encryption_key)
result = index_client.create_or_update_index(index)
print(f' {result.name} created')
Obtenha a definição do índice para verificar se a configuração da chave de criptografia existe.
index_name = "test-cmk-index-qs"
index_client = SearchIndexClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential)
result = index_client.get_index(index_name)
print(f"{result}")
Carregue o índice com alguns documentos. Todo o conteúdo do campo é considerado confidencial e criptografado no disco usando sua chave gerenciada pelo cliente.
from azure.search.documents import SearchClient
# Create a documents payload
documents = [
{
"@search.action": "upload",
"Id": "1",
"Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities."
},
{
"@search.action": "upload",
"Id": "2",
"Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts."
},
{
"@search.action": "upload",
"Id": "3",
"Description": "The hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel's restaurant services."
},
{
"@search.action": "upload",
"Id": "4",
"Description": "The hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace."
}
]
search_client = SearchClient(endpoint=AZURE_SEARCH_SERVICE, index_name=index_name, credential=credential)
try:
result = search_client.upload_documents(documents=documents)
print("Upload of new document succeeded: {}".format(result[0].succeeded))
except Exception as ex:
print (ex.message)
index_client = SearchClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential)
Execute uma consulta para confirmar que o índice está funcionando.
from azure.search.documents import SearchClient
query = "historic"
search_client = SearchClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential, index_name=index_name)
results = search_client.search(
query_type='simple',
search_text=query,
select=["Id", "Description"],
include_total_count=True
)
for result in results:
print(f"Score: {result['@search.score']}")
print(f"Id: {result['Id']}")
print(f"Description: {result['Description']}")
A saída da consulta deve produzir resultados semelhantes aos do exemplo a seguir.
Score: 0.6130029
Id: 4
Description: The hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace.
Score: 0.26286605
Id: 1
Description: The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
Como o conteúdo criptografado é descriptografado antes da atualização dos dados ou das consultas, você não verá evidências visuais da criptografia. Para verificar se a criptografia está funcionando, verifique os logs de recursos.
Próximas etapas
Se você não estiver familiarizado com a arquitetura de segurança do Azure, confira a documentação de segurança do Azure e, em particular, este artigo: