Door de klant beheerde sleutels configureren voor gegevensversleuteling in Azure AI Search
Azure AI Search versleutelt automatisch data-at-rest met door de service beheerde sleutels. Als er meer beveiliging nodig is, kunt u standaardversleuteling aanvullen met een andere versleutelingslaag met behulp van sleutels die u in Azure Key Vault maakt en beheert.
In dit artikel worden de stappen beschreven voor het instellen van door de klant beheerde sleutel (CMK) of BYOK-versleuteling (Bring-Your-Own-Key).
Notitie
Als een index CMK is versleuteld, is deze alleen toegankelijk als de zoekservice toegang heeft tot de sleutel. Als de toegang wordt ingetrokken, is de index onbruikbaar en kan de service pas worden geschaald als de index is verwijderd of de toegang tot de sleutel is hersteld.
Met CMK versleutelde objecten
CMK-versleuteling wordt uitgevoerd op afzonderlijke objecten. Als u CMK in uw zoekservice nodig hebt, stelt u een afdwingingsbeleid in.
CMK-versleuteling wordt operationeel wanneer een object wordt gemaakt. U kunt objecten die al bestaan, niet versleutelen. CMK-versleuteling vindt plaats wanneer een object wordt opgeslagen op schijf, ofwel data-at-rest voor langetermijnopslag of tijdelijke gegevens voor kortetermijnopslag. Met CMK ziet de schijf nooit niet-versleutelde gegevens.
Objecten die kunnen worden versleuteld, zijn indexen, synoniemenlijsten, indexeerfuncties, gegevensbronnen en vaardighedensets. Versleuteling is rekenkrachtig om te ontsleutelen, zodat alleen gevoelige inhoud wordt versleuteld.
Versleuteling wordt uitgevoerd via de volgende inhoud:
Alle inhoud in indexen en synoniemenlijsten.
Gevoelige inhoud in indexeerfuncties, gegevensbronnen, vaardighedensets en vectorizers. Deze inhoud bestaat alleen uit velden die verbindingsreeks s, beschrijvingen, identiteiten, sleutels en gebruikersinvoer opslaan. Vaardighedensets hebben bijvoorbeeld Sleutels voor Azure AI-services en sommige vaardigheden accepteren gebruikersinvoer, zoals aangepaste entiteiten. In beide gevallen worden sleutels en gebruikersinvoer in vaardigheden versleuteld. Verwijzingen naar externe resources (zoals Azure-gegevensbronnen of Azure OpenAI-modellen) worden ook versleuteld.
Volledige dubbele versleuteling
Wanneer u CMK-versleuteling introduceert, versleutelt u inhoud twee keer. Voor de objecten en velden die in de vorige sectie zijn genoteerd, wordt inhoud eerst versleuteld met uw CMK en ten tweede met de door Microsoft beheerde sleutel. Inhoud wordt dubbel versleuteld op gegevensschijven voor langetermijnopslag en op tijdelijke schijven die worden gebruikt voor kortetermijnopslag.
Door CMK-versleuteling in te schakelen, worden de indexgrootte vergroot en worden de queryprestaties verminderd. Op basis van waarnemingen tot heden kunt u verwachten dat er een toename van 30-60 procent in querytijden is, hoewel de werkelijke prestaties variëren, afhankelijk van de indexdefinitie en typen query's. Omdat de prestaties afnemen, raden we u aan deze functie alleen in te schakelen voor objecten die deze echt nodig hebben.
Hoewel dubbele versleuteling nu beschikbaar is in alle regio's, is de ondersteuning in twee fasen geïmplementeerd:
De eerste implementatie was op 1 augustus 2020 en bevatte de vijf onderstaande regio's. Search-service die zijn gemaakt in de volgende regio's, worden CMK ondersteund voor gegevensschijven, maar niet tijdelijke schijven:
- VS - west 2
- VS - oost
- VS - zuid-centraal
- VS (overheid) - Virginia
- US Gov - Arizona
De tweede implementatie op 13 mei 2021 heeft versleuteling toegevoegd voor tijdelijke schijven en uitgebreide CMK-versleuteling voor alle ondersteunde regio's.
Als u CMK gebruikt van een service die tijdens de eerste implementatie is gemaakt en u ook CMK-versleuteling via tijdelijke schijven wilt, moet u een nieuwe zoekservice maken in uw regio van keuze en uw inhoud opnieuw implementeren. Zie De aanmaakdatum van de service controleren om de aanmaakdatum van de service te bepalen.
Vereisten
Azure AI Search op een factureerbare laag (Basic of hoger, in elke regio).
Azure Key Vault in hetzelfde abonnement als Azure AI Search. U kunt een sleutelkluis maken met behulp van Azure Portal, Azure CLI of Azure PowerShell. Voor de sleutelkluis moet voorlopig verwijderen en beveiliging tegen opschonen zijn ingeschakeld.
Een zoekclient die een versleuteld object kan maken, zoals een REST-client, Azure PowerShell of een Azure SDK (Python, .NET, Java, JavaScript).
Beperkingen
Geen ondersteuning voor Azure Key Vault Managed Hardware Security Model (HSM).
Geen ondersteuning voor meerdere abonnementen. Azure Key Vault en Azure AI Search moeten zich in hetzelfde abonnement bevinden.
Tips voor Key Vault
Als u geen ervaring hebt met Azure Key Vault, raadpleegt u deze quickstart voor meer informatie over basistaken: Een geheim instellen en ophalen uit Azure Key Vault met behulp van PowerShell.
Hier volgen enkele tips voor het gebruik van Key Vault:
Gebruik zoveel sleutelkluizen als u nodig hebt. Beheerde sleutels kunnen zich in verschillende sleutelkluizen bevinden. Een zoekservice kan meerdere versleutelde objecten bevatten, elk met een andere door de klant beheerde versleutelingssleutel, die is opgeslagen in verschillende sleutelkluizen.
Gebruik dezelfde tenant zodat u uw beheerde sleutel kunt ophalen door verbinding te maken via een door een systeem of door de gebruiker beheerde identiteit. Voor dit gedrag moeten beide services dezelfde tenant delen. Zie Een nieuwe tenant instellen voor meer informatie over het maken van een tenant.
Schakel beveiliging tegen opschonen en voorlopig verwijderen in. Vanwege de aard van versleuteling met door de klant beheerde sleutels kan niemand uw gegevens ophalen als uw Azure Key Vault-sleutel wordt verwijderd. Om te voorkomen dat gegevens verloren gaan als gevolg van onbedoelde verwijderingen van Key Vault-sleutels, moet beveiliging tegen voorlopig verwijderen en opschonen zijn ingeschakeld in de sleutelkluis. Voorlopig verwijderen is standaard ingeschakeld, dus u ondervindt alleen problemen als u het doeleinde uitschakelt. Beveiliging tegen opschonen is niet standaard ingeschakeld, maar is vereist voor door de klant beheerde sleutelversleuteling in Azure AI Search.
Schakel logboekregistratie in voor de sleutelkluis, zodat u het sleutelgebruik kunt controleren.
Schakel automatische rotatie van sleutels in of volg strikte procedures tijdens routinerotatie van sleutelkluissleutels en toepassingsgeheimen en -registratie. Werk altijd alle versleutelde inhoud bij om nieuwe geheimen en sleutels te gebruiken voordat u de oude geheimen verwijdert. Als u deze stap mist, kan uw inhoud niet worden ontsleuteld.
Stap 1: Een sleutel maken in Key Vault
Sla sleutelgeneratie over als u al een sleutel in Azure Key Vault hebt die u wilt gebruiken, maar de sleutel-id verzamelt. U hebt deze informatie nodig bij het maken van een versleuteld object.
Voordat u de sleutel toevoegt, moet u ervoor zorgen dat u de rol Key Vault Crypto Officer aan uzelf hebt toegewezen.
Azure AI Search-versleuteling ondersteunt RSA-sleutels van grootte 2048, 3072 en 4096. Zie Over sleutels voor meer informatie over ondersteunde sleuteltypen.
Meld u aan bij Azure Portal en open de overzichtspagina van uw sleutelkluis.
Selecteer Objectentoetsen> aan de linkerkant en selecteer vervolgens Genereren/importeren.
Kies Genereren in het deelvenster Een sleutel maken in de lijst met opties de optie Genereren om een nieuwe sleutel te maken.
Voer een naam in voor uw sleutel en accepteer de standaardwaarden voor andere sleuteleigenschappen.
Stel desgewenst een sleutelrotatiebeleid in om automatische rotatie in te schakelen.
Selecteer Maken om de implementatie te starten.
Selecteer de sleutel, selecteer de huidige versie en noteer de sleutel-id. Deze bestaat uit de sleutelwaarde-URI, de sleutelnaam en de sleutelversie. U hebt de id nodig om een versleutelde index te definiëren in Azure AI Search.
Stap 2: Een beveiligingsprincipaal maken
U hebt verschillende opties voor het instellen van Azure AI Search-toegang tot de versleutelingssleutel tijdens runtime. De eenvoudigste methode is om de sleutel op te halen met behulp van de beheerde identiteit van uw zoekservice. U kunt een door een systeem beheerde identiteit of een door de gebruiker beheerde identiteit gebruiken. Hierdoor kunt u de stappen voor toepassingsregistratie en toepassingsgeheimen weglaten. U kunt ook een Microsoft Entra-toepassing maken en registreren en de zoekservice de toepassings-id laten opgeven voor aanvragen.
U wordt aangeraden een beheerde identiteit te gebruiken. Met een beheerde identiteit kan uw zoekservice worden geverifieerd bij Azure Key Vault zonder referenties (ApplicationID of ApplicationSecret) in code op te slaan. De levenscyclus van dit type beheerde identiteit is gekoppeld aan de levenscyclus van uw zoekservice, die slechts één door het systeem toegewezen beheerde identiteit kan hebben. Zie Wat zijn beheerde identiteiten voor Azure-resources voor meer informatie over hoe beheerde identiteiten werken.
- Door het systeem beheerde identiteit
- Door de gebruiker beheerde identiteit (preview)
- Een app registreren
Schakel de door het systeem toegewezen beheerde identiteit in voor uw zoekservice.
Stap 3: Machtigingen verlenen
Azure Key Vault ondersteunt autorisatie met behulp van op rollen gebaseerd toegangsbeheer. We raden deze methode aan via toegangsbeleid voor Key Vault. Zie Toegang verlenen tot Key Vault-sleutels, -certificaten en -geheimen met behulp van Azure-rollen voor meer informatie.
In deze stap wijst u de rol Key Vault Crypto Service Encryption User toe aan uw zoekservice. Als u lokaal test, wijst u deze rol ook aan uzelf toe.
Meld u aan bij Azure Portal en zoek uw sleutelkluis.
Selecteer Toegangsbeheer (IAM) en selecteer Roltoewijzing toevoegen.
Selecteer Key Vault Crypto Service Encryption User en selecteer Vervolgens.
Selecteer beheerde identiteiten, selecteer leden en selecteer vervolgens de beheerde identiteit van uw zoekservice.
Selecteer Controleren + Toewijzen.
Wacht enkele minuten totdat de roltoewijzing operationeel is geworden.
Stap 4: Inhoud versleutelen
Versleutelingssleutels worden toegevoegd wanneer u een object maakt. Als u een door de klant beheerde sleutel wilt toevoegen aan een index, synoniementoewijzing, indexeerfunctie, gegevensbron of vaardighedenset, gebruikt u Azure Portal, een Search REST API of een Azure SDK om een object te maken waarvoor versleuteling is ingeschakeld. Zie het Python-voorbeeld in dit artikel om versleuteling toe te voegen met behulp van de Azure SDK.
Roep de aanmaak-API's aan om de eigenschap encryptionKey op te geven:
Voeg de encryptionKey-constructie in de objectdefinitie in. Deze eigenschap is een eigenschap op het eerste niveau, op hetzelfde niveau als de naam en beschrijving. Als u dezelfde kluis, sleutel en versie gebruikt, kunt u dezelfde encryptionKey-constructie in elke objectdefinitie plakken.
In het eerste voorbeeld ziet u een encryptionKey voor een zoekservice die verbinding maakt met behulp van een beheerde identiteit:
{ "encryptionKey": { "keyVaultUri": "<YOUR-KEY-VAULT-URI>", "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>", "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>" } }Het tweede voorbeeld bevat accessCredentials, die nodig zijn als u een toepassing hebt geregistreerd in Microsoft Entra-id:
{ "encryptionKey": { "keyVaultUri": "<YOUR-KEY-VAULT-URI>", "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>", "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>", "accessCredentials": { "applicationId": "<YOUR-APPLICATION-ID>", "applicationSecret": "<YOUR-APPLICATION-SECRET>" } } }Controleer of de versleutelingssleutel bestaat door een GET op het object uit te geven.
Controleer of het object operationeel is door een taak uit te voeren, zoals een query uitvoeren op een index die is versleuteld.
Zodra u het versleutelde object in de zoekservice hebt gemaakt, kunt u het net als elk ander object van het type gebruiken. Versleuteling is transparant voor de gebruiker en ontwikkelaar.
Geen van deze sleutelkluisdetails wordt beschouwd als geheim en kan eenvoudig worden opgehaald door te bladeren naar de relevante Azure Key Vault-pagina in Azure Portal.
Belangrijk
Versleutelde inhoud in Azure AI Search is geconfigureerd voor het gebruik van een specifieke Azure Key Vault-sleutel met een specifieke versie. Als u de sleutel of versie wijzigt, moet het object worden bijgewerkt om het te gebruiken voordat u de vorige verwijdert. Als u dit niet doet, wordt het object onbruikbaar gemaakt. U kunt de inhoud niet ontsleutelen als de sleutel verloren gaat.
Stap 5: Versleuteling testen
Als u wilt controleren of versleuteling werkt, trekt u de versleutelingssleutel in, voert u een query uit op de index (deze moet onbruikbaar zijn) en voert u de versleutelingssleutel opnieuw in.
Gebruik Azure Portal voor deze taak.
Selecteer Objectensleutels> op de pagina Azure Key Vault.
Selecteer de sleutel die u zojuist hebt gemaakt en selecteer vervolgens Verwijderen.
Selecteer zoekbeheerindexen> op de pagina Azure AI Search.
Selecteer uw index en gebruik Search Explorer om een query uit te voeren. Er wordt een foutmelding weergegeven.
Ga terug naar de pagina Azure Key Vault-objectensleutels>.
Selecteer Verwijderde sleutels beheren.
Selecteer uw sleutel en selecteer vervolgens Herstellen.
Ga terug naar uw index in Azure AI Search en voer de query opnieuw uit. Als het goed is, ziet u zoekresultaten. Als u geen onmiddellijke resultaten ziet, wacht u een minuut en probeert u het opnieuw.
Een beleid instellen voor het afdwingen van CMK-naleving
Azure-beleid helpt bij het afdwingen van organisatiestandaarden en het beoordelen van naleving op schaal. Azure AI Search heeft een optioneel ingebouwd beleid voor het afdwingen van CMK voor de hele service.
In deze sectie stelt u het beleid in waarmee een CMK-standaard voor uw zoekservice wordt gedefinieerd. Vervolgens stelt u uw zoekservice in om dit beleid af te dwingen.
Navigeer naar het ingebouwde beleid in uw webbrowser. Toewijzen selecteren
Stel het beleidsbereik in. Schakel in de sectie Parameters alleen parameters weergeven uit en stel Effect in op Weigeren.
Tijdens de evaluatie van de aanvraag wordt een aanvraag die overeenkomt met een beleidsdefinitie voor weigeren gemarkeerd als niet-compatibel. Ervan uitgaande dat de standaard voor uw service CMK-versleuteling is, betekent 'weigeren' dat aanvragen die geen CMK-versleuteling opgeven niet compatibel zijn.
Voltooi het maken van het beleid.
Roep de Services aan- Update-API om het afdwingen van CMK-beleid op serviceniveau in te schakelen.
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"
}
}
}
Versleutelingssleutels draaien of bijwerken
U wordt aangeraden de mogelijkheden voor automatische rotatie van Azure Key Vault te gebruiken, maar u kunt ook sleutels handmatig roteren.
Wanneer u een sleutel of de bijbehorende versie wijzigt, moet elk object dat gebruikmaakt van de sleutel eerst worden bijgewerkt om de nieuwe waarden te gebruiken voordat u de oude waarden verwijdert. Anders wordt het object onbruikbaar omdat het niet kan worden ontsleuteld.
Bepaal de sleutel die wordt gebruikt door een index- of synoniemenkaart.
Maak een nieuwe sleutel in de sleutelkluis, maar laat de oorspronkelijke sleutel beschikbaar.
Werk de eigenschappen van encryptionKey op een index- of synoniemtoewijzing bij om de nieuwe waarden te gebruiken. Alleen objecten die oorspronkelijk met deze eigenschap zijn gemaakt, kunnen worden bijgewerkt om een andere waarde te gebruiken.
Schakel de vorige sleutel in de sleutelkluis uit of verwijder deze. Controleer de sleuteltoegang om te controleren of de nieuwe sleutel wordt gebruikt.
Om prestatieredenen slaat de zoekservice de sleutel maximaal enkele uren in de cache op. Als u de sleutel uitschakelt of verwijdert zonder een nieuwe sleutel op te geven, blijven query's tijdelijk werken totdat de cache verloopt. Zodra de zoekservice echter inhoud niet meer kan ontsleutelen, krijgt u het volgende bericht: 'Toegang verboden. De gebruikte querysleutel is mogelijk ingetrokken. Probeer het opnieuw.
Werken met versleutelde inhoud
Met door de klant beheerde sleutelversleuteling ziet u mogelijk latentie voor zowel indexering als query's vanwege het extra versleutelen/ontsleutelen van werk. Azure AI Search logt geen versleutelingsactiviteit, maar u kunt de toegang tot sleutels bewaken via logboekregistratie van de sleutelkluis.
U wordt aangeraden logboekregistratie in te schakelen als onderdeel van de configuratie van de sleutelkluis.
Voeg een diagnostische instelling toe in de sleutelkluis die gebruikmaakt van de werkruimte voor gegevensretentie.
Selecteer audit of allLogs voor de categorie, geef de diagnostische instelling een naam en sla deze op.
Python-voorbeeld van een configuratie van een versleutelingssleutel
In deze sectie ziet u de Python-weergave van een encryptionKey in een objectdefinitie. Dezelfde definitie is van toepassing op indexen, gegevensbronnen, vaardigheden, indexeerfuncties en synoniemenkaarten. Als u dit voorbeeld wilt proberen in uw zoekservice en sleutelkluis, downloadt u het notebook van azure-search-python-samples.
Installeer enkele pakketten.
! pip install python-dotenv
! pip install azure-core
! pip install azure-search-documents==11.5.1
! pip install azure-identity
Maak een index met een versleutelingssleutel.
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')
Haal de indexdefinitie op om te controleren of de configuratie van de versleutelingssleutel bestaat.
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}")
Laad de index met een paar documenten. Alle veldinhoud wordt beschouwd als gevoelig en wordt versleuteld op schijf met behulp van uw door de klant beheerde sleutel.
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 Cliff 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)
Voer een query uit om te bevestigen dat de index operationeel is.
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']}")
Uitvoer van de query moet resultaten opleveren die vergelijkbaar zijn met het volgende voorbeeld.
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 Cliff 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.
Omdat versleutelde inhoud wordt ontsleuteld voordat gegevens worden vernieuwd of query's worden uitgevoerd, ziet u geen visueel bewijs van versleuteling. Controleer de resourcelogboeken om te controleren of versleuteling werkt.
Volgende stappen
Als u niet bekend bent met de Azure-beveiligingsarchitectuur, raadpleegt u de Documentatie voor Azure Security en met name dit artikel: