Eseguire la migrazione di un'applicazione per usare connessioni senza password con Azure Cosmos DB per NoSQL

Le richieste dell'applicazione ad Azure Cosmos DB per NoSQL devono essere autenticate. Anche se sono disponibili più opzioni per l'autenticazione in Azure Cosmos DB, è consigliabile assegnare la priorità alle connessioni senza password nelle applicazioni, quando possibile. I metodi di autenticazione tradizionali che usano stringa di connessione con password o chiavi segrete creano rischi e complicazioni per la sicurezza. Visitare le connessioni senza password per l'hub dei servizi di Azure per altre informazioni sui vantaggi del passaggio alle connessioni senza password.

L'esercitazione seguente illustra come eseguire la migrazione di un'applicazione esistente per connettersi ad Azure Cosmos DB per NoSQL usando connessioni senza password anziché una soluzione basata su chiavi.

Configurare ruoli e utenti per l'autenticazione di sviluppo locale

Quando si sviluppa in locale con l'autenticazione senza password, assicurarsi che all'account utente che si connette a Cosmos DB venga assegnato un ruolo con le autorizzazioni corrette per eseguire operazioni sui dati. Attualmente Azure Cosmos DB per NoSQL non include ruoli predefiniti per le operazioni sui dati, ma è possibile crearne di personalizzati usando l'interfaccia della riga di comando di Azure o PowerShell.

I ruoli sono costituiti da una raccolta di autorizzazioni o azioni che un utente può eseguire, ad esempio lettura, scrittura ed eliminazione. Per altre informazioni sulla configurazione del controllo degli accessi in base al ruolo, vedere la documentazione sulla configurazione della sicurezza di Cosmos DB.

Creare il ruolo personalizzato

1. Creare un ruolo usando il az role definition create comando . Passare il nome e il gruppo di risorse dell'account Cosmos DB, seguiti da un corpo di JSON che definisce il ruolo personalizzato. L'esempio seguente crea un ruolo denominato PasswordlessReadWrite con autorizzazioni per leggere e scrivere elementi nei contenitori Cosmos DB. Il ruolo ha anche come ambito il livello di account usando /.

   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. Al termine del comando, copiare il valore ID dal name campo e incollarlo da qualche parte per usarlo in un secondo momento.

3. Assegnare il ruolo creato all'account utente o all'entità servizio che si connetterà a Cosmos DB. Durante lo sviluppo locale, questo sarà in genere il proprio account connesso a uno strumento di sviluppo come Visual Studio o l'interfaccia della riga di comando di Azure. Recuperare i dettagli dell'account usando il az ad user comando .

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

4. Copiare il valore della id proprietà dai risultati e incollarlo da qualche parte per usarlo in un secondo momento.

5. Assegnare il ruolo personalizzato creato all'account utente usando il az cosmosdb sql role assignment create comando e gli ID copiati in precedenza.

   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> 
   

Accedere ad Azure in locale

Per lo sviluppo locale, assicurarsi di essere autenticati con lo stesso account Microsoft Entra a cui è stato assegnato il ruolo. È possibile eseguire l'autenticazione tramite strumenti di sviluppo diffusi, ad esempio l'interfaccia della riga di comando di Azure o Azure PowerShell. Gli strumenti di sviluppo con cui è possibile eseguire l'autenticazione variano a seconda dei linguaggi.

Interfaccia della riga di comando di Azure

Accedere ad Azure tramite l'interfaccia della riga di comando di Azure usando il comando seguente:

az login

Visual Studio

Selezionare il pulsante Accedi in alto a destra di Visual Studio.

Accedere usando l'account Microsoft Entra a cui è stato assegnato un ruolo in precedenza.

Visual Studio Code

È necessario installare l'interfaccia della riga di comando di Azure per usare DefaultAzureCredential Visual Studio Code.

Nel menu principale di Visual Studio Code passare a Terminale > nuovo terminale.

Accedere ad Azure tramite l'interfaccia della riga di comando di Azure usando il comando seguente:

az login

PowerShell

Accedere ad Azure usando PowerShell tramite il comando seguente:

Connect-AzAccount

Eseguire la migrazione del codice dell'app per usare connessioni senza password

.NET

1. Per usare DefaultAzureCredential in un'applicazione .NET, installare il Azure.Identity pacchetto:

   dotnet add package Azure.Identity
   

2. Nella parte superiore del file aggiungere il codice seguente:

   using Azure.Identity;
   

3. Identificare i percorsi nel codice che creano un CosmosClient oggetto per connettersi ad Azure Cosmos DB. Aggiornare il codice in modo che corrisponda all'esempio seguente.

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

Go

1. Per usare DefaultAzureCredential in un'applicazione Go, installare il azidentity modulo:

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

2. Nella parte superiore del file aggiungere il codice seguente:

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

3. Identificare i percorsi nel codice che creano un'istanza Client per connettersi ad Azure Cosmos DB. Aggiornare il codice in modo che corrisponda all'esempio seguente:

   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. Per usare DefaultAzureCredential in un'applicazione Java, installare il azure-identity pacchetto tramite uno degli approcci seguenti:

   1. Includere il file bom.
   2. Includere una dipendenza diretta.

2. Nella parte superiore del file aggiungere il codice seguente:

   import com.azure.identity.DefaultAzureCredentialBuilder;
   

3. Identificare i percorsi nel codice che creano un CosmosClient oggetto o CosmosAsyncClient per connettersi ad Azure Cosmos DB. Aggiornare il codice in modo che corrisponda all'esempio seguente:

   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. Per usare DefaultAzureCredential in un'applicazione Node.js, installare il @azure/identity pacchetto:

   npm install --save @azure/identity
   

2. Nella parte superiore del file aggiungere il codice seguente:

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

3. Identificare i percorsi nel codice che creano un CosmosClient oggetto per connettersi ad Azure Cosmos DB. Aggiornare il codice in modo che corrisponda all'esempio seguente:

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

Python

1. Per usare DefaultAzureCredential in un'applicazione Python, installare il azure-identity pacchetto:

   pip install azure-identity
   

2. Nella parte superiore del file aggiungere il codice seguente:

   from azure.identity import DefaultAzureCredential
   

3. Identificare i percorsi nel codice che creano un BlobServiceClient oggetto per connettersi a Archiviazione BLOB di Azure. Aggiornare il codice in modo che corrisponda all'esempio seguente:

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

Eseguire l'app in locale

Dopo aver apportato queste modifiche al codice, eseguire l'applicazione in locale. La nuova configurazione deve raccogliere le credenziali locali, ad esempio l'interfaccia della riga di comando di Azure, Visual Studio o IntelliJ. I ruoli assegnati all'utente di sviluppo locale in Azure consentono all'app di connettersi al servizio di Azure in locale.

Configurare l'ambiente di hosting di Azure

Dopo aver configurato l'applicazione per l'uso di connessioni senza password e l'esecuzione in locale, lo stesso codice può eseguire l'autenticazione ai servizi di Azure dopo la distribuzione in Azure. Le sezioni seguenti illustrano come configurare un'applicazione distribuita per connettersi ad Azure Cosmos DB usando un'identità gestita.

Creare l'identità gestita

È possibile creare un'identità gestita assegnata dall'utente usando il portale di Azure o l'interfaccia della riga di comando di Azure. L'applicazione usa l'identità per eseguire l'autenticazione ad altri servizi.

Azure portal

1. Nella parte superiore della portale di Azure cercare Identità gestite. Selezionare il risultato identità gestite.
2. Selezionare + Crea nella parte superiore della pagina di panoramica delle identità gestite.
3. Nella scheda Informazioni di base immettere i valori seguenti:
   • Sottoscrizione: selezionare la sottoscrizione desiderata.
   • Gruppo di risorse: selezionare il gruppo di risorse desiderato.
   • Area: selezionare un'area nelle vicinanze della località.
   • Nome: immettere un nome riconoscibile per l'identità, ad esempio MigrationIdentity.
4. Selezionare Rivedi e crea nella parte inferiore della pagina.
5. Al termine dei controlli di convalida, selezionare Crea. Azure crea una nuova identità assegnata dall'utente.

Dopo aver creato la risorsa, selezionare Vai alla risorsa per visualizzare i dettagli dell'identità gestita.

Interfaccia della riga di comando di Azure

Usare il comando az identity create per creare un'identità gestita assegnata dall'utente:

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

Associare l'identità gestita all'app Web

È necessario configurare l'app Web per usare l'identità gestita creata. Assegnare l'identità all'app usando il portale di Azure o l'interfaccia della riga di comando di Azure.

Azure portal

Completare i passaggi seguenti nella portale di Azure per associare un'identità all'app. Questi stessi passaggi si applicano ai servizi di Azure seguenti:

• Azure Spring Apps
• App contenitore di Azure
• Macchine virtuali di Azure
• Servizio Azure Kubernetes

1. Passare alla pagina di panoramica dell'app Web.

2. Selezionare Identità nel riquadro di spostamento a sinistra.

3. Nella pagina Identità passare alla scheda Assegnata dall'utente.

4. Selezionare + Aggiungi per aprire il riquadro a comparsa Aggiungi identità gestita assegnata dall'utente.

5. Selezionare la sottoscrizione usata in precedenza per creare l'identità.

6. Cercare MigrationIdentity per nome e selezionarlo nei risultati della ricerca.

7. Selezionare Aggiungi per associare l'identità all'app.

   

Interfaccia della riga di comando di Azure

Usare i comandi seguenti dell'interfaccia della riga di comando di Azure per associare un'identità all'app:

Recuperare l'ID dell'identità gestita creata usando il comando az identity show . Copiare il valore di output da usare nel passaggio successivo.

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

Servizio app di Azure

È possibile assegnare un'identità gestita a un'istanza del servizio app Azure con il comando az webapp identity assign.

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

Azure Spring Apps

È possibile assegnare un'identità gestita a un'istanza di Azure Spring Apps con il comando az spring app identity assign .

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

App azure Container

È possibile assegnare un'identità gestita a una macchina virtuale con il comando az containerapp identity assign .

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

Macchine virtuali di Azure

È possibile assegnare un'identità gestita a una macchina virtuale con il comando az vm identity assign .

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

Servizio Azure Kubernetes

È possibile assegnare un'identità gestita a un'istanza del servizio Azure Kubernetes servizio Azure Kubernetes con il comando az aks update.

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>

Assegnare ruoli all'identità gestita

Concedere le autorizzazioni all'identità gestita assegnandogli il ruolo personalizzato creato, proprio come è stato fatto con l'utente di sviluppo locale.

Per assegnare un ruolo a livello di risorsa usando l'interfaccia della riga di comando di Azure, è prima necessario recuperare l'ID risorsa usando il comando az cosmosdb show . È possibile filtrare le proprietà di output usando il --query parametro .

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

Copiare l'ID di output dal comando precedente. È quindi possibile assegnare ruoli usando il comando az role assignment dell'interfaccia della riga di comando di Azure.

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

Aggiornare il codice dell'applicazione

È necessario configurare il codice dell'applicazione per cercare l'identità gestita specifica creata quando viene distribuita in Azure. In alcuni scenari, l'impostazione esplicita dell'identità gestita per l'app impedisce anche il rilevamento accidentale e l'uso automatico di altre identità dell'ambiente.

1. Nella pagina di panoramica dell'identità gestita copiare il valore dell'ID client negli Appunti.

2. Applicare le modifiche specifiche della lingua seguenti:

   .NET

   Creare un DefaultAzureCredentialOptions oggetto e passarlo a DefaultAzureCredential. Impostare la proprietà ManagedIdentityClientId sull'ID client.

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

   Go

   Impostare la AZURE_CLIENT_ID variabile di ambiente sull'ID client dell'identità gestita. DefaultAzureCredential legge questa variabile di ambiente.

   Java

   Chiamare il metodo managedIdentityClientId . Passare l'ID client.

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

   Node.js

   Creare un DefaultAzureCredentialClientIdOptions oggetto con la proprietà managedIdentityClientId impostata sull'ID client. Passare l'oggetto DefaultAzureCredential al costruttore.

   const credential = new DefaultAzureCredential({
     managedIdentityClientId
   });
   

   Python

   Impostare il DefaultAzureCredential parametro managed_identity_client_id del costruttore sull'ID client.

   credential = DefaultAzureCredential(
       managed_identity_client_id = managed_identity_client_id
   )
   

3. Ridistribuire il codice in Azure dopo aver apportato questa modifica affinché vengano applicati gli aggiornamenti della configurazione.

Testare l'app

Dopo aver distribuito il codice aggiornato, passare all'applicazione ospitata nel browser. L'app dovrebbe essere in grado di connettersi correttamente a Cosmos DB. Tenere presente che la propagazione delle assegnazioni di ruolo nell'ambiente di Azure potrebbe richiedere alcuni minuti. L'applicazione è ora configurata per l'esecuzione sia in locale che in un ambiente di produzione senza che gli sviluppatori dover gestire i segreti nell'applicazione stessa.

Passaggi successivi

In questa esercitazione si è appreso come eseguire la migrazione di un'applicazione a connessioni senza password.

È possibile leggere le risorse seguenti per esplorare i concetti illustrati in questo articolo in modo più approfondito:

• Autorizzare l'accesso ai BLOB usando Microsoft Entra ID)
• Per altre informazioni su .NET, vedere Introduzione a .NET in 10 minuti.