Esercitazione: Archiviare e usare le credenziali di Azure Cosmos DB con Azure Key Vault

  • Articolo

SI APPLICA A: NoSQL MongoDB Cassandra Gremlin Tabella

Importante

Per accedere ad Azure Cosmos DB è consigliabile usare un'identità gestita assegnata dal sistema. Se la soluzione delle identità gestite e quella basata su certificato non soddisfano le proprie esigenze, usare la soluzione con Azure Key Vault illustrata in questo articolo.

Se si usa Azure Cosmos DB come database, ci si connette a database, contenitori ed elementi usando un SDK, l'endpoint dell'API e la chiave primaria o secondaria.

Non è consigliabile archiviare l'URI dell'endpoint e le chiavi di lettura/scrittura sensibili direttamente all'interno del codice dell'applicazione o del file di configurazione. Idealmente, questi dati vengono letti dalle variabili di ambiente all'interno dell'host. In Servizio app di Azure le impostazioni dell'app consentono di inserire le credenziali di runtime per l'account Azure Cosmos DB senza che gli sviluppatori debbano archiviare queste credenziali in modo non sicuro in testo non crittografato.

Azure Key Vault migliora ulteriormente questa procedura consigliata consentendo di archiviare queste credenziali in modo sicuro e concedendo a servizi come Servizio app di Azure l'accesso gestito alle credenziali. Servizio app di Azure leggerà in modo sicuro le credenziali da Azure Key Vault e inserirà tali credenziali nell'applicazione in esecuzione.

Con questa procedura consigliata, gli sviluppatori possono archiviare le credenziali per strumenti come l'emulatore di Azure Cosmos DB o Try Azure Cosmos DB free durante la fase di sviluppo. Il team operativo può quindi assicurarsi che le impostazioni di produzione corrette vengano inserite in fase di esecuzione.

In questa esercitazione apprenderai a:

  • Creare un'istanza di Azure Key Vault
  • Aggiungere le credenziali di Azure Cosmos DB come segreti all'insieme di credenziali delle chiavi.
  • Creare e registrare una risorsa del Servizio app di Azure e concedere le autorizzazioni "chiave di lettura"
  • Inserire i segreti dell'insieme di credenziali delle chiavi nella risorsa del Servizio app

Nota

Questa esercitazione e l'applicazione di esempio usano un account Azure Cosmos DB for NoSQL. È possibile eseguire molti degli stessi passaggi anche usando altre API.

Prerequisiti

Prima di iniziare: Ottenere le credenziali di Azure Cosmos DB

Prima di iniziare si otterranno le credenziali per l'account esistente.

  1. Passare alla pagina del portale di Azure per l'account Azure Cosmos DB for NoSQL esistente.

  2. Nella pagina dell'account Azure Cosmos DB for NoSQL selezionare l'opzione del menu di spostamento Chiavi.

    Screenshot of an Azure Cosmos DB SQL API account page. The Keys option is highlighted in the navigation menu.

  3. Registrare i valori dei campi URI e PRIMARY KEY. Questi valori verranno usati più avanti nell'esercitazione.

    Screenshot of Keys page with various credentials for an Azure Cosmos DB SQL API account.

Creare una risorsa di Azure Key Vault

Per prima cosa, creare un nuovo insieme di credenziali delle chiavi in cui archiviare le credenziali dell'API per NoSQL.

  1. Accedere al portale di Azure.

  2. Selezionare Crea una risorsa > Sicurezza > Insieme di credenziali delle chiavi.

  3. Nella pagina Crea un insieme di credenziali delle chiavi immettere le informazioni seguenti:

    Impostazione Descrizione
    Abbonamento Selezionare la sottoscrizione di Azure da usare per l'account Azure Cosmos.
    Gruppo di risorse Selezionare un gruppo di risorse oppure fare clic su Crea nuovo, quindi immettere un nome univoco per il nuovo gruppo di risorse.
    Nome dell'insieme di credenziali delle chiavi Immettere un nome univoco globale per l'insieme di credenziali delle chiavi.
    Area Selezionare una posizione geografica in cui ospitare l'account Azure Cosmos DB. Usare la località più vicina agli utenti per offrire loro la massima velocità di accesso ai dati.
    Piano tariffario Selezionare Standard.

  4. Lasciare i valori predefiniti per le altre impostazioni.

  5. Selezionare Rivedi e crea.

  6. Rivedere le impostazioni fornite e quindi selezionare Crea. La creazione dell'account richiede alcuni minuti. Attendere che la pagina del portale visualizzi La distribuzione è stata completata prima di continuare.

Aggiungere chiavi di accesso di Azure Cosmos DB all'insieme di credenziali delle chiavi

Archiviare ora le credenziali di Azure Cosmos DB come segreti nell'insieme di credenziali delle chiavi.

  1. Selezionare Vai alla risorsa per passare alla pagina delle risorse di Azure Cosmos DB.

  2. Nella pagina delle risorse di Azure Key Vault selezionare l'opzione del menu di spostamento Segreti.

  3. Selezionare Genera/Importa dal menu.

    Screenshot of the Generate/Import option in a key vault menu.

  4. Nella pagina Crea un segreto immettere le informazioni seguenti:

    Impostazione Descrizione
    Opzioni di caricamento Manualee
    Nome cosmos-endpoint
    Valore del segreto Immettere l'URI copiato in precedenza in questa esercitazione.

    Screenshot of the Create a secret dialog in the Azure portal with details for an URI secret.

  5. Selezionare Crea per creare il nuovo segreto cosmos-endpoint.

  6. Selezionare di nuovo Genera/Importa dal menu. Nella pagina Crea un segreto immettere le informazioni seguenti:

    Impostazione Descrizione
    Opzioni di caricamento Manualee
    Nome cosmos-readwrite-key
    Valore del segreto Immettere il valore del campo PRIMARY KEY copiato in precedenza in questa esercitazione.

    Screenshot of the Create a secret dialog in the Azure portal with details for a PRIMARY KEY secret.

  7. Selezionare Crea per creare il nuovo segreto cosmos-readwrite-key.

  8. Dopo aver creato i segreti, visualizzarli nell'elenco dei segreti all'interno della pagina Segreti.

    Screenshot of the list of secrets for a key vault.

  9. Selezionare ogni chiave, selezionare la versione più recente e quindi copiare il valore di Identificatore segreto. Questo identificatore sarà necessario più avanti nell'esercitazione per segreti cosmos-endpoint e cosmos-readwrite-key.

    Suggerimento

    L'identificatore del segreto sarà nel formato https://<key-vault-name>.vault.azure.net/secrets/<secret-name>/<version-id>. Ad esempio, se il nome dell'insieme di credenziali delle chiavi è msdocs-key-vault, il nome della chiave è cosmos-readwrite-key e la versione è 83b995e363d947999ac6cf487ae0e12e, l'identificatore del segreto sarà https://msdocs-key-vault.vault.azure.net/secrets/cosmos-readwrite-key/83b995e363d947999ac6cf487ae0e12e.

    Screenshot of a secret identifier for a key vault secret named cosmos-readwrite-key.

Creare e registrare un'app Web di Azure con Azure Key Vault

In questa sezione si creerà una nuova app Web di Azure, si distribuirà un'applicazione di esempio e quindi si registrerà l'identità gestita dell'app Web con Azure Key Vault.

  1. Creare un nuovo repository GitHub usando il modello cosmos-db-nosql-dotnet-sample-web-environment-variables.

  2. Nel portale di Azure selezionare Crea una risorsa > Web > App Web.

  3. Nella pagina Crea app Web, all'interno della scheda Informazioni di base, immettere le informazioni seguenti:

    Impostazione Descrizione
    Abbonamento Selezionare la sottoscrizione di Azure da usare per l'account Azure Cosmos.
    Gruppo di risorse Selezionare un gruppo di risorse oppure fare clic su Crea nuovo, quindi immettere un nome univoco per il nuovo gruppo di risorse.
    Nome Immettere un nome univoco globale per l'app Web.
    Pubblicazione Selezionare Codice.
    Stack di runtime Selezionare .NET 6 (LTS).
    Sistema operativo Selezionare Windows.
    Area Selezionare una posizione geografica in cui ospitare l'account Azure Cosmos DB. Usare la località più vicina agli utenti per offrire loro la massima velocità di accesso ai dati.

  4. Lasciare i valori predefiniti per le altre impostazioni.

  5. Selezionare Successivo: Distribuzione.

  6. Nella scheda Distribuzione immettere le informazioni seguenti:

    Impostazione Descrizione
    Distribuzione continua Seleziona Abilita.
    Account GitHub Seleziona Autorizza. Seguire le richieste di autorizzazione dell'account GitHub per concedere ad Azure l'autorizzazione per leggere il repository GitHub appena creato.
    Azienda Selezionare l'organizzazione per il nuovo repository GitHub.
    Repository Selezionare il nome del nuovo repository GitHub.
    Ramo Selezionare main.

  7. Selezionare Rivedi e crea.

  8. Rivedere le impostazioni fornite e quindi selezionare Crea. La creazione dell'account richiede alcuni minuti. Attendere che la pagina del portale visualizzi La distribuzione è stata completata prima di continuare.

  9. Potrebbe essere necessario attendere qualche minuto in più per la distribuzione iniziale dell'applicazione Web nell'app Web. Nella pagina della risorsa App Web di Azure selezionare Sfoglia per visualizzare lo stato predefinito dell'app.

    Screenshot of the web application in it's default state without credentials.

  10. Selezionare l'opzione Identità nel menu di spostamento.

  11. Nella pagina Identità selezionare Attiva per l'identità gestita Assegnata dal sistema e quindi selezionare Salva.

    Screenshot of system-assigned managed identity being enabled from the Identity page.

Inserire i segreti di Azure Key Vault come impostazioni dell'app di App Web di Azure

Inserire quindi i segreti archiviati nell'insieme di credenziali delle chiavi come impostazioni dell'app all'interno dell'app Web. Le impostazioni dell'app inseriranno, a loro volta, le credenziali nell'applicazione in fase di esecuzione senza archiviare le credenziali in testo non crittografato.

  1. Tornare alla pagina dell'insieme di credenziali delle chiavi nel portale di Azure. Selezionare Criteri di accesso nel menu di spostamento.

  2. Nel menu della pagina Criteri di accesso selezionare Crea.

    Screenshot of the Create option in the Access policies menu.

  3. Nella scheda Autorizzazioni della pagina Creare un criterio di accesso selezionare l'opzione Ottieni nella sezione Autorizzazioni segrete. Selezionare Avanti.

    Screenshot of the Get permission enabled for Secret permissions.

  4. Nella scheda Entità di sicurezza selezionare il nome dell'app Web creata in precedenza in questa esercitazione. Seleziona Avanti.

    Screenshot of a web app managed identity assigned to a permission.

    Nota

    In questo screenshot di esempio l'app Web è denominata msdocs-dotnet-web.

  5. Selezionare di nuovo Avanti per ignorare la scheda Applicazione. Nella scheda Rivedi e crea rivedere le impostazioni fornite e quindi selezionare Crea.

  6. Tornare alla pagina dell'app Web nel portale di Azure. Selezionare Configurazione nel menu di spostamento.

  7. Nella pagina Configurazione selezionare Nuova impostazione applicazione. Nella finestra di dialogo Aggiungi/Modifica impostazione applicazione immettere le seguenti informazioni:

    Impostazione Description
    Nome CREDENTIALS__ENDPOINT
    Chiave Ottenere l'identificatore del segreto per cosmos-endpoint nell'insieme di credenziali delle chiavi creato in precedenza in questa esercitazione. Immettere l'identificatore nel formato seguente: @Microsoft.KeyVault(SecretUri=<secret-identifier>).

    Suggerimento

    Assicurarsi che la variabile di ambiente abbia un valore di sottolineatura doppia (__) anziché un singolo carattere di sottolineatura. Il doppio carattere di sottolineatura è un delimitatore di chiave supportato da .NET in tutte le piattaforme. Per altre informazioni, vedere Configurazione delle variabili di ambiente.

    Nota

    Se, ad esempio, l'identificatore del segreto è https://msdocs-key-vault.vault.azure.net/secrets/cosmos-endpoint/69621c59ef5b4b7294b5def118921b07, il riferimento sarà @Microsoft.KeyVault(SecretUri=https://msdocs-key-vault.vault.azure.net/secrets/cosmos-endpoint/69621c59ef5b4b7294b5def118921b07).

    Screenshot of the Add/Edit application setting dialog with a new app setting referencing a key vault secret.

  8. Selezionare OK per salvare in modo permanente la nuova impostazione dell'app

  9. Selezionare di nuovo Nuova impostazione applicazione. Nella finestra di dialogo Aggiungi/Modifica impostazione applicazione immettere le seguenti informazioni e quindi scegliere OK:

    Impostazione Description
    Nome CREDENTIALS__KEY
    Chiave Ottenere l'identificatore del segreto per cosmos-readwrite-key nell'insieme di credenziali delle chiavi creato in precedenza in questa esercitazione. Immettere l'identificatore nel formato seguente: @Microsoft.KeyVault(SecretUri=<secret-identifier>).

  10. Tornare alla pagina Configurazione e selezionare Salva per aggiornare le impostazioni dell'app Web.

    Screenshot of the Save option in the Configuration page's menu.

  11. Dopo alcuni minuti l'app Web si riavvierà con le nuove impostazioni. A questo punto, nelle nuove impostazioni dell'app dovrà essere indicato se sono Informazioni di riferimento sull'insieme di credenziali delle chiavi.

    Screenshot of the Key vault Reference designation on two app settings in a web app.

  12. Selezionare Panoramica nel menu di spostamento. Selezionare Sfoglia per visualizzare l'app con le credenziali impostate.

    Screenshot of the web application with valid Azure Cosmos DB for NoSQL account credentials.

Passaggi successivi