Verwenden verwalteter Identitäten zum Herstellen einer Verbindung mit Cosmos DB über einen virtuellen Azure-Computer

In diesem Artikel richten Sie einen virtuellen Computer ein, um mithilfe verwalteter Identitäten eine Verbindung mit Cosmos herzustellen. Azure Cosmos DB ist eine vollständig verwaltete NoSQL-Datenbank für die moderne App-Entwicklung. Verwaltete Identitäten für Azure-Ressourcen ermöglichen Ihren Anwendungen die Authentifizierung, wenn sie auf Dienste zugreifen, die die Azure AD-Authentifizierung mithilfe einer von Azure verwalteten Identität unterstützen.

Voraussetzungen

  • Grundlegende Kenntnisse im Bereich verwaltete Identitäten. Wenn Sie vor dem Fortfahren mehr über verwaltete Identitäten für Azure-Ressourcen erfahren möchten, sehen Sie sich die Übersicht über verwaltete Identitäten an.
  • Sie benötigen ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
  • Sie benötigen unter Umständen PowerShell oder die CLI.
  • Visual Studio Community Edition oder eine andere Entwicklungsumgebung Ihrer Wahl

Erstellen einer Ressourcengruppe

Erstellen Sie eine Ressourcengruppe namens mi-test. Diese Ressourcengruppe wird für alle in diesem Tutorial verwendeten Ressourcen genutzt.

Erstellen eines virtuellen Azure-Computers mit einer verwalteten Identität

Für dieses Tutorial benötigen Sie einen virtuellen Azure-Computer (Virtual Machine, VM). Erstellen Sie einen virtuellen Computer mit aktivierter systemseitig zugewiesener verwalteter Identität namens mi-vm-01. Sie können auch eine benutzerseitig zugewiesene verwaltete Identität namens mi-ua-01 in der zuvor erstellten Ressourcengruppe (mi-test) erstellen. Wenn Sie eine benutzerseitig zugewiesene verwaltete Identität verwenden, können Sie sie während der Erstellung einem virtuellen Computer zuweisen.

Erstellen eines virtuellen Computers mit einer systemseitig zugewiesenen verwalteten Identität

Zum Erstellen eines virtuellen Azure-Computers, auf dem die systemseitig zugewiesene verwaltete Identität aktiviert ist, benötigt Ihr Konto die Rollenzuweisung Mitwirkender für virtuelle Computer. Es sind keine weiteren Azure AD-Rollenzuweisungen erforderlich.

  • Suchen Sie im Azure-Portal nach Virtuelle Computer.
  • Klicken Sie auf Erstellen.
  • Geben Sie auf der Registerkarte „Grundlagen“ die erforderlichen Informationen ein.
  • Wählen Sie Weiter: Datenträger >
  • Füllen Sie die Informationen nach Bedarf weiter aus, navigieren Sie auf der Registerkarte Verwaltung zum Abschnitt Identität, und aktivieren Sie das Kontrollkästchen neben Systemseitig zugewiesene verwaltete Identität.

Image showing how to enable system assigned managed identities while creating a VM.

Weitere Informationen finden Sie in der Dokumentation zu virtuellen Azure-Computern:

Erstellen eines virtuellen Computers mit einer benutzerseitig zugewiesenen verwalteten Identität

Die folgenden Schritte zeigen, wie Sie einen virtuellen Computer erstellen, für den eine benutzerseitig zugewiesene verwaltete Identität konfiguriert ist.

Derzeit wird das Zuweisen einer systemseitig zugewiesenen verwalteten Identität während der VM-Erstellung im Azure-Portal nicht unterstützt. Es wird empfohlen, einen virtuellen Computer zu erstellen und ihm dann eine benutzerseitig zugewiesene verwaltete Identität zuzuweisen.

Konfigurieren von verwalteten Identitäten für Azure-Ressourcen auf einem virtuellen Computer über das Azure-Portal

Erstellen eines Cosmos DB-Kontos

Sie verfügen nun über einen virtuellen Computer mit einer benutzerseitig zugewiesenen verwalteten Identität oder einer systemseitig zugewiesenen verwalteten Identität. Jetzt benötigen Sie ein Cosmos DB-Konto, für das Sie Administratorrechte besitzen. Wenn Sie für dieses Tutorial ein Cosmos DB-Konto erstellen müssen, finden Sie in der Schnellstartanleitung zu Cosmos DB ausführliche Schritte dazu.

Hinweis

Verwaltete Identitäten können für den Zugriff auf alle Azure-Ressourcen verwendet werden, die die Azure Active Directory-Authentifizierung unterstützen. In diesem Tutorial wird davon ausgegangen, dass Ihr Cosmos DB-Konto wie unten dargestellt konfiguriert wird:

Einstellung Wert BESCHREIBUNG
Subscription Abonnementname Wählen Sie das Azure-Abonnement aus, das Sie für dieses Azure Cosmos-Konto verwenden möchten.
Ressourcengruppe Ressourcengruppenname Wählen Sie mi-test oder Neu erstellen aus, und geben Sie einen eindeutigen Namen für die neue Ressourcengruppe ein.
Kontoname Ein eindeutiger Name Geben Sie einen Namen ein, der Ihr Azure Cosmos-Konto identifiziert. Da documents.azure.com an den Namen angefügt wird, die Sie für die URI-Erstellung angeben, muss der Name eindeutig sein.

Der Name darf nur Kleinbuchstaben, Zahlen und den Bindestrich (-) enthalten. Er muss 3 bis 44 Zeichen umfassen.
API Der Typ des zu erstellenden Kontos Wählen Sie Core (SQL) aus, um eine Dokumentdatenbank und eine Abfrage mit SQL-Syntax zu erstellen.

Weitere Informationen zur SQL-API
Standort Die Region, die Ihren Benutzern am nächsten liegt Wählen Sie einen geografischen Standort aus, an dem Ihr Azure Cosmos DB-Konto gehostet werden soll. Verwenden Sie den Standort, der Ihren Benutzern am nächsten ist, damit sie möglichst schnell auf die Daten zugreifen können.

Hinweis

Wenn Sie Tests durchführen, sollten Sie den Rabatt für den Free-Tarif von Azure Cosmos DB anwenden. Mit dem Azure Cosmos DB-Tarif „Free“ erhalten Sie die ersten 1000 RUs/Sek. sowie 25 GB Speicher kostenlos in einem Konto. Weitere Informationen zum Tarif „Free“ Beachten Sie, dass diese Auswahl für dieses Tutorial keinen Unterschied macht.

Gewähren von Zugriff

An diesem Punkt sollte sowohl ein virtueller Computer, der mit einer verwalteten Identität konfiguriert ist, als auch ein Cosmos DB-Konto vorhanden sein. Bevor Sie fortfahren, müssen Sie der verwalteten Identität verschiedene Rollen zuweisen.

  • Gewähren Sie zunächst mithilfe der Azure RBAC Zugriff auf die Cosmos-Verwaltungsebene. Der verwalteten Identität muss die Rolle „DocumentDB-Kontomitwirkender“ zugewiesen sein, damit Datenbanken und Container erstellt werden können.

  • Darüber hinaus müssen Sie der verwalteten Identität mithilfe der Cosmos RBAC die Rolle „Mitwirkender“ zuweisen. Die genauen Schritte finden Sie weiter unten.

Hinweis

Sie verwenden die Rolle Integrierter Mitwirkender an Cosmos DB-Daten. Zum Gewähren des Zugriffs müssen Sie die Rollendefinition der Identität zuordnen. In diesem Fall ist dies die verwaltete Identität, die dem virtuellen Computer zugeordnet ist.

Derzeit steht im Azure-Portal keine Option zur Rollenzuweisung zur Verfügung.

Zugreifen auf Daten

Der Zugriff auf Cosmos unter Verwendung von verwalteten Identitäten kann mithilfe der Bibliothek „Azure.identity“ erfolgen, um die Authentifizierung in Ihrer Anwendung zu aktivieren. Sie können ManagedIdentityCredential direkt aufrufen oder DefaultAzureCredential verwenden.

Die ManagedIdentityCredential-Klasse versucht die Authentifizierung mithilfe einer verwalteten Identität, die der Bereitstellungsumgebung zugewiesen ist. Die Klasse DefaultAzureCredential durchläuft der Reihe nach verschiedene Authentifizierungsoptionen. Als zweite Authentifizierungsoption verwendet DefaultAzureCredential verwaltete Identitäten.

Im folgenden Beispiel erstellen Sie eine Datenbank, einen Container und ein Element im Container und lesen das neu erstellte Element mithilfe der systemseitig zugewiesenen verwalteten Identität des virtuellen Computers ein. Wenn Sie eine benutzerseitig zugewiesene verwaltete Identität verwenden möchten, müssen Sie die benutzerseitig zugewiesene verwaltete Identität angeben. Geben Sie dazu die Client-ID der verwalteten Identität an.

string userAssignedClientId = "<your managed identity client Id>";
var tokenCredential = new DefaultAzureCredential(new DefaultAzureCredentialOptions { ManagedIdentityClientId = userAssignedClientId });

Um das folgende Beispiel verwenden zu können, benötigen Sie die folgenden NuGet-Pakete:

  • Azure.Identity
  • Microsoft.Azure.Cosmos
  • Microsoft.Azure.Management.CosmosDB

Zusätzlich zu den oben genannten NuGet-Paketen müssen Sie Vorabversion einbeziehen aktivieren und dann Azure.ResourceManager.CosmosDB hinzufügen.

using Azure.Identity;
using Azure.ResourceManager.CosmosDB;
using Azure.ResourceManager.CosmosDB.Models;
using Microsoft.Azure.Cosmos;
using System;
using System.Threading.Tasks;

namespace MITest
{
    class Program
    {
        static async Task Main(string[] args)
        {
            var subscriptionId = "Your subscription ID";
            var resourceGroupName = "You resource group";
            var accountName = "Cosmos DB Account name";
            var databaseName = "mi-test";
            var containerName = "container01";

            var tokenCredential = new DefaultAzureCredential();

            // create the management clientSS
            var managementClient = new CosmosDBManagementClient(subscriptionId, tokenCredential);

            // create the data client
            var dataClient = new CosmosClient("https://[Account].documents.azure.com:443/", tokenCredential);

            // create a new database 
            var createDatabaseOperation = await managementClient.SqlResources.StartCreateUpdateSqlDatabaseAsync(resourceGroupName, accountName, databaseName,
                new SqlDatabaseCreateUpdateParameters(new SqlDatabaseResource(databaseName), new CreateUpdateOptions()));
            await createDatabaseOperation.WaitForCompletionAsync();

            // create a new container
            var createContainerOperation = await managementClient.SqlResources.StartCreateUpdateSqlContainerAsync(resourceGroupName, accountName, databaseName, containerName,
                new SqlContainerCreateUpdateParameters(new SqlContainerResource(containerName), new CreateUpdateOptions()));
            await createContainerOperation.WaitForCompletionAsync();


            // create a new item 
            var partitionKey = "pkey";
            var id = Guid.NewGuid().ToString();
            await dataClient.GetContainer(databaseName, containerName)
                .CreateItemAsync(new { id = id, _partitionKey = partitionKey }, new PartitionKey(partitionKey));


            // read back the item
            var pointReadResult = await dataClient.GetContainer(databaseName, containerName)
                .ReadItemAsync<dynamic>(id, new PartitionKey(partitionKey));


            // run a query
            await dataClient.GetContainer(databaseName, containerName)
                .GetItemQueryIterator<dynamic>("SELECT * FROM c")
                .ReadNextAsync();
        }
    }
}

Sprachspezifische Beispiele mit ManagedIdentityCredential:

.NET

Initialisieren Sie Ihren Cosmos DB-Client:

CosmosClient client = new CosmosClient("<account-endpoint>", new ManagedIdentityCredential());

Lesen und schreiben Sie dann Daten.

Java

Initialisieren Sie Ihren Cosmos DB-Client:

CosmosAsyncClient Client = new CosmosClientBuilder().endpoint("<account-endpoint>") .credential(new ManagedIdentityCredential()) .build();

Lesen und schreiben Sie dann Daten, wie in diesen Beispielen beschrieben.

JavaScript

Initialisieren Sie Ihren Cosmos DB-Client:

const client = new CosmosClient({ "<account-endpoint>", aadCredentials: new ManagedIdentityCredential() });

Lesen und schreiben Sie dann Daten, wie in diesen Beispielen beschrieben.

Bereinigungsschritte

  1. Wählen Sie im Portal die Ressource aus, die Sie löschen möchten.

  2. Klicken Sie auf Löschen.

  3. Bestätigen Sie den Löschvorgang, wenn Sie dazu aufgefordert werden.

Nächste Schritte

Erfahren Sie mehr über verwaltete Identitäten für Azure-Ressourcen:

Informieren Sie sich ausführlicher über Azure Cosmos DB: