Konfigurera en söktjänst för att ansluta med hjälp av en hanterad identitet i Azure AI Search

Artikel
07/25/2024

Viktigt!

Användartilldelade hanterade identitetstilldelningar finns i offentlig förhandsversion under Kompletterande användningsvillkor. REST API för förhandsversion av hantering tillhandahåller användartilldelad hanterad identitetstilldelning för Azure AI Search. Stöd för en systemtilldelad hanterad identitet är allmänt tillgängligt.

Du kan använda Microsoft Entra-ID och rolltilldelningar för utgående anslutningar från Azure AI Search till resurser som tillhandahåller data, tillämpad AI eller vektorisering under indexering eller frågor.

Om du vill använda roller på en utgående anslutning konfigurerar du först söktjänsten så att den använder antingen en systemtilldelad eller användartilldelad hanterad identitet som säkerhetsprincip för din söktjänst i en Microsoft Entra-klientorganisation. När du har en hanterad identitet kan du tilldela roller för auktoriserad åtkomst. Hanterade identiteter och rolltilldelningar eliminerar behovet av att skicka hemligheter och autentiseringsuppgifter i en niska veze eller kod.

Förutsättningar

En söktjänst på Basic-nivån eller högre, vilken region som helst.
En Azure-resurs som accepterar inkommande begäranden från ett Microsoft Entra-säkerhetsobjekt som har en giltig rolltilldelning.

Stödda scenarier

Azure AI Search kan ansluta till andra Azure-resurser under dess systemtilldelade eller en användartilldelad hanterad identitet.

usluga pretrage konfiguration av en systemtilldelad hanterad identitet är allmänt tillgänglig.
usluga pretrage konfigurationen av en användartilldelad hanterad identitet finns i offentlig förhandsversion, under kompletterande användningsvillkor.
Dataplansanvändning för en hanterad identitet, oavsett om det är system eller användartilldelad, är allmänt tillgänglig. Om du till exempel vill ha en användartilldelad hanterad identitet på en indexerares datakällaanslutning, nyckelvalv, felsökningssession eller berikande cache kan du använda en allmänt tillgänglig REST API-version för att skapa anslutningen, förutsatt att funktionen du använder också är allmänt tillgänglig.

En systemhanterad identitet anges när en niska veze är det unika resurs-ID:t för en Microsoft Entra ID-medveten tjänst eller ett program. En användartilldelad hanterad identitet anges via en identitetsegenskap.

En söktjänst använder Azure Storage som en indexerares datakälla och som datamottagare för felsökningssessioner, cachelagring av berikning och kunskapslager. För sökfunktioner som skrivs tillbaka till lagringen behöver den hanterade identiteten en rolltilldelning för deltagare enligt beskrivningen i avsnittet "Tilldela en roll" .

Scenario	System	Användartilldelad
Indexerareanslutningar till Azure-datakällor ^{som stöds 1}	Ja	Ja
Azure Key Vault för kundhanterade nycklar	Ja	Ja
Felsökningssessioner (finns i Azure Storage)¹	Ja	Nej
Berikningscache (finns i Azure Storage) 1,^²	Ja	Ja
Knowledge Store (finns i Azure Storage) ¹	Ja	Ja
Anslutningar till Azure OpenAI eller Azure AI ³	Ja	Ja

¹ För anslutning mellan sökning och lagring medför nätverkssäkerhetskonfigurationen begränsningar för vilken typ av hanterad identitet du kan använda. Endast en systemhanterad identitet kan användas för en anslutning till lagring i samma region via undantaget för betrodda tjänster eller resursinstansregeln. Mer information finns i Åtkomst till ett nätverksskyddat lagringskonto .

² AI-söktjänsten kan för närvarande inte ansluta till tabeller på ett lagringskonto som har delad nyckelåtkomst inaktiverad.

³ Anslutningar till Azure OpenAI eller Azure AI omfattar: Anpassad kompetens, Anpassad vektoriserare, Azure OpenAI-inbäddningsfärdighet, Azure OpenAI-vektoriserare, AML-färdighet, Katalogvektoriserare för Azure AI Studio-modell, Azure AI Vision multimodala inbäddningsfärdighet, Azure AI Vision-vektoriserare.

Skapa en systemhanterad identitet

När du aktiverar en systemtilldelad hanterad identitet skapar Microsoft Entra-ID en identitet för din söktjänst som kan användas för att autentisera till andra Azure-tjänster inom samma klientorganisation. Du kan sedan använda den här identiteten i rolltilldelningar för åtkomst till data och modeller.

En systemtilldelad hanterad identitet är unik för din söktjänst och bunden till tjänsten under dess livslängd. En söktjänst kan bara ha en systemtilldelad hanterad identitet.

Logga in på Azure-portalen och leta reda på söktjänsten.
Under Inställningar väljer du Identitet.
På fliken Systemtilldelat går du till Status och väljer På.
Välj Spara.

När du har sparat inställningarna uppdateras sidan så att en objektidentifierare som har tilldelats söktjänsten visas.

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

Mer information finns i Skapa en söktjänst med en systemtilldelad hanterad identitet (Azure PowerShell.

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

Mer information finns i Skapa en söktjänst med en systemtilldelad hanterad identitet (Azure CLI).

Formulera en begäran om att skapa eller uppdatera en söktjänst.

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

Bekräftelse och en objektidentifierare för den systemhanterade identiteten returneras i svaret.

Mer information finns i Create or Update Service (Management REST API).

Skapa en användartilldelad hanterad identitet

Viktigt!

En del av det här scenariot finns i offentlig förhandsversion under kompletterande användningsvillkor. Rest-API:et för förhandsversionen av hantering tillhandahåller användartilldelad konfiguration av hanterad identitet för Azure AI Search.

En användartilldelad hanterad identitet är en resurs i Azure. Du kan skapa flera användartilldelade hanterade identiteter om du vill ha mer detaljerad information om rolltilldelningar. Du kanske till exempel vill ha separata identiteter för olika program och scenarier.

Stegen är:

Skapa en användartilldelad hanterad identitet i din Azure-prenumeration.
I söktjänsten uppdaterar du tjänstdefinitionen för att aktivera den användartilldelade hanterade identiteten (det här steget är i förhandsversion).
På andra Azure-tjänster som du vill ansluta till skapar du en rolltilldelning för identiteten.
I datakällanslutningar i Azure AI Search, till exempel en indexerares datakälla, refererar du till den användarhanterade identiteten i anslutningsinformationen (det här steget är allmänt tillgängligt om stöd för funktionen är allmänt tillgängligt).

En användartilldelad hanterad identitet kan begränsas till prenumerationer, resursgrupper eller resurstyper.

Det går att associera en användartilldelad hanterad identitet i Azure-portalen, i förhandsversioner av REST API:er för hantering och i beta-SDK-paket som tillhandahåller funktionen.

Azure-portalen
REST-API

Logga in på Azure-portalen
Välj Skapa en resurs.
I sökfältet "usluga pretrage s and marketplace" söker du efter "Användartilldelad hanterad identitet" och väljer sedan Skapa.
Välj prenumeration, resursgrupp och region. Ge identiteten ett beskrivande namn.
Välj Skapa och vänta tills resursen har distribuerats klart.

Det tar flera minuter innan du kan använda identiteten.
På söktjänstsidan går du till Inställningar och väljer Identitet.
På fliken Användartilldelade väljer du Lägg till.
Välj prenumerationen och välj sedan den användartilldelade hanterade resursen som du skapade i föregående steg.

Du kan använda rest-API:et för förhandsversionshantering i stället för portalen för att tilldela en användartilldelad hanterad identitet. Använd API-versioner 2021-04-01-preview eller senare. I det här exemplet används 2024-06-01-preview.

Formulera en begäran om att uppdatera en söktjänst.

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

Ange egenskapen "identitet" för att ange en fullständigt kvalificerad hanterad identitet:
- "type" är typen av identitet. Giltiga värden är "SystemAssigned", "UserAssigned" eller "SystemAssigned, UserAssigned" för båda. Värdet "Ingen" rensar alla tidigare tilldelade identiteter från söktjänsten.
- "userAssignedIdentities" innehåller information om den användartilldelade hanterade identiteten. Den här identiteten måste redan finnas innan du kan ange den i begäran om uppdateringstjänsten.

Tilldela en roll

När du har en hanterad identitet tilldelar du roller som bestämmer behörigheter för söktjänsten på Azure-resursen.

Läsbehörigheter krävs för indexerarens dataanslutningar och för åtkomst till en kundhanterad nyckel i Azure Key Vault.
Skrivbehörigheter krävs för AI-berikningsfunktioner som använder Azure Storage för att hantera felsökningssessionsdata, cachelagring av berikning och långsiktig innehållslagring i ett kunskapslager.

Följande steg illustrerar arbetsflödet för rolltilldelning. Det här exemplet gäller Azure OpenAI. Andra Azure-resurser finns i Ansluta till Azure Storage, Ansluta till Azure Cosmos DB eller Anslut till Azure SQL.

Logga in på Azure-portalen med ditt Azure-konto och gå till din Azure OpenAI-resurs.
Välj Åtkomstkontroll på den vänstra menyn.
Välj Lägg till och sedan Lägg till rolltilldelning.
Under Jobbfunktionsroller väljer du Cognitive Services OpenAI-användare och sedan Nästa.
Under Medlemmar väljer du Hanterad identitet och sedan Medlemmar.
Filtrera efter prenumeration och resurstyp (usluga pretrage) och välj sedan söktjänstens hanterade identitet.
Välj Granska + tilldela.

Exempel på anslutningssträngar

När en hanterad identitet har definierats för söktjänsten och fått en rolltilldelning kan utgående anslutningar ändras för att använda det unika resurs-ID:t för den andra Azure-resursen. Här följer några exempel på niska veze för olika scenarier.

Du kan använda allmänt tillgängliga REST API-versioner och Azure SDK-paket för dessa anslutningar.

Dricks

Du kan skapa de flesta av dessa objekt i Azure-portalen, ange antingen en system- eller användartilldelad hanterad identitet och sedan visa JSON-definitionen för att hämta niska veze.

Blobdatakälla (system):

En indexerares datakälla innehåller en egenskap för "autentiseringsuppgifter" som avgör hur anslutningen görs till datakällan. I följande exempel visas en niska veze som anger det unika resurs-ID:t för ett lagringskonto.

Microsoft Entra-ID autentiserar begäran med hjälp av söktjänstens systemhanterade identitet. Observera att niska veze inte innehåller någon container. I en datakällasdefinition anges ett containernamn i egenskapen "container" (visas inte), inte niska veze.

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

Blobdatakälla (användare):

En sökbegäran till Azure Storage kan också göras under en användartilldelad hanterad identitet. Användaridentiteten för söktjänsten anges i egenskapen "identitet".

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

Kunskapslager:

En definition för kunskapslager innehåller en niska veze till Azure Storage. Niska veze är det unika resurs-ID:t för ditt lagringskonto. Observera att strängen inte innehåller containrar eller tabeller i sökvägen. Dessa definieras i den inbäddade projektionsdefinitionen, inte i niska veze.

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

Berikningscache:

En indexerare skapar, använder och kommer ihåg containern som används för cachelagrade berikanden. Det är inte nödvändigt att inkludera containern i cachen niska veze. Du hittar objekt-ID:t på identitetssidan för söktjänsten i portalen.

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

Felsökningssession:

En felsökningssession körs i portalen och tar en niska veze när du startar sessionen. Du kan klistra in en sträng som liknar följande exempel.

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

Anpassad färdighet:

En anpassad färdighet riktar sig mot slutpunkten för en Azure-funktion eller app som är värd för anpassad kod. Slutpunkten anges i den anpassade färdighetsdefinitionen. Förekomsten av "authResourceId" instruerar söktjänsten att ansluta med hjälp av en hanterad identitet och skickar program-ID:t för målfunktionen eller appen i egenskapen.

{
  "@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-inbäddningsfärdighet och Azure OpenAI-vektoriserare:

En Azure OpenAI-inbäddningsfärdighet och vektoriserare i AI Search riktar in sig på slutpunkten för en Azure OpenAI-tjänst som är värd för en inbäddningsmodell. Slutpunkten anges i Azure OpenAI-inbäddningsfärdighetsdefinitionen och/eller i Azure OpenAI-vektoriserardefinitionen. Den systemhanterade identiteten används om den konfigureras och om "apikey" och "authIdentity" är tomma. Egenskapen "authIdentity" används endast för användartilldelade hanterade identiteter.

Exempel på systemhanterad identitet:

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

Exempel på användartilldelad hanterad identitet:

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

Sök efter brandväggsåtkomst

Om din Azure-resurs finns bakom en brandvägg kontrollerar du att det finns en inkommande regel som tar emot begäranden från din söktjänst.

För anslutningar i samma region till Azure Blob Storage eller Azure Data Lake Storage Gen2 använder du en systemhanterad identitet och undantaget för betrodda tjänster. Du kan också konfigurera en resursinstansregel för att ta emot begäranden.
För alla andra resurser och anslutningar konfigurerar du en IP-brandväggsregel som tar emot begäranden från Search. Mer information finns i Indexer-åtkomst till innehåll som skyddas av Azure-nätverkssäkerhetsfunktioner .

Dela via