Share via

Zelfstudie: Azure Cosmos DB-referenties opslaan en gebruiken met Azure Key Vault

  • Artikel

VAN TOEPASSING OP: Nosql MongoDB Cassandra Gremlin Tabel

Belangrijk

Het wordt aanbevolen om toegang te krijgen tot Azure Cosmos DB door een door het systeem toegewezen beheerde identiteit te gebruiken. Als zowel de oplossing voor beheerde identiteit als de oplossing op basis van certificaten niet aan uw behoeften voldoen, gebruikt u de Azure Key Vault-oplossing in dit artikel.

Als u Azure Cosmos DB als database gebruikt, maakt u verbinding met databases, containers en items met behulp van een SDK, het API-eindpunt en de primaire of secundaire sleutel.

Het is geen goede gewoonte om de eindpunt-URI en gevoelige lees-schrijfsleutels rechtstreeks in de toepassingscode of het configuratiebestand op te slaan. Idealiter worden deze gegevens gelezen uit omgevingsvariabelen binnen de host. In Azure App Service kunt u met app-instellingen runtimereferenties invoeren voor uw Azure Cosmos DB-account zonder dat ontwikkelaars deze referenties op een onveilige manier met tekst hoeven op te slaan.

Azure Key Vault herhaalt deze best practice verder door u in staat te stellen deze referenties veilig op te slaan en services zoals Azure App Service beheerde toegang tot de referenties te geven. Azure App Service leest uw referenties veilig uit Azure Key Vault en injecteert deze referenties in uw actieve toepassing.

Met deze best practice kunnen ontwikkelaars de referenties opslaan voor hulpprogramma's zoals de Azure Cosmos DB-emulator of Azure Cosmos DB gratis uitproberen tijdens de ontwikkeling. Vervolgens kan het operations-team ervoor zorgen dat de juiste productie-instellingen tijdens runtime worden geïnjecteerd.

In deze zelfstudie leert u het volgende:

  • Een Azure Key Vault-exemplaar maken
  • Azure Cosmos DB-referenties als geheimen toevoegen aan de sleutelkluis
  • Een Azure App Service-resource maken en registreren en machtigingen voor 'leessleutel' verlenen
  • Sleutelkluisgeheimen invoegen in de App Service-resource

Notitie

In deze zelfstudie en de voorbeeldtoepassing wordt gebruikgemaakt van een Azure Cosmos DB for NoSQL-account. U kunt veel van dezelfde stappen uitvoeren met behulp van andere API's.

Vereisten

Voordat u begint: Azure Cosmos DB-referenties ophalen

Voordat u begint, krijgt u de referenties voor uw bestaande account.

  1. Navigeer naar de pagina Azure Portal voor het bestaande Azure Cosmos DB for NoSQL-account.

  2. Selecteer op de pagina Azure Cosmos DB for NoSQL-account de optie Navigatiemenu Sleutels .

    Schermopname van een Azure Cosmos DB SQL API-accountpagina. De optie Sleutels is gemarkeerd in het navigatiemenu.

  3. Noteer de waarden uit de velden URI en PRIMAIRE SLEUTEL . U gebruikt deze waarden verderop in deze zelfstudie.

    Schermopname van de pagina Sleutels met verschillende referenties voor een Azure Cosmos DB SQL API-account.

Een Azure Key Vault-resource maken

Maak eerst een nieuwe sleutelkluis om uw API voor NoSQL-referenties op te slaan.

  1. Meld u aan bij de Azure-portal.

  2. Selecteer Een resource > maken Security > Key Vault.

  3. Voer op de pagina Sleutelkluis maken de volgende gegevens in:

    Instelling Beschrijving
    Abonnement Selecteer het Azure-abonnement dat u wilt gebruiken voor dit Azure Cosmos-account.
    Resourcegroep Selecteer een resourcegroep of selecteer Nieuwe maken en voer vervolgens een unieke naam in voor de nieuwe resourcegroep.
    Naam van sleutelkluis Voer een wereldwijd unieke naam in voor uw sleutelkluis.
    Regio Selecteer een geografische locatie waar u het Azure Cosmos DB-account wilt hosten. Gebruik de locatie die zich het dichtst bij uw gebruikers bevindt, zodat ze de snelst mogelijke toegang tot de gegevens hebben.
    Prijscategorie selecteer Standaard.

  4. Laat de overige instellingen op de standaardwaarden staan.

  5. Selecteer Controleren + maken.

  6. Controleer de instellingen die u opgeeft en selecteer vervolgens Maken. Het duurt een paar minuten om het account te maken. Wacht totdat op de portalpagina Uw implementatie is voltooid wordt weergegeven voordat u verdergaat.

Azure Cosmos DB-toegangssleutels toevoegen aan de Key Vault

Sla nu uw Azure Cosmos DB-referenties op als geheimen in de sleutelkluis.

  1. Selecteer Ga naar resource om naar de pagina Azure Key Vault resource te gaan.

  2. Selecteer op de pagina Azure Key Vault resource de optie Navigatiemenu Geheimen.

  3. Selecteer Genereren/importeren in het menu.

    Schermopname van de optie Genereren/importeren in het menu van een sleutelkluis.

  4. Voer op de pagina Een geheim maken de volgende gegevens in:

    Instelling Beschrijving
    Uploadopties Handmatig
    Naam cosmos-eindpunt
    Geheime waarde Voer de URI in die u eerder in deze zelfstudie hebt gekopieerd.

    Schermopname van het dialoogvenster Een geheim maken in de Azure Portal met details voor een URI-geheim.

  5. Selecteer Maken om het nieuwe cosmos-eindpuntgeheim te maken.

  6. Selecteer opnieuw Genereren/importeren in het menu. Voer op de pagina Een geheim maken de volgende gegevens in:

    Instelling Beschrijving
    Uploadopties Handmatig
    Naam cosmos-readwrite-key
    Geheime waarde Voer de PRIMAIRE SLEUTEL in die u eerder in deze zelfstudie hebt gekopieerd.

    Schermopname van het dialoogvenster Een geheim maken in de Azure Portal met details voor een GEHEIM PRIMAIRE SLEUTEL.

  7. Selecteer Maken om het nieuwe geheim cosmos-readwrite-key te maken.

  8. Nadat de geheimen zijn gemaakt, bekijkt u ze in de lijst met geheimen op de pagina Geheimen .

    Schermopname van de lijst met geheimen voor een sleutelkluis.

  9. Selecteer elke sleutel, selecteer de nieuwste versie en kopieer vervolgens de geheime id. Verderop in deze zelfstudie gebruikt u de id voor de geheimen cosmos-endpoint en cosmos-readwrite-key .

    Tip

    De geheime id heeft deze indeling https://<key-vault-name>.vault.azure.net/secrets/<secret-name>/<version-id>. Als de naam van de sleutelkluis bijvoorbeeld msdocs-key-vault is, is de naam van de sleutel cosmos-readwrite-key en de versie als 83b995e363d947999ac6cf487ae0e12e; dan is https://msdocs-key-vault.vault.azure.net/secrets/cosmos-readwrite-key/83b995e363d947999ac6cf487ae0e12ede geheime id .

    Schermopname van een geheime id voor een sleutelkluisgeheim met de naam cosmos-readwrite-key.

Een Azure-web-app maken en registreren met Azure Key Vault

In deze sectie maakt u een nieuwe Azure-web-app, implementeert u een voorbeeldtoepassing en registreert u vervolgens de beheerde identiteit van de web-app bij Azure Key Vault.

  1. Maak een nieuwe GitHub-opslagplaats met behulp van de sjabloon cosmos-db-nosql-dotnet-sample-web-environment-variables.

  2. Selecteer in de Azure Portal De web-app van een resource >> maken.

  3. Voer op de pagina Web-app maken en het tabblad Basisinformatie de volgende gegevens in:

    Instelling Beschrijving
    Abonnement Selecteer het Azure-abonnement dat u wilt gebruiken voor dit Azure Cosmos-account.
    Resourcegroep Selecteer een resourcegroep of selecteer Nieuwe maken en voer vervolgens een unieke naam in voor de nieuwe resourcegroep.
    Naam Voer een wereldwijd unieke naam in voor uw web-app.
    Publiceren Selecteer Code.
    Runtimestack Selecteer .NET 6 (LTS).
    Besturingssysteem Selecteer Windows.
    Regio Selecteer een geografische locatie waar u het Azure Cosmos DB-account wilt hosten. Gebruik de locatie die zich het dichtst bij uw gebruikers bevindt, zodat ze de snelst mogelijke toegang tot de gegevens hebben.

  4. Laat de overige instellingen op de standaardwaarden staan.

  5. Selecteer Volgende: Implementatie.

  6. Voer op het tabblad Implementatie de volgende gegevens in:

    Instelling Beschrijving
    Doorlopende implementatie Selecteer Inschakelen.
    GitHub-account Selecteer Autoriseren. Volg de autorisatieprompts van het GitHub-account om Azure toestemming te geven om uw zojuist gemaakte GitHub-opslagplaats te lezen.
    Organisatie Selecteer de organisatie voor uw nieuwe GitHub-opslagplaats.
    Opslagplaats Selecteer de naam van uw nieuwe GitHub-opslagplaats.
    Vertakking Selecteer hoofd.

  7. Selecteer Controleren + maken.

  8. Controleer de instellingen die u opgeeft en selecteer vervolgens Maken. Het duurt een paar minuten om het account te maken. Wacht totdat op de portalpagina Uw implementatie is voltooid wordt weergegeven voordat u verdergaat.

  9. Mogelijk moet u enkele minuten extra wachten totdat de webtoepassing in eerste instantie is geïmplementeerd in de web-app. Selecteer op de resourcepagina van De Azure Web App de optie Bladeren om de standaardstatus van de app te bekijken.

    Schermopname van de webtoepassing in de standaardstatus zonder referenties.

  10. Selecteer de menuoptie Identiteitsnavigatie .

  11. Selecteer op de pagina Identiteitde optie Aan bij Door het systeem toegewezen beheerde identiteit en selecteer vervolgens Opslaan.

    Schermopname van door het systeem toegewezen beheerde identiteit die wordt ingeschakeld op de pagina Identiteit.

Azure Key Vault-geheimen injecteren als instellingen voor Azure Web App-apps

Ten slotte injecteert u de geheimen die zijn opgeslagen in uw sleutelkluis als app-instellingen in de web-app. De app-instellingen injecteren op hun beurt de referenties in de toepassing tijdens runtime zonder de referenties in tekst op te slaan.

  1. Ga terug naar de sleutelkluispagina in de Azure Portal. Selecteer Toegangsbeleid in het navigatiemenu.

  2. Selecteer op de pagina Toegangsbeleidde optie Maken in het menu.

    Schermopname van de optie Maken in het menu Toegangsbeleid.

  3. Selecteer op het tabblad Machtigingen van de pagina Een toegangsbeleid maken de optie Ophalen in de sectie Machtigingen voor geheim . Selecteer Next.

    Schermopname van de optie Machtiging ophalen ingeschakeld voor machtigingen voor geheim.

  4. Selecteer op het tabblad Principal de naam van de web-app die u eerder in deze zelfstudie hebt gemaakt. Selecteer Next.

    Schermopname van een beheerde identiteit voor een web-app die is toegewezen aan een machtiging.

    Notitie

    In deze voorbeeldschermafbeelding heet de web-app msdocs-dotnet-web.

  5. Selecteer nogmaals Volgende om het tabblad Toepassing over te slaan. Controleer op het tabblad Controleren en maken de instellingen die u opgeeft en selecteer vervolgens Maken.

  6. Ga terug naar de pagina van de web-app in de Azure Portal. Selecteer Configuratie in het navigatiemenu.

  7. Selecteer op de pagina Configuratiede optie Nieuwe toepassingsinstelling. Voer in het dialoogvenster Toepassingsinstelling toevoegen/bewerken de volgende gegevens in:

    Instelling Beschrijving
    Naam CREDENTIALS__ENDPOINT
    Sleutel Haal de geheime id op voor het cosmos-eindpuntgeheim in uw sleutelkluis die u eerder in deze zelfstudie hebt gemaakt. Voer de id in de volgende indeling in: @Microsoft.KeyVault(SecretUri=<secret-identifier>).

    Tip

    Zorg ervoor dat de omgevingsvariabele een dubbele onderstrepingstekenwaarde (__) heeft in plaats van één onderstrepingsteken. Het dubbele onderstrepingsteken is een sleuteldelimeter die wordt ondersteund door .NET op alle platforms. Zie configuratie van omgevingsvariabelen voor meer informatie.

    Notitie

    Als de geheime id bijvoorbeeld is, is https://msdocs-key-vault.vault.azure.net/secrets/cosmos-endpoint/69621c59ef5b4b7294b5def118921b07@Microsoft.KeyVault(SecretUri=https://msdocs-key-vault.vault.azure.net/secrets/cosmos-endpoint/69621c59ef5b4b7294b5def118921b07)de verwijzing .

    Schermopname van het dialoogvenster Toepassingsinstelling toevoegen/bewerken met een nieuwe app-instelling die verwijst naar een sleutelkluisgeheim.

  8. Selecteer OK om de nieuwe app-instelling te behouden

  9. Selecteer opnieuw Nieuwe toepassingsinstelling . Voer in het dialoogvenster Toepassingsinstelling toevoegen/bewerken de volgende gegevens in en selecteer vervolgens OK:

    Instelling Beschrijving
    Naam CREDENTIALS__KEY
    Sleutel Haal de geheime id op voor het geheim cosmos-readwrite-key in uw sleutelkluis die u eerder in deze zelfstudie hebt gemaakt. Voer de id in de volgende indeling in: @Microsoft.KeyVault(SecretUri=<secret-identifier>).

  10. Selecteer opslaan op de pagina Configuratie om de app-instellingen voor de web-app bij te werken.

    Schermopname van de optie Opslaan in het menu van de pagina Configuratie.

  11. Wacht enkele minuten totdat de web-app opnieuw is opgestart met de nieuwe app-instellingen. Op dit moment moeten de nieuwe app-instellingen aangeven dat ze een key vault-verwijzing zijn.

    Schermopname van de verwijzingsaanduiding voor de sleutelkluis voor twee app-instellingen in een web-app.

  12. Selecteer Overzicht in het navigatiemenu. Selecteer Bladeren om de app met ingevulde referenties weer te geven.

    Schermopname van de webtoepassing met geldige Azure Cosmos DB voor NoSQL-accountreferenties.

Volgende stappen