Dela via

Ansluta till Azure Cosmos DB med hjälp av en hanterad identitet (Azure AI Search)

  • Artikel

Den här artikeln beskriver hur du konfigurerar en indexeraranslutning till en Azure Cosmos DB-databas med hjälp av en hanterad identitet i stället för att ange autentiseringsuppgifter i anslutningssträng."

Du kan använda en systemtilldelad hanterad identitet eller en användartilldelad hanterad identitet. Hanterade identiteter är Microsoft Entra-inloggningar och kräver Azure-rolltilldelningar för åtkomst till data i Azure Cosmos DB. Du kan också tillämpa rollbaserad åtkomst som den enda autentiseringsmetoden för dataanslutningar genom att ange disableLocalAuth till true för ditt Azure Cosmos DB för NoSQL-konto.

Förutsättningar

Metoder som stöds för autentisering av hanterad identitet

Azure AI Search stöder två mekanismer för att ansluta till Azure Cosmos DB med hjälp av hanterad identitet.

  • Den äldre metoden kräver att den hanterade identiteten konfigureras så att den har läsbehörighet på kontrollplanet för azure Cosmos DB-målkontot. Azure AI Search använder den identiteten för att hämta kontonycklarna för Cosmos DB-kontot i bakgrunden för att komma åt data. Den här metoden fungerar inte om Cosmos DB-kontot har "disableLocalAuth": true.

  • Den moderna metoden kräver att du konfigurerar lämpliga roller för den hanterade identiteten på kontroll- och dataplanet för azure Cosmos DB-målkontot. Azure AI Search begär sedan en åtkomsttoken för att få åtkomst till data i Cosmos DB-kontot. Den här metoden fungerar även om Cosmos DB-kontot har "disableLocalAuth": true.

Indexerare som ansluter till Azure Cosmos DB for NoSQL stöder både den äldre och den moderna metoden – den moderna metoden rekommenderas starkt.

Begränsningar

  • Indexerare som ansluter till Azure Cosmos DB för Gremlin och MongoDB (för närvarande i förhandsversion) stöder endast den äldre metoden.

Ansluta till Azure Cosmos DB för NoSQL

I det här avsnittet beskrivs stegen för att konfigurera anslutning till Azure Cosmos DB för NoSQL via den moderna metoden.

Konfigurera rolltilldelningar för kontrollplan

  1. Logga in för att Azure Portal och hitta ditt Cosmos DB för NoSQL-konto.

  2. Välj Åtkomstkontroll (IAM) .

  3. Välj Lägg till och välj sedan Rolltilldelning.

  4. I listan över jobbfunktionsroller väljer du Cosmos DB-kontoläsare.

  5. Välj Nästa.

  6. Välj Hanterad identitet och välj sedan Medlemmar.

  7. Filtrera efter systemtilldelade hanterade identiteter eller användartilldelade hanterade identiteter. Du bör se den hanterade identitet som du skapade tidigare för söktjänsten. Om du inte har någon kan du läsa Konfigurera sökning för att använda en hanterad identitet. Om du redan har konfigurerat en, men den inte är tillgänglig, kan du ge den några minuter.

  8. Välj identiteten och spara rolltilldelningen.

Mer information finns i Använda rollbaserad åtkomstkontroll för kontrollplan med Azure Cosmos DB för NoSQL.

Konfigurera rolltilldelningar för dataplan

Den hanterade identiteten måste tilldelas en roll för att läsa från Cosmos DB-kontots dataplan. Objekt-ID :t (huvudnamn) för söktjänstens system-/användartilldelade identitet finns på söktjänstens "identitetsflik". Det här steget kan bara utföras via Azure CLI för tillfället.

Ange variabler:

$cosmosdb_acc_name = <cosmos db account name>
$resource_group = <resource group name>
$subsciption = <subscription ID>
$system_assigned_principal = <Object (principal) ID for the search service's system/user assigned identity>
$readOnlyRoleDefinitionId = "00000000-0000-0000-0000-00000000000"
$scope=$(az cosmosdb show --name $cosmosdbname --resource-group $resourcegroup --query id --output tsv)

Definiera en rolltilldelning för den systemtilldelade identiteten:

az cosmosdb sql role assignment create --account-name $cosmosdbname --resource-group $resourcegroup --role-definition-id $readOnlyRoleDefinitionId --principal-id $sys_principal --scope $scope

Mer information finns i Använda rollbaserad åtkomstkontroll för dataplan med Azure Cosmos DB för NoSQL

Konfigurera datakällans definition

När du har konfigurerat rolltilldelningar för både kontrollplan och dataplan i Azure Cosmos DB för NoSQL-kontot kan du konfigurera en anslutning till den som fungerar under den rollen.

Indexerare använder ett datakällaobjekt för anslutningar till en extern datakälla. I det här avsnittet beskrivs hur du anger en systemtilldelad hanterad identitet eller en användartilldelad hanterad identitet på en datakälla anslutningssträng. Du hittar fler anslutningssträng exempel i artikeln hanterad identitet.

Dricks

Du kan skapa en datakällaanslutning till Cosmos DB i Azure Portal, ange antingen en system- eller användartilldelad hanterad identitet och sedan visa JSON-definitionen för att se hur anslutningssträng formuleras.

REST API, Azure Portal och .NET SDK stöder med hjälp av en systemtilldelad eller användartilldelad hanterad identitet.

Ansluta via systemtilldelad identitet

När du ansluter med en systemtilldelad hanterad identitet är den enda ändringen av datakällans definition formatet för egenskapen "autentiseringsuppgifter". Ange ett databasnamn och ett ResourceId som inte har någon kontonyckel eller lösenord. ResourceId måste innehålla prenumerations-ID för Azure Cosmos DB, resursgruppen och Azure Cosmos DB-kontonamnet.

Här är ett exempel med rest-API:et Skapa datakälla som använder den moderna metoden.

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "name": "my-cosmosdb-ds",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]" }
}

Kommentar

Om egenskapen IdentityAuthType inte ingår i anslutningssträng använder Azure AI Search som standard den äldre metoden för att säkerställa bakåtkompatibilitet.

Ansluta via användartilldelad identitet

Du måste lägga till en "identitetsegenskap" i datakällans definition, där du anger den specifika identiteten (av flera som kan tilldelas till söktjänsten), som ska användas för att ansluta till Azure Cosmos DB-kontot.

Här är ett exempel med användartilldelad identitet via den moderna metoden.

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]"},
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }
}

Ansluta till Azure Cosmos DB för Gremlin/MongoDB (förhandsversion)

I det här avsnittet beskrivs stegen för att konfigurera anslutning till Azure Cosmos DB för Gremlin/Mongo via den äldre metoden.

Konfigurera rolltilldelningar för kontrollplan

Följ samma steg som tidigare för att tilldela lämpliga roller på kontrollplanet i Azure Cosmos DB för Gremlin/MongoDB.

Ange anslutningssträngen

  • För MongoDB-samlingar lägger du till "ApiKind=MongoDb" i anslutningssträng och använder ett REST API för förhandsversion.
  • För Gremlin-grafer lägger du till "ApiKind=Gremlin" i anslutningssträng och använder ett REST API för förhandsversion.
  • För båda typerna stöds endast den äldre metoden , det vill sägs att IdentityAuthType=AccountKey om den utelämnas helt är den enda giltiga anslutningssträng.

Här är ett exempel för att ansluta till MongoDB-samlingar med hjälp av systemtilldelad identitet via REST-API:et

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "name": "my-cosmosdb-ds",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=MongoDb"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null
}

Här är ett exempel för att ansluta till Gremlin-grafer med hjälp av användartilldelad identitet.

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=Gremlin"
    },
    "container": { "name": "[my-cosmos-collection]"},
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }
}

Kör indexeraren för att verifiera behörigheter

Anslutningsinformation och behörigheter för fjärrtjänsten verifieras vid körning under indexeringskörningen. Om indexeraren lyckas är anslutningssyntaxen och rolltilldelningarna giltiga. Mer information finns i Köra eller återställa indexerare, färdigheter eller dokument.

Felsöka anslutningar

  • För Azure Cosmos DB för NoSQL kontrollerar du om kontot har begränsad åtkomst till utvalda nätverk. Du kan utesluta eventuella brandväggsproblem genom att prova anslutningen utan begränsningar. Mer information finns i Indexer-åtkomst till innehåll som skyddas av Azure-nätverkssäkerhet

  • Om indexeraren misslyckas på grund av autentiseringsproblem för Azure Cosmos DB for NoSQL kontrollerar du att rolltilldelningarna har utförts både på kontrollplanet och på dataplanet för Cosmos DB-kontot.

  • Om du nyligen roterade dina Azure Cosmos DB-kontonycklar för Gremlin eller MongoDB måste du vänta upp till 15 minuter på att den hanterade identiteten anslutningssträng ska fungera.

Se även