Een zoekservice configureren om verbinding te maken met een beheerde identiteit

Note

Azure AI Zoeken is beschikbaar via de Azure-portal, REST API's en Azure-SDK's. Het vormt ook een basis voor Foundry IQ, de beheerde kennislaag die bedrijfsinhoud transformeert in herbruikbare, machtigingsbewuste knowledge bases voor agents in de Microsoft Foundry-portal.

U kunt Microsoft Entra ID beveiligingsprinciplen en roltoewijzingen gebruiken voor uitgaande verbindingen van Azure AI Zoeken naar andere Azure 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 system-toegewezen of door de gebruiker toegewezen beheerde identiteit als beveiligingsprincipaal voor uw zoekservice in een Microsoft Entra tenant. Nadat 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.

Voorwaarden

Een Azure AI Zoeken-service in elke regio op de Basic-laag of hoger.
Een Azure resource die binnenkomende aanvragen accepteert van een Microsoft Entra beveiligingsprincipal met een geldige roltoewijzing.
Als u een beheerde identiteit wilt maken, moet u eigenaar of beheerder van gebruikerstoegang zijn. Als u rollen wilt toewijzen, moet u een Eigenaar, Beheerder voor Gebruikerstoegang, Rolgebaseerde Toegangscontrolebeheerder, of lid zijn van een aangepaste rol met Microsoft.Authorization/roleAssignments/write-machtigingen.

Ondersteunde scenario's

U kunt beheerde identiteiten gebruiken voor de volgende scenario's.

Scenario	Systeem toegewezen	Gebruiker toegewezen
Verbinding maken met gegevensbronnen van de indexeerfunctie¹	Ja	Ja
** Maak verbinding met embedding- en chatcompletionmodellen in Azure OpenAI, Microsoft Foundry en Azure Functions via skills/vectorizers ²	Ja	Ja
Verbind met Azure Key Vault voor door de klant beheerde sleutels	Ja	Ja
Verbinding maken met foutopsporingssessies (gehost in Azure Storage)¹	Ja	Nee
Verbinding maken met een verrijkingscache, gehost in Azure Storage (preview)^1,3	Ja	Ja ⁴
Verbinden met een Knowledge Store (gehosted in Azure Storage)¹	Ja	Ja

¹ Voor connectiviteit tussen zoeken en opslag legt netwerkbeveiliging beperkingen op voor welk type beheerde identiteit u kunt gebruiken. Alleen een door het systeem beheerde identiteit kan worden gebruikt voor een verbinding binnen dezelfde regio met Azure Storage en deze verbinding moet worden uitgevoerd via de trusted service exception of resource-instantieregel. Zie Toegang tot een met netwerk beveiligd opslagaccount voor meer informatie.

² Verbindingen met Azure OpenAI, Foundry en Azure Functions via vaardigheden/vectorizers zijn onder andere: Custom-vaardigheid, Custom vectorizer, Azure Insluitvaardigheid van OpenAI, Azure OpenAI-vectorizer, AML-vaardigheid en Microsoft Foundry model catalog vectorizer.

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

Een door de gebruiker toegewezen beheerde identiteit ⁴ voor gebruik met verrijkingscacheverbindingen vereist een preview-REST-API (2025-11-01-preview of later) of preview-SDK-pakket. Alle andere door de gebruiker toegewezen beheerde identiteiten in deze tabel worden ondersteund in REST API-versie 2026-04-01 en hoger.

Een door het systeem beheerde identiteit maken

Een door het systeem toegewezen beheerde identiteit is een Microsoft Entra ID beveiligingsprincipaal die automatisch wordt gemaakt en gekoppeld aan een Azure-resource, zoals een Azure AI Zoeken-service.

U kunt één door het systeem toegewezen beheerde identiteit hebben voor elke zoekservice. Het is uniek voor uw zoekservice en is gedurende zijn levensduur gebonden aan de service.

Wanneer u een door het systeem toegewezen beheerde identiteit inschakelt, maakt Microsoft Entra ID een beveiligingsprincipaal voor uw zoekservice die wordt gebruikt voor verificatie bij andere Azure resources. U kunt deze identiteit vervolgens gebruiken in roltoewijzingen voor geautoriseerde toegang tot gegevens en bewerkingen.

Ga naar uw zoekservice in de Azure portal.
Selecteer Instellingen>Identiteit in het linkerdeelvenster.
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 Maak een zoekservice 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 Maak een zoekservice met een door het systeem toegewezen beheerde identiteit (Azure CLI) voor meer informatie.

Gebruik Services - Maken Of Bijwerken (REST API) om het verzoek te formuleren.

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

Het antwoord bevat een bevestiging en een object-id voor de door het systeem toegewezen beheerde identiteit.

Een door de gebruiker toegewezen beheerde identiteit maken

Een door de gebruiker toegewezen beheerde identiteit is een Azure resource die kan worden toegewezen aan abonnementen, resourcegroepen of resourcetypen.

U kunt meerdere door de gebruiker toegewezen beheerde identiteiten maken voor meer granulariteit in roltoewijzingen. U wilt bijvoorbeeld afzonderlijke identiteiten voor verschillende toepassingen en scenario's. Als onafhankelijk gemaakte en beheerde resource is deze niet gebonden aan de service zelf.

De stappen voor het instellen van een door de gebruiker toegewezen beheerde identiteit zijn als volgt:

Maak in uw Azure-abonnement een door de gebruiker toegewezen beheerde identiteit.
Koppel in uw zoekservice de door de gebruiker toegewezen beheerde identiteit aan uw zoekservice.
Maak in andere Azure services waarmee u verbinding wilt maken een roltoewijzing voor de identiteit.

Het koppelen van een door de gebruiker toegewezen beheerde identiteit aan een Azure AI Zoeken-service wordt ondersteund in de Azure-portal, REST API's voor Search Management en SDK-pakketten die de functie bieden.

Azure portal
REST API

Meld u aan bij de Azure-portal.
Selecteer in de linkerbovenhoek van uw dashboard de optie Een resource maken.
Gebruik het zoekvak om door de gebruiker toegewezen beheerde identiteit te zoeken 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.
Op de pagina van de zoekservice, selecteer Instellingen>Identiteit.
Selecteer Toevoegen op het tabblad Toegewezen gebruiker.
Selecteer het abonnement en de door de gebruiker toegewezen beheerde identiteit die u eerder hebt gemaakt.

In plaats van de Azure-portal kunt u de REST API's van Search Management gebruiken om een door de gebruiker toegewezen beheerde identiteit toe te wijzen.

Gebruik Services - Update (REST API) om de aanvraag te formuleren.

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

Stel identity.type in op het type identiteit.
- Geldige waarden zijn SystemAssigned, UserAssignedof SystemAssigned, UserAssigned voor beide.
- Een waarde van None wist alle eerder toegewezen identiteiten uit de zoekservice.
Werk identity.userAssignedIdentities bij om de details van uw door de gebruiker toegewezen beheerde identiteit op te nemen. Deze identiteit moet al bestaan voordat u deze in de aanvraag kunt opgeven.

Een rol toewijzen

Nadat 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 Connect to Azure Storage, Connect to Azure Cosmos DB of Connect to Azure SQL voor andere Azure-resources.

Ga naar uw Azure OpenAI-resource in de Azure portal.
Selecteer Toegangsbeheer in het linkermenu.
Selecteer Toevoegen en selecteer vervolgens Roltoewijzing toevoegen.
Selecteer onder FunctierollenCognitive Services OpenAI-gebruiker en selecteer Volgende.
Selecteer onder Ledenbeheerde identiteit en selecteer vervolgens Leden.
Filter op abonnement en resourcetype (zoekservices) en selecteer vervolgens de beheerde identiteit van uw zoekservice.
Selecteer Beoordelen en toewijzen.

Voorbeelden van verbindingsstringen

Denk eraan dat u uit de beschrijving van scenario's beheerde identiteiten kunt gebruiken in verbindingsreeksen naar andere Azure-bronnen. Deze sectie bevat voorbeelden.

Door het systeem toegewezen beheerde identiteitverbindingen maken gebruik van algemeen beschikbare REST API-versies. Door de gebruiker toegewezen beheerde identiteitverbindingen gebruiken REST API-versie 2026-04-01 of hoger, met uitzondering van verrijkingscacheverbindingen, waarvoor nog steeds een preview-API-versie is vereist.

Tip

U kunt de meeste van deze objecten maken in de Azure-portal, waarbij u een door het systeem of de gebruiker toegewezen beheerde identiteit opgeeft en vervolgens de JSON-definitie bekijkt om de verbindingsreeks op te halen.

Blob-gegevensbron (door het systeem beheerde identiteit):

Een indexeerfunctiegegevensbron bevat een credentials eigenschap 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.

Een door het systeem beheerde identiteit wordt aangegeven wanneer een verbindingstekenreeks de unieke resource-id is van een service of app die Microsoft Entra ID gebruikt. Een door de gebruiker toegewezen beheerde identiteit wordt opgegeven via een identity eigenschap.

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

Blob-gegevensbron (door gebruiker beheerde identiteit):

Een door de gebruiker toegewezen beheerde identiteit wordt ondersteund via de identity eigenschap op SearchIndexerDataSource met REST API-versie 2026-04-01 of hoger.

"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 (door systeem beheerde identiteit):

Een definitie van een kennisarchief bevat een verbindingsreeks voor 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 ingebouwde projectie, niet de verbindingsreeks.

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

Kennisarchief (door gebruiker beheerde identiteit):

Een door de gebruiker toegewezen beheerde identiteit wordt ondersteund via de identity eigenschap op SearchIndexerKnowledgeStore met REST API-versie 2026-04-01 of hoger.

"knowledgeStore": {
  "storageConnectionString": "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}"
  }
}

Verrijkingscache (preview):

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 Identity van uw zoekservice in de Azure-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 Azure-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 aangepaste code host.

uri is het eindpunt van de functie of app.
authResourceId geeft aan dat de zoekservice verbinding moet 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": [ ...]
}

Verbindingsvoorbeelden voor modellen

Voor verbindingen die zijn gemaakt met beheerde identiteiten, ziet u in deze sectie voorbeelden van verbindingsgegevens die door een zoekservice worden gebruikt om verbinding te maken met een model op een andere resource. Een verbinding via een door het systeem beheerde identiteit is transparant; de identiteit en rollen zijn aanwezig en de verbinding slaagt als ze correct zijn geconfigureerd. Een door de gebruiker beheerde identiteit vereist daarentegen extra verbindingseigenschappen.

Azure Vaardigheid voor insluiten van OpenAI en Azure OpenAI vectorizer:

Een Azure OpenAI-insluitingsvaardigheid en vectorizer in AI Search richten zich op het eindpunt van een Azure OpenAI die een embedding-model host. Het eindpunt wordt opgegeven in de definitie van de Azure OpenAI embedding skill en/of in de definitie van de Azure OpenAI vectorizer.

De door het systeem beheerde identiteit wordt automatisch gebruikt als "apikey" en "authIdentity" leeg zijn, zoals wordt weergegeven in het volgende voorbeeld. De "authIdentity" eigenschap 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"
    }
  ]
}

Hier volgt een vectorizer-voorbeeld dat is geconfigureerd voor een door het systeem toegewezen beheerde identiteit. Een vectorizer wordt opgegeven in een zoekindex.

 "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:

Er wordt een door de gebruiker toegewezen beheerde identiteit gebruikt als "apiKey" leeg is en er een geldige "authIdentity" wordt opgegeven.

{
  "@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>"
   }
}

Hier volgt een vectorizer-voorbeeld dat is geconfigureerd voor een door de gebruiker toegewezen beheerde identiteit. Een vectorizer wordt opgegeven in een zoekindex.

 "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 of er toegang is tot de firewall

Als uw Azure-resource zich achter een firewall bevindt, controleert u of er een binnenkomende regel is waarmee aanvragen van uw zoekservice en vanuit de Azure-portal 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 vertrouwte service-uitzondering. Desgewenst kunt u een regel voor een resource-exemplaar configureren om aanvragen toe te laten.
Voor alle andere resources en verbindingen configureer een IP-firewallregel die aanvragen toestaat van Azure AI Zoeken. Zie Indexer-toegang tot inhoud die wordt beveiligd door Azure netwerkbeveiligingsfuncties voor meer informatie.

Zie ook

Feedback

Is deze pagina nuttig?

Laatst bijgewerkt om 2026-09-17