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

VAN TOEPASSING OP: NoSQL MongoDB Cassandra Gremlin Tafel

Belangrijk

Het is raadzaam om toegang te krijgen tot Azure Cosmos DB door een door het systeem toegewezen beheerde identiteit te gebruiken. Als zowel de oplossing voor beheerde identiteiten als de op certificaten gebaseerde oplossing niet aan uw behoeften voldoet, gebruikt u de Azure Key Vault-oplossing in dit artikel.

Als u Azure Cosmos DB als uw 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 toepassingscode of configuratiebestand op te slaan. Idealiter worden deze gegevens gelezen uit omgevingsvariabelen binnen de host. In Azure-app Service kunt u met app-instellingen runtimereferenties injecteren voor uw Azure Cosmos DB-account zonder dat ontwikkelaars deze referenties op een onveilige, duidelijke tekst manier hoeven op te slaan.

Azure Key Vault herhaalt deze best practice verder door u in staat te stellen deze referenties veilig op te slaan terwijl u services zoals Azure-app Service beheerde toegang tot de referenties geeft. 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 toevoegen als geheimen aan de sleutelkluis
• Een Azure-app Service-resource maken en registreren en machtigingen voor 'leessleutel' verlenen
• Sleutelkluisgeheimen injecteren in de App Service-resource

Notitie

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

Vereisten

• Een bestaand Azure Cosmos DB for NoSQL-account.
  • Als u een Azure-abonnement hebt, maakt u een nieuw account.
  • Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint.
  • U kunt azure Cosmos DB ook gratis proberen voordat u zich doorvoert.
• GitHub-account.

Voordat u begint: Azure Cosmos DB-referenties ophalen

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

1. Navigeer naar de azure-portalpagina voor het bestaande Azure Cosmos DB for NoSQL-account.

2. Selecteer op de azure Cosmos DB for NoSQL-accountpagina de optie Navigatiemenu Sleutels .

   

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

   

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 het Azure-portaal.

2. Selecteer Een resourcebeveiligingssleutelkluis> > maken.

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 de portalpagina wordt weergegeven dat uw implementatie is voltooid voordat u verdergaat.

Azure Cosmos DB-toegangssleutels toevoegen aan Key Vault

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

1. Selecteer Ga naar de resource om naar de azure Key Vault-resourcepagina te gaan.

2. Selecteer op de resourcepagina van Azure Key Vault de optie Voor het navigatiemenu Geheimen .

3. Selecteer Genereren/importeren in het menu.

   

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.

   

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

6. Selecteer Genereren/importeren opnieuw 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.

   

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

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

   

9. Selecteer elke sleutel, selecteer de nieuwste versie en kopieer de geheime id. U gebruikt de id voor het cosmos-eindpunt en cosmos-readwrite-key-geheimen verderop in deze zelfstudie.

   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. De geheime id zou dan zijnhttps://msdocs-key-vault.vault.azure.net/secrets/cosmos-readwrite-key/83b995e363d947999ac6cf487ae0e12e.

   

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 een resourceweb-web-app > >maken in Azure Portal.

3. Voer op de pagina Web-app maken en 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.
   Een GitHub-account	Selecteer Autoriseren. Volg de autorisatieprompts voor 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 de hoofdmap.

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 de portalpagina wordt weergegeven dat uw implementatie is voltooid voordat u verdergaat.

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

   

10. Selecteer de menuoptie Identiteitsnavigatie .

11. Selecteer Op de pagina Identiteit de optie Aan voor door het systeem toegewezen beheerde identiteit en selecteer vervolgens Opslaan.

    

Azure Key Vault-geheimen als app-instellingen van Azure Web App injecteren

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

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

2. Selecteer Op de pagina Toegangsbeleid maken in het menu.

   

3. Selecteer op het tabblad Machtigingen van de pagina Een toegangsbeleid maken de optie Ophalen in de sectie Geheime machtigingen. Selecteer Volgende.

   

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

   

   Notitie

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

5. Selecteer Volgende opnieuw 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 met web-apps in Azure Portal. Selecteer Configuratie in het navigatiemenu.

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

   Instelling	Omschrijving
   Naam	CREDENTIALS__ENDPOINT
   Code	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 belangrijke delimeter die wordt ondersteund door .NET op alle platforms. Zie de configuratie van omgevingsvariabelen voor meer informatie.

   Notitie

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

   

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

9. Selecteer de instelling Nieuwe toepassing opnieuw. Voer in het dialoogvenster Toepassingsinstelling toevoegen/bewerken de volgende informatie in en selecteer VERVOLGENS OK:

   Instelling	Omschrijving
   Naam	CREDENTIALS__KEY
   Code	Haal de geheime id op voor het cosmos-readwrite-key-geheim 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.

    

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 naslaginformatie voor key vault zijn.

    

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

    

Volgende stappen

• Als u een firewall voor Azure Cosmos DB wilt configureren, raadpleegt u het artikel over firewallondersteuning .
• Zie het artikel over het VNet-service-eindpunt om service-eindpunten voor virtuele netwerken te configureren.