Teilen über

Tutorial: Speichern und Verwenden von Azure Cosmos DB-Anmeldeinformationen mit Azure Key Vault

  • Artikel

GILT FÜR: NoSQL MongoDB Cassandra Gremlin Tabelle

Wichtig

Es wird empfohlen, mit einer systemseitig zugewiesenen verwalteten Identität auf Azure Cosmos DB zuzugreifen. Wenn sowohl verwaltete Identitäten als auch die zertifikatbasierte Lösung nicht Ihren Anforderungen entsprechen, verwenden Sie die in diesem Artikel vorgestellte Azure Key Vault-Lösung.

Wenn Sie Azure Cosmos DB als Datenbank verwenden, stellen Sie eine Verbindung mit Datenbanken, Containern und Elementen her, indem Sie ein SDK, den API-Endpunkt und entweder den Primär- oder Sekundärschlüssel verwenden.

Es ist keine gute Praxis, den Endpunkt-URI und vertrauliche Schreib-/Leseschlüssel direkt im Anwendungscode oder in der Konfigurationsdatei zu speichern. Im Idealfall werden diese Daten aus Umgebungsvariablen innerhalb des Hosts gelesen. In Azure App Service können Sie mit App-Einstellungen Laufzeitanmeldeinformationen für Ihr Azure Cosmos DB-Konto hinterlegen, ohne dass Entwickler diese Anmeldeinformationen als unsicheren Klartext speichern müssen.

Azure Key Vault erweitert diese Best Practice, indem es Ihnen ermöglicht, die Anmeldedaten sicher zu speichern und gleichzeitig Diensten wie Azure App Service einen verwalteten Zugriff auf die Anmeldedaten zu gewähren. Azure App Service liest Ihre Anmeldeinformationen sicher aus Azure Key Vault und fügt sie in Ihre ausgeführte Anwendung ein.

Mit dieser Best Practice können Entwickler die Anmeldeinformationen für Tools wie den Azure Cosmos DB-Emulator oder die kostenlose Azure Cosmos DB-Testversion während der Entwicklung speichern. Anschließend kann das Betriebsteam sicherstellen, dass zur Laufzeit die richtigen Produktionseinstellungen eingefügt werden.

In diesem Tutorial lernen Sie Folgendes:

  • Erstellen einer Azure Key Vault-Instanz
  • Hinzufügen von Azure Cosmos DB-Anmeldeinformationen als Geheimnisse zum Schlüsseltresor
  • Erstellen und Registrieren einer Azure App Service-Ressource und Erteilen von Berechtigungen zum Lesen von Schlüsseln
  • Injizieren von Schlüsseltresorgeheimnissen in die App Service-Ressource

Hinweis

Für dieses Tutorial und die Beispielanwendung wird ein Azure Cosmos DB for NoSQL-Konto verwendet. Sie können viele dieser Schritte auch mit anderen APIs durchführen.

Voraussetzungen

Bevor Sie beginnen: Abrufen von Azure Cosmos DB-Anmeldeinformationen

Rufen Sie zunächst die Anmeldeinformationen für Ihr bestehendes Konto auf.

  1. Navigieren Sie im Azure-Portal zur Seite für das vorhandene Azure Cosmos DB for NoSQL-Konto.

  2. Wählen Sie auf der Seite für das Azure Cosmos DB for NoSQL-Konto im Navigationsmenü die Option Schlüssel aus.

    Screenshot einer Azure Cosmos DB SQL-API-Kontoseite. Die Schlüsseloption ist im Navigationsmenü hervorgehoben.

  3. Zeichnen Sie die Werte aus den Feldern von URI - und PRIMÄRSCLÜSSEL auf. Sie benötigen diese Werte im weiteren Verlauf dieses Tutorials.

    Screenshot der Schlüsselseite mit diversen Anmeldeinformationen für ein Azure Cosmos DB SQL-API-Konto.

Erstellen einer Azure Key Vault-Ressource

Erstellen Sie zunächst einen neuen Schlüsseltresor, um Ihre API for NoSQL-Anmeldeinformationen zu speichern.

  1. Melden Sie sich beim Azure-Portal an.

  2. Wählen Sie Ressource erstellen > Sicherheit > Key Vault aus.

  3. Geben Sie auf der Seite Schlüsseltresor erstellen die folgenden Informationen ein:

    Einstellung Beschreibung
    Abonnement Wählen Sie das Azure-Abonnement aus, das Sie für dieses Azure Cosmos-Konto verwenden möchten.
    Ressourcengruppe Wählen Sie eine Ressourcengruppe aus, oder wählen Sie Neu erstellen aus, und geben Sie einen eindeutigen Namen für die Ressourcengruppe ein.
    Name des Schlüsseltresors Geben Sie einen global eindeutigen Namen für Ihren Schlüsseltresor an.
    Region 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.
    Preisstufe Wählen Sie Standard aus.

  4. Behalten Sie für die übrigen Einstellungen die Standardwerte bei.

  5. Klicken Sie auf Überprüfen + erstellen.

  6. Überprüfen Sie die von Ihnen angegebenen Einstellungen, und wählen Sie dann Erstellen aus. Die Erstellung des Kontos dauert einige Minuten. Warten Sie, bis auf der Portalseite Ihre Bereitstellung ist abgeschlossen angezeigt wird, bevor sie den Vorgang fortsetzen.

Hinzufügen von Azure Cosmos DB-Zugriffsschlüsseln zu Key Vault

Speichern Sie jetzt Ihre Azure Cosmos DB-Anmeldeinformationen als Geheimnisse im Schlüsseltresor.

  1. Wählen Sie Zu Ressource wechseln, um die Azure Key Vault-Ressourcenseite aufzurufen.

  2. Wählen Sie auf der Azure Key Vault-Ressourcenseite im Navigationsmenü die Option Geheimnisse aus.

  3. Wählen Sie im Menü die Option Generieren/Importieren aus.

    Screenshot: Option „Generieren/Importieren“ im Schlüsseltresormenü

  4. Geben Sie auf der Seite Geheimnis erstellen die folgenden Informationen ein:

    Einstellung BESCHREIBUNG
    Uploadoptionen Manuell
    Name cosmos-endpoint
    Geheimniswert Geben Sie den URI ein, den Sie weiter oben in diesem Tutorial kopiert haben.

    Screenshot: Dialogfeld „Geheimnis erstellen“ im Azure-Portal mit Details zu einem URI-Geheimnis

  5. Wählen Sie Erstellen aus, um das neue Geheimnis cosmos-endpoint zu erstellen.

  6. Wählen Sie im Menü erneut Generieren/Importieren aus. Geben Sie auf der Seite Geheimnis erstellen die folgenden Informationen ein:

    Einstellung BESCHREIBUNG
    Uploadoptionen Manuell
    Name cosmos-readwrite-key
    Geheimniswert Geben Sie den PRIMÄRSCHLÜSSEL ein, den Sie weiter oben in diesem Tutorial kopiert haben.

    Screenshot: Dialogfeld „Geheimnis erstellen“ im Azure-Portal mit Details zu einem PRIMÄRSCHLÜSSEL-Geheimnis

  7. Wählen Sie Erstellen aus, um das neue Geheimnis cosmos-readwrite-key zu erstellen.

  8. Nachdem die Geheimnisse erstellt wurden, zeigen Sie sie in der Liste der Geheimnisse auf der Seite Geheimnisse an.

    Screenshot: Liste der Geheimnisse für einen Schlüsseltresor

  9. Wählen Sie jeden Schlüssel aus, wählen Sie die neueste Version aus, und kopieren Sie dann die Geheimnis-ID. Sie benötigen den Bezeichner für die Geheimnisse cosmos-endpoint und cosmos-readwrite-key später in diesem Tutorial.

    Tipp

    Die Geheimnis-ID verwendet dieses Format: https://<key-vault-name>.vault.azure.net/secrets/<secret-name>/<version-id>. Wenn beispielsweise der Name des Schlüsseltresors msdocs-key-vault lautet, der Schlüssel cosmos-readwrite-key heißt und die Version 83b995e363d947999ac6cf487ae0e12e verwendet wird, dann lautet die Geheimnis-ID https://msdocs-key-vault.vault.azure.net/secrets/cosmos-readwrite-key/83b995e363d947999ac6cf487ae0e12e.

    Screenshot: Geheimnis-ID für ein Key Vault-Geheimnis namens „cosmos-readwrite-key“

Erstellen und Registrieren einer Azure-Web-App mit Azure Key Vault

In diesem Abschnitt erstellen Sie eine neue Azure-Web-App, stellen eine Beispielanwendung bereit und registrieren dann die verwaltete Identität der Web-App bei Azure Key Vault.

  1. Erstellen Sie mithilfe der Vorlage cosmos-db-nosql-dotnet-sample-web-environment-variables ein neues GitHub-Repository.

  2. Wählen Sie im Azure-Portal die Option Ressource erstellen > Web > Web-App aus.

  3. Geben Sie auf der Seite Web-App erstellen und auf der Registerkarte Grundlagen die folgenden Informationen ein:

    Einstellung Beschreibung
    Abonnement Wählen Sie das Azure-Abonnement aus, das Sie für dieses Azure Cosmos-Konto verwenden möchten.
    Ressourcengruppe Wählen Sie eine Ressourcengruppe aus, oder wählen Sie Neu erstellen aus, und geben Sie einen eindeutigen Namen für die Ressourcengruppe ein.
    Name Geben Sie einen global eindeutigen Namen für Ihre Web-App ein.
    Veröffentlichen Wählen Sie Code aus.
    Runtimestapel Wählen Sie .NET 6 (LTS) aus.
    Betriebssystem Wählen Sie Windows aus.
    Region 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.

  4. Behalten Sie für die übrigen Einstellungen die Standardwerte bei.

  5. Wählen Sie Weiter: Bereitstellung aus.

  6. Geben Sie auf der Registerkarte Bereitstellung die folgenden Informationen ein:

    Einstellung BESCHREIBUNG
    Continuous Deployment Wählen Sie Aktivieren aus.
    GitHub-Konto Wählen Sie Autorisieren. Befolgen Sie die Eingabeaufforderungen zum Autorisieren des GitHub-Kontos, um Azure-Leseberechtigungen für Ihr neu erstelltes GitHub-Repositorys zu erteilen.
    Organisation Wählen Sie die Organisation für Ihr neues GitHub-Repository aus.
    Repository Wählen Sie den Namen für Ihr neues GitHub-Repository aus.
    Branch Wählen Sie main aus.

  7. Klicken Sie auf Überprüfen + erstellen.

  8. Überprüfen Sie die von Ihnen angegebenen Einstellungen, und wählen Sie dann Erstellen aus. Die Erstellung des Kontos dauert einige Minuten. Warten Sie, bis auf der Portalseite Ihre Bereitstellung ist abgeschlossen angezeigt wird, bevor sie den Vorgang fortsetzen.

  9. Es kann unter Umständen einige Minuten dauern, bis die Webanwendung erstmals in der Web-App bereitgestellt wird. Wählen Sie auf der Azure Web App-Ressourcenseite Durchsuchen aus, um den Standardzustand der App anzuzeigen.

    Screenshot: Webanwendung im Standardzustand ohne Anmeldeinformationen

  10. Wählen Sie im Navigationsmenü die Option Identität aus.

  11. Wählen Sie auf der Seite Identität auf der Registerkarte Systemseitig zugewiesen den Status Ein aus, und klicken Sie dann auf Speichern.

    Screenshot: Aktivieren der systemseitig zugewiesenen verwalteten Identität auf der Seite „Identität“

Injizieren von Azure Key Vault-Geheimnissen als Azure-Web-App-Einstellungen

Abschließend fügen Sie die in Ihrem Schlüsseltresor gespeicherten Geheimnisse als App-Einstellungen in die Web-App ein. Die App-Einstellungen wiederum injizieren die Anmeldeinformationen zur Laufzeit in die Anwendung, ohne die Anmeldeinformationen im Klartext zu speichern.

  1. Kehren Sie zur Schlüsseltresorseite im Azure-Portal zurück. Wählen Sie im Navigationsmenü die Option Zugriffsrichtlinien aus.

  2. Wählen Sie auf der Seite Zugriffsrichtlinien die Menüoption Erstellen aus.

    Screenshot: Option „Erstellen“ im Menü „Zugriffsrichtlinien“

  3. Wählen Sie auf der Seite Zugriffsrichtlinie erstellen auf der Registerkarte Berechtigungen im Abschnitt Geheimnisberechtigungen die Option Abrufen aus. Klicken Sie auf Weiter.

    Screenshot: Aktivierte Geheimnisberechtigung „Abrufen“

  4. Wählen Sie auf der Registerkarte Prinzipal den Namen der Web-App, die Sie zuvor in diesem Tutorial erstellt haben. Klicken Sie auf Weiter.

    Screenshot: Verwaltete Identität einer Web-App, die einer Berechtigung zugewiesen ist

    Hinweis

    In diesem Beispielscreenshot lautet der Name der Web-App msdocs-dotnet-web.

  5. Wählen Sie erneut Weiter aus, um die Registerkarte Anwendung zu überspringen. Überprüfen Sie auf der Registerkarte Überprüfen + erstellen die von Ihnen angegebenen Einstellungen, und klicken Sie dann auf Erstellen.

  6. Kehren Sie zur Web-App-Seite im Azure-Portal zurück. Wählen Sie im Navigationsmenü die Option Konfiguration aus.

  7. Wählen Sie auf der Seite Konfiguration die Option Neue Anwendungseinstellung aus. Geben Sie im Dialogfeld Anwendungseinstellung hinzufügen/bearbeiten die folgenden Informationen ein:

    Einstellung BESCHREIBUNG
    Name CREDENTIALS__ENDPOINT
    Schlüssel Rufen Sie die Geheimnis-ID für das Geheimnis cosmos-endpoint in Ihrem Schlüsseltresor ab, das Sie weiter oben in diesem Tutorial erstellt haben. Geben Sie die ID im folgenden Format ein: @Microsoft.KeyVault(SecretUri=<secret-identifier>).

    Tipp

    Stellen Sie sicher, dass die Umgebungsvariable einen doppelten Unterstrich (__) anstelle eines einfachen Unterstrichs enthält. Der doppelte Unterstrich ist ein Schlüsseltrennzeichen, das von .NET auf allen Plattformen unterstützt wird. Weitere Informationen finden Sie unter Konfigurationsanbieter für Umgebungsvariablen.

    Hinweis

    Wenn die Geheimnis-ID beispielsweise https://msdocs-key-vault.vault.azure.net/secrets/cosmos-endpoint/69621c59ef5b4b7294b5def118921b07 lautet, dann lautet der Verweis @Microsoft.KeyVault(SecretUri=https://msdocs-key-vault.vault.azure.net/secrets/cosmos-endpoint/69621c59ef5b4b7294b5def118921b07).

    Screenshot: Dialogfeld „Anwendungseinstellungen hinzufügen/bearbeiten“ mit einer neuen Anwendungseinstellung, die auf ein Schlüsseltresorgeheimnis verweist

  8. Wählen Sie OK aus, um die neue App-Einstellung zu speichern.

  9. Wählen Sie erneut Neue Anwendungseinstellung aus. Geben Sie im Dialogfeld Anwendungseinstellung hinzufügen/bearbeiten die folgenden Informationen ein, und klicken Sie dann auf OK:

    Einstellung BESCHREIBUNG
    Name CREDENTIALS__KEY
    Schlüssel Rufen Sie die Geheimnis-ID für das Geheimnis cosmos-readwrite-key in Ihrem Schlüsseltresor ab, das Sie weiter oben in diesem Tutorial erstellt haben. Geben Sie die ID im folgenden Format ein: @Microsoft.KeyVault(SecretUri=<secret-identifier>).

  10. Klicken Sie auf der Seite Konfiguration auf Speichern, um die App-Einstellungen für die Web-App zu aktualisieren.

    Screenshot: Option „Speichern“ im Menü der Seite „Konfiguration“

  11. Warten Sie einige Minuten, bis die Web-App mit den neuen App-Einstellungen neu gestartet wird. Zu diesem Zeitpunkt sollten die neuen App-Einstellungen anzeigen, dass es sich um einen Schlüsseltresorverweis handelt.

    Screenshot: Bezeichnung „Schlüsseltresorverweis“ für zwei App-Einstellungen in einer Web-App

  12. Klicken Sie im Navigationsmenü auf Übersicht. Wählen Sie Durchsuchen aus, um die App mit aufgefüllten Anmeldeinformationen anzuzeigen.

    Screenshot: Webanwendung mit gültigen Azure Cosmos DB for NoSQL-Kontoanmeldeinformationen

Nächste Schritte