Een zoekservice configureren om verbinding te maken met behulp van een beheerde identiteit in Azure AI Search

Artikel
09/11/2024

Belangrijk

Door de gebruiker toegewezen beheerde identiteittoewijzing bevindt zich in openbare preview onder aanvullende gebruiksvoorwaarden. De REST API voor beheervoorbeeld biedt door de gebruiker toegewezen beheerde identiteittoewijzing voor Azure AI Search. Ondersteuning voor een door het systeem toegewezen beheerde identiteit is algemeen beschikbaar.

U kunt Microsoft Entra-id en roltoewijzingen gebruiken voor uitgaande verbindingen van Azure AI Search naar resources die gegevens, toegepaste AI of vectorisatie bieden tijdens het indexeren of uitvoeren van query's.

Als u rollen wilt gebruiken voor een uitgaande verbinding, configureert u eerst uw zoekservice voor het gebruik van een door het systeem toegewezen of door de gebruiker toegewezen beheerde identiteit als het beveiligingsprincipe voor uw zoekservice in een Microsoft Entra-tenant. Zodra u een beheerde identiteit hebt, kunt u rollen toewijzen voor geautoriseerde toegang. Beheerde identiteiten en roltoewijzingen elimineren de noodzaak om geheimen en referenties door te geven in een verbindingsreeks of code.

Vereisten

Een zoekservice in de Basic-laag of hoger, elke regio.
Een Azure-resource die binnenkomende aanvragen accepteert van een Microsoft Entra-beveiligingsprincipal met een geldige roltoewijzing.

Ondersteunde scenario's

Azure AI Search kan verbinding maken met andere Azure-resources onder de door het systeem toegewezen of een door de gebruiker toegewezen beheerde identiteit.

Search-service configuratie van een door het systeem toegewezen beheerde identiteit is algemeen beschikbaar.
Search-service configuratie van een door de gebruiker toegewezen beheerde identiteit is in openbare preview, onder aanvullende gebruiksvoorwaarden.
Gegevensvlakgebruik van een beheerde identiteit, ongeacht of het systeem of door de gebruiker is toegewezen, is algemeen beschikbaar. Als u bijvoorbeeld een door de gebruiker toegewezen beheerde identiteit wilt op een verbinding met een indexeerfunctiegegevensbron, sleutelkluis, foutopsporingssessie of verrijkingscache, kunt u een algemeen beschikbare REST API-versie gebruiken om de verbinding te maken, ervan uitgaande dat de functie die u gebruikt ook algemeen beschikbaar is.

Een door het systeem beheerde identiteit wordt aangegeven wanneer een verbindingsreeks de unieke resource-id is van een Microsoft Entra ID-compatibele service of toepassing. Een door de gebruiker toegewezen beheerde identiteit wordt opgegeven via een 'identiteit'-eigenschap.

Een zoekservice maakt gebruik van Azure Storage als een indexeerfunctiegegevensbron en als gegevenssink voor foutopsporingssessies, verrijkingscaching en kennisarchief. Voor zoekfuncties die terugschrijven naar de opslag, heeft de beheerde identiteit een roltoewijzing inzender nodig, zoals beschreven in de sectie Een rol toewijzen.

Scenario	Systeem	Door de gebruiker toegewezen
Indexeerfunctieverbindingen met ondersteunde Azure-gegevensbronnen ¹	Ja	Ja
Azure Key Vault voor door de klant beheerde sleutels	Ja	Ja
Fouten opsporen in sessies (gehost in Azure Storage)¹	Ja	Nr.
Verrijkingscache (gehost in Azure Storage) 1,^²	Ja	Ja
Kennisarchief (gehost in Azure Storage) ¹	Ja	Ja
Verbindingen met Azure OpenAI, Azure AI Studio en Azure Functions via vaardigheden/vectorizers ³	Ja	Ja

¹ Voor connectiviteit tussen zoeken en opslag legt uw netwerkbeveiligingsconfiguratie beperkingen op voor welk type beheerde identiteit u kunt gebruiken. Alleen een door het systeem beheerde identiteit kan worden gebruikt voor een verbinding met dezelfde regio met opslag via de uitzondering van de vertrouwde service of regel voor het resource-exemplaar. Zie Toegang tot een met netwerk beveiligd opslagaccount voor meer informatie.

² AI-zoekservice kan momenteel geen verbinding maken met tabellen in een opslagaccount waarvoor gedeelde sleuteltoegang is uitgeschakeld.

³ Verbindingen met Azure OpenAI, Azure AI Studio en Azure Functions via vaardigheden/vectorizers zijn: Aangepaste vaardigheid, Aangepaste vectorizer, Azure OpenAI-insluitingsvaardigheden, Azure OpenAI vectorizer, AML-vaardigheid en Azure AI Studio-modelcatalogusvectorizer.

Een door het systeem beheerde identiteit maken

Wanneer u een door het systeem toegewezen beheerde identiteit inschakelt, maakt Microsoft Entra ID een identiteit voor uw zoekservice die kan worden gebruikt voor verificatie bij andere Azure-services binnen dezelfde tenant. U kunt deze identiteit vervolgens gebruiken in roltoewijzingen voor toegang tot gegevens en modellen.

Een door het systeem toegewezen beheerde identiteit is uniek voor uw zoekservice en is gedurende zijn levensduur gebonden aan de service. Een zoekservice kan slechts één door het systeem toegewezen beheerde identiteit hebben.

Meld u aan bij Azure Portal en zoek uw zoekservice.
Selecteer Identiteit onder Instellingen.
Selecteer op het tabblad Systeem toegewezen onder Status de optie Aan.
Selecteer Opslaan.

Nadat u de instellingen hebt opgeslagen, wordt de pagina bijgewerkt om een object-id weer te geven die is toegewezen aan uw zoekservice.

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -IdentityType SystemAssigned

Zie Een zoekservice maken met een door het systeem toegewezen beheerde identiteit (Azure PowerShell) voor meer informatie.

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --identity-type SystemAssigned

Zie Een zoekservice maken met een door het systeem toegewezen beheerde identiteit (Azure CLI) voor meer informatie.

Formuleer een aanvraag om een zoekservice te maken of bij te werken.

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2023-11-01
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "SystemAssigned"
  }
}

Bevestiging en een object-id voor de door het systeem beheerde identiteit wordt geretourneerd in het antwoord.

Zie Create or Update Service (Management REST API) voor meer informatie.

Een door de gebruiker toegewezen beheerde identiteit maken

Belangrijk

Een deel van dit scenario bevindt zich in openbare preview onder aanvullende gebruiksvoorwaarden. De REST API voor beheervoorbeeld biedt door de gebruiker toegewezen beheerde identiteitconfiguratie voor Azure AI Search.

Een door de gebruiker toegewezen beheerde identiteit is een resource in Azure. U kunt meerdere door de gebruiker toegewezen beheerde identiteiten maken als u meer granulariteit wilt in roltoewijzingen. U wilt bijvoorbeeld afzonderlijke identiteiten voor verschillende toepassingen en scenario's.

Stappen zijn:

Maak in uw Azure-abonnement een door de gebruiker toegewezen beheerde identiteit.
Werk in uw zoekservice de servicedefinitie bij om de door de gebruiker toegewezen beheerde identiteit in te schakelen (deze stap is in preview).
Maak in andere Azure-services waarmee u verbinding wilt maken een roltoewijzing voor de identiteit.
In gegevensbronverbindingen in Azure AI Search, zoals een gegevensbron voor een indexeerfunctie, verwijst u naar de door de gebruiker beheerde identiteit in de verbindingsgegevens (deze stap is algemeen beschikbaar als ondersteuning voor de functie algemeen beschikbaar is).

Een door de gebruiker toegewezen beheerde identiteit kan worden toegewezen aan abonnementen, resourcegroepen of resourcetypen.

Het koppelen van een door de gebruiker toegewezen beheerde identiteit wordt ondersteund in Azure Portal, in preview-versies van de REST API's van Management en in bèta-SDK-pakketten die de functie bieden.

Azure-portal
REST API

Meld u aan bij het Azure Portal
Selecteer Een resource maken.
Zoek in de zoekbalk 'Search-service s en marketplace' naar 'Door gebruiker toegewezen beheerde identiteit' en selecteer vervolgens Maken.
Selecteer het abonnement, de resourcegroep en de regio. Geef de identiteit een beschrijvende naam.
Selecteer Maken en wacht totdat de resource is geïmplementeerd.

Het duurt enkele minuten voordat u de identiteit kunt gebruiken.
Selecteer Identiteit op de pagina van de zoekservice onder Instellingen.
Selecteer Toevoegen op het tabblad Toegewezen gebruiker.
Kies het abonnement en selecteer vervolgens de door de gebruiker toegewezen beheerde resource die u in de vorige stap hebt gemaakt.

U kunt een PREVIEW Management REST API gebruiken in plaats van de portal om een door de gebruiker toegewezen beheerde identiteit toe te wijzen. Gebruik API-versies 2021-04-01-preview of hoger. In dit voorbeeld wordt 2024-06-01-preview gebruikt.

Formuleer een aanvraag om een zoekservice bij te werken.

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2024-06-01-preview
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/[subscription ID]/resourcegroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[name of managed identity]": {}
    }
  }
}

Stel de eigenschap 'identiteit' in om een volledig gekwalificeerde beheerde identiteit op te geven:
- 'type' is het type identiteit. Geldige waarden zijn 'SystemAssigned', 'UserAssigned' of 'SystemAssigned, UserAssigned' voor beide. De waarde None wist alle eerder toegewezen identiteiten uit de zoekservice.
- "userAssignedIdentities" bevat de details van de door de gebruiker toegewezen beheerde identiteit. Deze identiteit moet al bestaan voordat u deze kunt opgeven in de updateserviceaanvraag.

Een rol toewijzen

Zodra u een beheerde identiteit hebt, wijst u rollen toe die de zoekservicemachtigingen voor de Azure-resource bepalen.

Leesmachtigingen zijn nodig voor gegevensverbindingen van de indexeerfunctie en voor toegang tot een door de klant beheerde sleutel in Azure Key Vault.
Schrijfmachtigingen zijn nodig voor AI-verrijkingsfuncties die gebruikmaken van Azure Storage voor het hosten van foutopsporingssessiegegevens, het opslaan van verrijking in cache en langetermijnopslag van inhoud in een kennisarchief.

De volgende stappen illustreren de werkstroom voor roltoewijzing. Dit voorbeeld is bedoeld voor Azure OpenAI. Zie Verbinding maken met Azure Storage, Verbinding maken met Azure Cosmos DB of Verbinding maken met Azure SQL voor andere Azure-resources.

Meld u aan bij Azure Portal met uw Azure-account en ga naar uw Azure OpenAI-resource.
Selecteer Toegangsbeheer in het linkermenu.
Selecteer Toevoegen en selecteer vervolgens Roltoewijzing toevoegen.
Selecteer onder Functierollen voor De functie van Cognitive Services Cognitive Services OpenAI-gebruiker en selecteer vervolgens Volgende.
Selecteer onder Leden beheerde identiteit en selecteer vervolgens Leden.
Filter op abonnement en resourcetype (Search-service s) en selecteer vervolgens de beheerde identiteit van uw zoekservice.
Selecteer Controleren + toewijzen.

Voorbeelden van verbindingsreeksen

Zodra een beheerde identiteit is gedefinieerd voor de zoekservice en een roltoewijzing krijgt, kunnen uitgaande verbindingen worden gewijzigd om de unieke resource-id van de andere Azure-resource te gebruiken. Hier volgen enkele voorbeelden van verbindingsreeks s voor verschillende scenario's.

U kunt algemeen beschikbare REST API-versies en Azure SDK-pakketten voor deze verbindingen gebruiken.

Tip

U kunt de meeste van deze objecten maken in Azure Portal, een door het systeem of de gebruiker toegewezen beheerde identiteit opgeven en vervolgens de JSON-definitie weergeven om de verbindingsreeks op te halen.

Blobgegevensbron (systeem):

Een indexeerfunctiegegevensbron bevat een eigenschap referenties die bepaalt hoe de verbinding met de gegevensbron wordt gemaakt. In het volgende voorbeeld ziet u een verbindingsreeks waarin de unieke resource-id van een opslagaccount wordt opgegeven.

Microsoft Entra ID verifieert de aanvraag met behulp van de door het systeem beheerde identiteit van de zoekservice. U ziet dat de verbindingsreeks geen container bevat. In een definitie van een gegevensbron wordt een containernaam opgegeven in de eigenschap 'container' (niet weergegeven), niet de verbindingsreeks.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    }

Blobgegevensbron (gebruiker):

Een zoekaanvraag naar Azure Storage kan ook worden gedaan onder een door de gebruiker toegewezen beheerde identiteit. De gebruikersidentiteit van de zoekservice wordt opgegeven in de eigenschap 'identiteit'.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    },
  . . .
"identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
  }

Kennisarchief:

Een definitie van een kennisarchief bevat een verbindingsreeks naar Azure Storage. De verbindingsreeks is de unieke resource-id van uw opslagaccount. U ziet dat de tekenreeks geen containers of tabellen in het pad bevat. Deze worden gedefinieerd in de definitie van de ingesloten projectie, niet de verbindingsreeks.

"knowledgeStore": {
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/storage-account-name};"
}

Verrijkingscache:

Een indexeerfunctie maakt, gebruikt en onthoudt de container die wordt gebruikt voor de verrijkingen in de cache. Het is niet nodig om de container op te nemen in de cache verbindingsreeks. U vindt de object-id op de pagina Identiteit van uw zoekservice in de portal.

"cache": {
  "enableReprocessing": true,
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

Foutopsporingssessie:

Een foutopsporingssessie wordt uitgevoerd in de portal en neemt een verbindingsreeks wanneer u de sessie start. U kunt een tekenreeks plakken die vergelijkbaar is met het volgende voorbeeld.

"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",

Aangepaste vaardigheid:

Een aangepaste vaardigheid is gericht op het eindpunt van een Azure-functie of app die als host fungeert voor aangepaste code. Het eindpunt wordt opgegeven in de definitie van de aangepaste vaardigheid. De aanwezigheid van de 'authResourceId' vertelt de zoekservice verbinding te maken met behulp van een beheerde identiteit, waarbij de toepassings-id van de doelfunctie of app in de eigenschap wordt doorgegeven.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "authResourceId": "<Azure-AD-registered-application-ID>",
  "batchSize": 4,
  "context": "/document",
  "inputs": [ ... ],
  "outputs": [ ...]
}

Azure OpenAI-insluitingsvaardigheden en Azure OpenAI-vectorizer:

Een Azure OpenAI-insluitingsvaardigheid en vectorizer in AI Search richt zich op het eindpunt van een Azure OpenAI-service die als host fungeert voor een insluitmodel. Het eindpunt wordt opgegeven in de definitie van de vaardigheid voor het insluiten van vaardigheden in Azure OpenAI en/of in de Definitie van de Azure OpenAI-vectorizer. De door het systeem beheerde identiteit wordt gebruikt als deze is geconfigureerd en of de 'apikey' en 'authIdentity' leeg zijn. De eigenschap authIdentity wordt alleen gebruikt voor door de gebruiker toegewezen beheerde identiteit.

Voorbeeld van door het systeem beheerde identiteit:

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "modelName": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002",
        "modelName": "text-embedding-ada-002"
      }
    }
  ]

Voorbeeld van door de gebruiker toegewezen beheerde identiteit:

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "modelName": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ],
  "authIdentity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
   }
}

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002",
        "modelName": "text-embedding-ada-002"
        "authIdentity": {
            "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
            "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
          }
      }
    }
  ]

Controleren op firewalltoegang

Als uw Azure-resource zich achter een firewall bevindt, controleert u of er een binnenkomende regel is waarmee aanvragen van uw zoekservice worden toegegeven.

Gebruik voor verbindingen met dezelfde regio met Azure Blob Storage of Azure Data Lake Storage Gen2 een door het systeem beheerde identiteit en de uitzondering op de vertrouwde service. U kunt desgewenst een regel voor een resource-exemplaar configureren om aanvragen toe te laten.
Voor alle andere resources en verbindingen configureert u een IP-firewallregel waarmee aanvragen van Search worden toegegeven. Zie De indexeerfunctie voor toegang tot inhoud die wordt beveiligd door azure-netwerkbeveiligingsfuncties voor meer informatie.

Delen via