Migrieren einer Anwendung zur Verwendung von kennwortlosen Verbindungen mit Azure Cosmos DB for NoSQL

Anwendungsanforderungen an Azure Cosmos DB for NoSQL müssen authentifiziert werden. Obwohl es mehrere Optionen für die Authentifizierung bei Azure Cosmos DB gibt, sollten Sie nach Möglichkeit kennwortlose Verbindungen in Ihren Anwendungen priorisieren. Traditionelle Authentifizierungsmethoden, die Verbindungszeichenfolgen mit Kennwörtern oder geheimen Schlüsseln verwenden, sind mit Sicherheitsrisiken und Komplikationen verbunden. Besuchen Sie den Hub für kennwortlose Verbindungen für Azure-Dienste, um mehr über die Vorteile der Umstellung auf kennwortlose Verbindungen zu erfahren.

Im folgenden Tutorial wird erklärt, wie eine vorhandene Anwendung zur Verbindung mit Azure Cosmos DB for NoSQL migriert werden kann, um kennwortlose Verbindungen anstelle einer schlüsselbasierten Lösung zu verwenden.

Konfigurieren von Rollen und Benutzern für Authentifizierung bei lokaler Entwicklung

Stellen Sie bei der lokalen Entwicklung mit kennwortloser Authentifizierung sicher, dass dem Benutzerkonto, das eine Verbindung mit Cosmos DB herstellt, eine Rolle mit den richtigen Berechtigungen zum Ausführen von Datenvorgängen zugewiesen ist. Derzeit enthält Azure Cosmos DB for NoSQL keine integrierten Rollen für Datenvorgänge. Sie können jedoch mithilfe der Azure CLI oder mit PowerShell eigene Rollen erstellen.

Rollen bestehen aus einer Sammlung von Berechtigungen oder Aktionen, die ein Benutzer ausführen darf, z. B. Lesen, Schreiben und Löschen. Weitere Informationen zum Konfigurieren der rollenbasierten Zugriffssteuerung (Role-Based Access Control, RBAC) finden Sie in der Dokumentation zur Cosmos DB-Sicherheitskonfiguration.

Erstellen der benutzerdefinierten Rolle

1. Erstellen Sie eine Rolle mit dem Befehl az role definition create. Übergeben Sie den Cosmos DB-Kontonamen und die Ressourcengruppe, gefolgt von einem JSON-Text, der die benutzerdefinierte Rolle definiert. Im folgenden Beispiel wird eine Rolle namens PasswordlessReadWrite mit Berechtigungen zum Lesen und Schreiben von Elementen in Cosmos DB-Containern erstellt. Der Bereich der Rolle wird zudem mit / auf die Kontoebene festgelegt.

   az cosmosdb sql role definition create \
       --account-name <cosmosdb-account-name> \
       --resource-group  <resource-group-name> \
       --body '{
       "RoleName": "PasswordlessReadWrite",
       "Type": "CustomRole",
       "AssignableScopes": ["/"],
       "Permissions": [{
           "DataActions": [
               "Microsoft.DocumentDB/databaseAccounts/readMetadata",
               "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*",
               "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*"
           ]
       }]
   }'
   

2. Kopieren Sie nach Abschluss des Befehls den ID-Wert aus dem Feld name, und fügen Sie ihn zur späteren Verwendung an einer beliebigen Stelle ein.

3. Weisen Sie die erstellte Rolle dem Benutzerkonto oder Dienstprinzipal zu, das bzw. der eine Verbindung mit Cosmos DB herstellt. Während der lokalen Entwicklung ist dies in der Regel Ihr eigenes Konto, das bei einem Entwicklungstool wie Visual Studio oder der Azure CLI angemeldet ist. Rufen Sie die Details Ihres Kontos mit dem Befehl az ad user ab.

   az ad user show --id "<your-email-address>"
   

4. Kopieren Sie den Wert der id-Eigenschaft aus den Ergebnissen, und fügen Sie ihn zur späteren Verwendung an einer beliebigen Stelle ein.

5. Weisen Sie die erstellte benutzerdefinierte Rolle mithilfe des Befehls az cosmosdb sql role assignment create und der zuvor kopierten IDs Ihrem Benutzerkonto zu.

   az cosmosdb sql role assignment create \
       --account-name <cosmosdb-account-name> \
       --resource-group  <resource-group-name> \
       --scope "/" \
       --principal-id <your-user-id> \
       --role-definition-id <your-custom-role-id> 
   

Lokale Anmeldung bei Azure

Stellen Sie für die lokale Entwicklung sicher, dass Sie mit demselben Microsoft Entra-Konto authentifiziert sind, dem Sie die Rolle zugewiesen haben. Sie können sich über gängige Entwicklungstools wie die Azure-Befehlszeilenschnittstelle (CLI) oder Azure PowerShell authentifizieren. Die Entwicklungstools, mit denen Sie sich authentifizieren können, variieren je nach Sprache.

Azure-Befehlszeilenschnittstelle

Melden Sie sich mit dem folgenden Befehl über die Azure-Befehlszeilenschnittstelle bei Azure an:

az login

Visual Studio

Wählen Sie oben rechts in Visual Studio die Schaltfläche Anmelden aus.

Melden Sie sich mit dem Microsoft Entra-Konto an, dem Sie zuvor eine Rolle zugewiesen haben.

Visual Studio Code

Sie müssen die Azure CLI installieren, um mit DefaultAzureCredential über Visual Studio Code arbeiten zu können.

Navigieren Sie im Hauptmenü von Visual Studio Code zu Terminal > Neues Terminal.

Melden Sie sich mit dem folgenden Befehl über die Azure-Befehlszeilenschnittstelle bei Azure an:

az login

PowerShell

Melden Sie sich mithilfe von PowerShell über den folgenden Befehl bei Azure an:

Connect-AzAccount

Migrieren des App-Codes zur Verwendung kennwortloser Verbindungen

.NET

1. Um in einer .NET-Anwendung DefaultAzureCredential zu verwenden, installieren Sie das Azure.Identity-Paket:

   dotnet add package Azure.Identity
   

2. Fügen Sie am Anfang der Datei den folgenden Code hinzu:

   using Azure.Identity;
   

3. Identifizieren Sie die Stellen in Ihrem Code, an denen ein CosmosClient-Objekt erstellt wird, um eine Verbindung mit Azure Cosmos DB herzustellen. Aktualisieren Sie Ihren Code, damit er mit dem folgenden Beispiel übereinstimmt.

   DefaultAzureCredential credential = new();
   
   using CosmosClient client = new(
       accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT"),
       tokenCredential: credential
   );
   

Go

1. Um in einer Go-Anwendung DefaultAzureCredential zu verwenden, installieren Sie das azidentity-Modul:

   go get -u github.com/Azure/azure-sdk-for-go/sdk/azidentity
   

2. Fügen Sie am Anfang der Datei den folgenden Code hinzu:

   import (
       "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
   )
   

3. Identifizieren Sie die Stellen in Ihrem Code, an denen eine Client-Instanz erstellt wird, um eine Verbindung mit Azure Cosmos DB herzustellen. Aktualisieren Sie Ihren Code wie im folgenden Beispiel gezeigt:

   cred, err := azidentity.NewDefaultAzureCredential(nil)
   if err != nil {
       // handle error
   }
   
   endpoint := os.Getenv("COSMOS_ENDPOINT")
   client, err := azblob.NewClient(endpoint, cred, nil)
   if err != nil {
       // handle error
   }
   

Java

1. Um DefaultAzureCredential in einer Java-Anwendung zu verwenden, installieren Sie das azure-identity-Paket mit einem der folgenden Ansätze:

   1. Schließen Sie die BOM-Datei ein.
   2. Schließen Sie eine direkte Abhängigkeiten ein.

2. Fügen Sie am Anfang der Datei den folgenden Code hinzu:

   import com.azure.identity.DefaultAzureCredentialBuilder;
   

3. Identifizieren Sie die Stellen in Ihrem Code, an denen ein CosmosClient oder CosmosAsyncClient Objekt erstellt wird, um eine Verbindung mit Azure Cosmos DB herzustellen. Aktualisieren Sie Ihren Code wie im folgenden Beispiel gezeigt:

   DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
       .build();
   String endpoint = System.getenv("COSMOS_ENDPOINT");
   
   CosmosClient client = new CosmosClientBuilder()
       .endpoint(endpoint)
       .credential(credential)
       .consistencyLevel(ConsistencyLevel.EVENTUAL)
       .buildClient();
   

Node.js

1. Um in einer Node.js-Anwendung DefaultAzureCredential zu verwenden, installieren Sie das @azure/identity-Paket:

   npm install --save @azure/identity
   

2. Fügen Sie am Anfang der Datei den folgenden Code hinzu:

   import { DefaultAzureCredential } from "@azure/identity";
   

3. Identifizieren Sie die Stellen in Ihrem Code, an denen ein CosmosClient-Objekt erstellt wird, um eine Verbindung mit Azure Cosmos DB herzustellen. Aktualisieren Sie Ihren Code wie im folgenden Beispiel gezeigt:

   const credential = new DefaultAzureCredential();
   const endpoint = process.env.COSMOS_ENDPOINT;
   
   const cosmosClient = new CosmosClient({ 
       endpoint, 
       aadCredentials: credential
   });
   

Python

1. Um in einer Python-Anwendung DefaultAzureCredential zu verwenden, installieren Sie das azure-identity-Paket:

   pip install azure-identity
   

2. Fügen Sie am Anfang der Datei den folgenden Code hinzu:

   from azure.identity import DefaultAzureCredential
   

3. Identifizieren Sie die Stellen in Ihrem Code, an denen ein BlobServiceClient-Objekt erstellt wird, um eine Verbindung mit Azure Blob Storage herzustellen. Aktualisieren Sie Ihren Code wie im folgenden Beispiel gezeigt:

   credential = DefaultAzureCredential()
   endpoint = os.environ["COSMOS_ENDPOINT"]
   
   client = CosmosClient(
       url = endpoint,
       credential = credential
   )
   

Lokales Ausführen der App

Führen Sie die Anwendung lokal aus, nachdem Sie diese Codeänderungen vorgenommen haben. Die neue Konfiguration sollte Ihre lokalen Anmeldeinformationen abrufen, z. B. mit der Azure CLI, mit Visual Studio oder IntelliJ. Die Rollen, die Sie Ihrem lokalen Entwicklerbenutzer in Azure zugewiesen haben, ermöglichen es Ihrer App, eine lokale Verbindung mit dem Azure-Dienst herzustellen.

Konfigurieren der Azure-Hostingumgebung

Sobald Ihre Anwendung für die Verwendung kennwortloser Verbindungen konfiguriert ist und lokal ausgeführt wird, kann sich derselbe Code nach der Bereitstellung in Azure bei Azure-Diensten authentifizieren. In den folgenden Abschnitten wird erläutert, wie Sie eine bereitgestellte Anwendung so konfigurieren, dass sie mithilfe einer verwalteten Identität eine Verbindung mit Azure Cosmos DB herstellt.

Erstellen Sie die verwaltete Identität

Sie können eine benutzerseitig zugewiesene verwaltete Identität über das Azure-Portal oder mithilfe der Azure CLI erstellen. Ihre Anwendung verwendet die Identität zur Identifizierung bei anderen Diensten.

Azure portal

1. Suchen Sie oben im Azure-Portal nach Verwaltete Identitäten. Wählen Sie das Ergebnis Verwaltete Identitäten aus.
2. Wählen Sie oben auf der Übersichtsseite Verwaltete Identitäten die Option + Erstellen aus.
3. Geben Sie auf der Registerkarte Grundlagen die folgenden Werte ein:
   • Abonnement: Wählen Sie Ihr gewünschtes Abonnement aus.
   • Ressourcengruppe: Wählen Sie Ihre gewünschte Ressourcengruppe aus.
   • Region: Wählen Sie eine Region in Ihrer Nähe aus.
   • Name: Geben Sie einen erkennbaren Namen für Ihre Identität ein, z. B. MigrationIdentity.
4. Wählen Sie am unteren Rand der Seite die Option Bewerten + erstellen aus.
5. Wenn die Überprüfungen abgeschlossen sind, wählen Sie Erstellen aus. Azure erstellt eine neue benutzerseitig zugewiesene Identität.

Nachdem die Ressource erstellt wurde, wählen Sie Zu Ressource wechseln aus, um die Details der verwalteten Identität anzuzeigen.

Azure-Befehlszeilenschnittstelle

Verwenden Sie den Befehl az identity create zum Erstellen einer benutzerseitig zugewiesenen verwalteten Identität:

az identity create --name MigrationIdentity --resource-group <your-resource-group>

Zuordnen der verwalteten Identität zu Ihrer Web-App

Sie müssen Ihre Web-App so konfigurieren, dass sie die von Ihnen erstellte verwaltete Identität verwendet. Weisen Sie die Identität Ihrer App entweder über das Azure-Portal oder mithilfe der Azure CLI zu.

Azure portal

Führen Sie im Azure-Portal die folgenden Schritte aus, um Ihrer App eine Identität zuzuordnen. Dieselben Schritte gelten für die folgenden Azure-Dienste:

• Azure Spring Apps
• Azure Container Apps
• Virtuelle Azure-Computer
• Azure Kubernetes Service

1. Navigieren Sie zur Übersichtsseite Ihrer Web-App.

2. Wählen Sie im linken Navigationsbereich Identität aus.

3. Wechseln Sie auf der Seite Identität zur Registerkarte Benutzerseitig zugewiesen.

4. Wählen Sie + Hinzufügen aus, um das Flyout Benutzerseitig zugewiesene verwaltete Identität hinzufügen zu öffnen.

5. Wählen Sie das Abonnement aus, das Sie vorher zum Erstellen der Identität verwendet haben.

6. Suchen Sie anhand des Namens nach der MigrationIdentity, und wählen Sie sie aus den Suchergebnissen aus.

7. Wählen Sie Hinzufügen aus, um die Identität Ihrer App zuzuordnen.

   

Azure-Befehlszeilenschnittstelle

Verwenden Sie die folgenden Azure CLI-Befehle, um Ihrer App eine Identität zuzuordnen:

Rufen Sie die ID der verwalteten Identität ab, die Sie mit dem Befehl az identity show erstellt haben. Kopieren Sie den Ausgabewert zur Verwendung im nächsten Schritt.

az identity show --name MigrationIdentity -g <your-identity-resource-group-name> --query id

Azure App Service

Sie können einer Azure App Service-Instanz mit dem Befehl az webapp identity assign eine verwaltete Identität zuweisen.

az webapp identity assign \
    --resource-group <resource-group-name> \
    --name <webapp-name>
    --identities <managed-identity-id>

Azure Spring Apps

Sie können einer Azure Spring Apps-Instanz mit dem Befehl az spring app identity assign eine verwaltete Identität zuweisen.

az spring app identity assign \
    --resource-group <resource-group-name> \
    --name <app-name> \
    --service <service-name>
    --user-assigned <managed-identity-id>

Azure Container Apps

Sie können einem virtuellen Computer mit dem Befehl az vm containerapp identity assign eine verwaltete Identität zuweisen.

az containerapp identity assign \
    --resource-group <resource-group-name> \
    --name <app-name>
    --user-assigned <managed-identity-id>

Azure Virtual Machines

Sie können einem virtuellen Computer mit dem Befehl az vm identity assign eine verwaltete Identität zuweisen.

az vm identity assign \
    --resource-group <resource-group-name> \
    --name <virtual-machine-name>
    --identities <managed-identity-id>

Azure Kubernetes Service

Sie können einer Azure Kubernetes Service-Instanz mit dem Befehl az aks update eine verwaltete Identität zuweisen.

az aks update \
    --resource-group <resource-group-name> \
    --name <cluster-name> \
    --enable-managed-identity \
    --assign-identity <managed-identity-id> \
    --assign-kubelet-identity <managed-identity-id>

Zuweisen einer Rolle zur verwalteten Identität

Erteilen Sie Berechtigungen für die verwaltete Identität, indem Sie ihr die von Ihnen erstellte benutzerdefinierte Rolle mit denselben Schritten zuweisen wie bei Ihrem lokalen Entwicklungsbenutzer.

Wenn Sie eine Rolle auf der Ressourcenebene mithilfe der Azure CLI zuweisen möchten, müssen Sie zuerst die Ressourcen-ID mithilfe des Befehls az cosmosdb show abrufen. Sie können die Ausgabeeigenschaften mithilfe des Parameters --query filtern.

az cosmosdb show \
    --resource-group '<resource-group-name>' \
    --name '<cosmosdb-name>' \
    --query id

Kopieren Sie die Ausgabe-ID aus dem vorherigen Befehl. Anschließend können Sie Rollen mithilfe des Befehls az role assignment der Azure CLI zuweisen.

az role assignment create \
    --assignee "<your-managed-identity-name>" \
    --role "PasswordlessReadWrite" \
    --scope "<cosmosdb-resource-id>"

Aktualisieren des Anwendungscodes

Sie müssen Ihren Anwendungscode so konfigurieren, dass er nach der von Ihnen erstellten verwalteten Identität sucht, wenn er in Azure bereitgestellt wird. In einigen Szenarien verhindert das explizite Festlegen der verwalteten Identität für die App außerdem, dass andere Umgebungsidentitäten versehentlich erkannt und automatisch verwendet werden.

1. Kopieren Sie auf der Übersichtsseite der verwalteten Identität den Wert der Client-ID in Ihre Zwischenablage.

2. Wenden Sie die folgenden sprachspezifischen Änderungen an:

   .NET

   Erstellen Sie ein DefaultAzureCredentialOptions-Objekt, und übergeben Sie es an DefaultAzureCredential. Legen Sie die Eigenschaft ManagedIdentityClientId auf die Client-ID fest.

   DefaultAzureCredential credential = new(
       new DefaultAzureCredentialOptions
       {
           ManagedIdentityClientId = managedIdentityClientId
       });
   

   Go

   Legen Sie die Umgebungsvariable AZURE_CLIENT_ID auf die Client-ID der verwalteten Identität fest. DefaultAzureCredential liest diese Umgebungsvariable.

   Java

   Rufen Sie die Methode managedIdentityClientId auf. Übergeben Sie die Client-ID an sie.

   DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
       .managedIdentityClientId(managedIdentityClientId)
       .build();
   

   Node.js

   Erstellen Sie ein DefaultAzureCredentialClientIdOptions-Objekt, dessen Eigenschaft managedIdentityClientId auf die Client-ID festgelegt ist. Übergeben Sie dieses Objekt an den DefaultAzureCredential-Konstruktor.

   const credential = new DefaultAzureCredential({
     managedIdentityClientId
   });
   

   Python

   Legen Sie den Parameter managed_identity_client_id des DefaultAzureCredential-Konstruktors auf die Client-ID fest.

   credential = DefaultAzureCredential(
       managed_identity_client_id = managed_identity_client_id
   )
   

3. Nachdem Sie diese Änderung vorgenommen haben, stellen Sie Ihren Code in Azure erneut bereit, damit die Konfigurationsupdates angewendet werden.

Testen der App

Nachdem Sie den aktualisierten Code bereitgestellt haben, navigieren Sie im Browser zu Ihrer gehosteten Anwendung. Ihre App sollte die Verbindung mit Cosmos DB erfolgreich herstellen können. Denken Sie daran, dass es einige Minuten dauern kann, bis die Rollenzuweisungen in der Azure-Umgebung weitergegeben werden. Ihre Anwendung ist jetzt so konfiguriert, dass sie lokal und in einer Produktionsumgebung ausgeführt werden kann, ohne dass die Entwickler Geheimnisse in der Anwendung selbst verwalten müssen.

Nächste Schritte

In diesem Tutorial haben Sie gelernt, wie Sie eine Anwendung zu kennwortlosen Verbindungen migrieren.

Sie können die folgenden Ressourcen lesen, um die in diesem Artikel erläuterten Konzepte ausführlicher zu erkunden:

• Autorisieren des Zugriffs auf Blobs mithilfe von Microsoft Entra ID)
• Weitere Informationen zu .NET finden Sie unter Get started with .NET in 10 minutes (Einstieg in .NET in 10 Minuten).