Migrowanie aplikacji do używania połączeń bez hasła z usługą Azure Cosmos DB for NoSQL

Żądania aplikacji do usługi Azure Cosmos DB for NoSQL muszą być uwierzytelnione. Chociaż istnieje wiele opcji uwierzytelniania w usłudze Azure Cosmos DB, należy określić priorytety połączeń bez hasła w aplikacjach, jeśli to możliwe. Tradycyjne metody uwierzytelniania, które używają parametry połączenia z hasłami lub kluczami tajnymi, tworzą zagrożenia bezpieczeństwa i komplikacje. Odwiedź centrum usług platformy Azure bez hasła, aby dowiedzieć się więcej o zaletach przechodzenia do połączeń bez hasła.

W poniższym samouczku wyjaśniono, jak przeprowadzić migrację istniejącej aplikacji w celu nawiązania połączenia z usługą Azure Cosmos DB for NoSQL przy użyciu połączeń bez hasła zamiast rozwiązania opartego na kluczach.

Konfigurowanie ról i użytkowników na potrzeby uwierzytelniania programowania lokalnego

Podczas opracowywania lokalnego przy użyciu uwierzytelniania bez hasła upewnij się, że konto użytkownika łączące się z usługą Cosmos DB ma przypisaną rolę z odpowiednimi uprawnieniami do wykonywania operacji na danych. Obecnie usługa Azure Cosmos DB for NoSQL nie obejmuje wbudowanych ról dla operacji na danych, ale możesz utworzyć własne przy użyciu interfejsu wiersza polecenia platformy Azure lub programu PowerShell.

Role składają się z kolekcji uprawnień lub akcji, które użytkownik może wykonywać, takich jak odczyt, zapis i usuwanie. Więcej informacji na temat konfigurowania kontroli dostępu opartej na rolach (RBAC) można uzyskać w dokumentacji konfiguracji zabezpieczeń usługi Cosmos DB.

Tworzenie roli niestandardowej

1. Utwórz rolę przy użyciu az role definition create polecenia . Przekaż nazwę konta usługi Cosmos DB i grupę zasobów, a następnie treść kodu JSON definiującą rolę niestandardową. Poniższy przykład tworzy rolę o nazwie PasswordlessReadWrite z uprawnieniami do odczytu i zapisu elementów w kontenerach usługi Cosmos DB. Rola jest również ograniczona do poziomu konta przy użyciu polecenia /.

   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. Po zakończeniu działania polecenia skopiuj wartość identyfikatora name z pola i wklej ją gdzieś do późniejszego użycia.

3. Przypisz rolę utworzoną do konta użytkownika lub jednostki usługi, która będzie łączyć się z usługą Cosmos DB. Podczas programowania lokalnego zazwyczaj będzie to twoje własne konto, które jest zalogowane do narzędzia programistycznego, takiego jak Program Visual Studio lub interfejs wiersza polecenia platformy Azure. Pobierz szczegóły konta przy użyciu az ad user polecenia .

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

4. Skopiuj wartość id właściwości z wyników i wklej ją gdzieś do późniejszego użycia.

5. Przypisz rolę niestandardową utworzoną do konta użytkownika przy użyciu az cosmosdb sql role assignment create polecenia i skopiowanych wcześniej identyfikatorów.

   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> 
   

Logowanie do platformy Azure lokalnie

W przypadku programowania lokalnego upewnij się, że uwierzytelniasz się przy użyciu tego samego konta Microsoft Entra, do którego przypisano rolę. Możesz uwierzytelnić się za pomocą popularnych narzędzi programistycznych, takich jak interfejs wiersza polecenia platformy Azure lub program Azure PowerShell. Narzędzia programistyczne, za pomocą których można uwierzytelniać się w różnych językach.

Interfejs wiersza polecenia platformy Azure

Zaloguj się do platformy Azure za pomocą interfejsu wiersza polecenia platformy Azure przy użyciu następującego polecenia:

az login

Program Visual Studio

Wybierz przycisk Zaloguj się w prawym górnym rogu programu Visual Studio.

Zaloguj się przy użyciu konta Microsoft Entra, do którego przypisano wcześniej rolę.

Visual Studio Code

Aby pracować z DefaultAzureCredential programem Visual Studio Code, musisz zainstalować interfejs wiersza polecenia platformy Azure.

W menu głównym programu Visual Studio Code przejdź do pozycji Terminal New Terminal (Nowy > terminal).

Zaloguj się do platformy Azure za pomocą interfejsu wiersza polecenia platformy Azure przy użyciu następującego polecenia:

az login

Program PowerShell

Zaloguj się do platformy Azure przy użyciu programu PowerShell za pomocą następującego polecenia:

Connect-AzAccount

Migrowanie kodu aplikacji w celu korzystania z połączeń bez hasła

.NET

1. Aby użyć DefaultAzureCredential w aplikacji .NET, zainstaluj Azure.Identity pakiet:

   dotnet add package Azure.Identity
   

2. W górnej części pliku dodaj następujący kod:

   using Azure.Identity;
   

3. Zidentyfikuj lokalizacje w kodzie, które tworzą obiekt w celu nawiązania połączenia z usługą CosmosClient Azure Cosmos DB. Zaktualizuj kod, aby był zgodny z poniższym przykładem.

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

Przejdź

1. Aby użyć DefaultAzureCredential w aplikacji Języka Go, zainstaluj azidentity moduł:

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

2. W górnej części pliku dodaj następujący kod:

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

3. Zidentyfikuj lokalizacje w kodzie, które tworzą wystąpienie w celu nawiązania połączenia z usługą Client Azure Cosmos DB. Zaktualizuj kod, aby był zgodny z następującym przykładem:

   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. Aby użyć DefaultAzureCredential go w aplikacji Java, zainstaluj azure-identity pakiet za pomocą jednego z następujących podejść:

   1. Uwzględnij plik BOM.
   2. Uwzględnij zależność bezpośrednią.

2. W górnej części pliku dodaj następujący kod:

   import com.azure.identity.DefaultAzureCredentialBuilder;
   

3. Zidentyfikuj lokalizacje w kodzie, które tworzą obiekt lub CosmosAsyncClient w celu nawiązania połączenia z usługą CosmosClient Azure Cosmos DB. Zaktualizuj kod, aby był zgodny z następującym przykładem:

   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. Aby użyć DefaultAzureCredential w aplikacji Node.js, zainstaluj @azure/identity pakiet:

   npm install --save @azure/identity
   

2. W górnej części pliku dodaj następujący kod:

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

3. Zidentyfikuj lokalizacje w kodzie, które tworzą obiekt w celu nawiązania połączenia z usługą CosmosClient Azure Cosmos DB. Zaktualizuj kod, aby był zgodny z następującym przykładem:

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

Python

1. Aby użyć DefaultAzureCredential w aplikacji języka Python, zainstaluj azure-identity pakiet:

   pip install azure-identity
   

2. W górnej części pliku dodaj następujący kod:

   from azure.identity import DefaultAzureCredential
   

3. Zidentyfikuj lokalizacje w kodzie, które tworzą obiekt w celu nawiązania połączenia z usługą BlobServiceClient Azure Blob Storage. Zaktualizuj kod, aby był zgodny z następującym przykładem:

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

Lokalne uruchamianie aplikacji

Po wprowadzeniu tych zmian w kodzie uruchom aplikację lokalnie. Nowa konfiguracja powinna pobierać poświadczenia lokalne, takie jak interfejs wiersza polecenia platformy Azure, program Visual Studio lub IntelliJ. Role przypisane do lokalnego użytkownika deweloperskiego na platformie Azure umożliwiają aplikacji nawiązywanie połączenia z usługą platformy Azure lokalnie.

Konfigurowanie środowiska hostingu platformy Azure

Po skonfigurowaniu aplikacji do korzystania z połączeń bez hasła i uruchamianiu lokalnie ten sam kod może uwierzytelniać się w usługach platformy Azure po jej wdrożeniu na platformie Azure. W poniższych sekcjach opisano sposób konfigurowania wdrożonej aplikacji w celu nawiązania połączenia z usługą Azure Cosmos DB przy użyciu tożsamości zarządzanej.

Tworzenie tożsamości zarządzanej

Tożsamość zarządzaną przypisaną przez użytkownika można utworzyć przy użyciu witryny Azure Portal lub interfejsu wiersza polecenia platformy Azure. Aplikacja używa tożsamości do uwierzytelniania w innych usługach.

Witryna Azure Portal

1. W górnej części witryny Azure Portal wyszukaj pozycję Tożsamości zarządzane. Wybierz wynik tożsamości zarządzanych.
2. Wybierz pozycję + Utwórz w górnej części strony przeglądu tożsamości zarządzanych .
3. Na karcie Podstawy wprowadź następujące wartości:
   • Subskrypcja: wybierz żądaną subskrypcję.
   • Grupa zasobów: wybierz żądaną grupę zasobów.
   • Region: wybierz region w pobliżu lokalizacji.
   • Nazwa: wprowadź rozpoznawalną nazwę tożsamości, taką jak MigrationIdentity.
4. Wybierz pozycję Przejrzyj i utwórz w dolnej części strony.
5. Po zakończeniu sprawdzania poprawności wybierz pozycję Utwórz. Platforma Azure tworzy nową tożsamość przypisaną przez użytkownika.

Po utworzeniu zasobu wybierz pozycję Przejdź do zasobu , aby wyświetlić szczegóły tożsamości zarządzanej.

Interfejs wiersza polecenia platformy Azure

Użyj polecenia az identity create, aby utworzyć tożsamość zarządzaną przypisaną przez użytkownika:

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

Kojarzenie tożsamości zarządzanej z aplikacją internetową

Musisz skonfigurować aplikację internetową tak, aby korzystała z utworzonej tożsamości zarządzanej. Przypisz tożsamość do aplikacji przy użyciu witryny Azure Portal lub interfejsu wiersza polecenia platformy Azure.

Witryna Azure Portal

Wykonaj następujące kroki w witrynie Azure Portal, aby skojarzyć tożsamość z aplikacją. Te same kroki dotyczą następujących usług platformy Azure:

• Azure Spring Apps
• Azure Container Apps
• Maszyny wirtualne platformy Azure
• Azure Kubernetes Service

1. Przejdź do strony przeglądu aplikacji internetowej.

2. Wybierz pozycję Tożsamość w obszarze nawigacji po lewej stronie.

3. Na stronie Tożsamość przejdź do karty Przypisane przez użytkownika.

4. Wybierz pozycję + Dodaj, aby otworzyć okno wysuwane Dodawanie tożsamości zarządzanej przypisanej przez użytkownika.

5. Wybierz subskrypcję użytą wcześniej do utworzenia tożsamości.

6. Wyszukaj pozycję MigrationIdentity według nazwy i wybierz ją z wyników wyszukiwania.

7. Wybierz pozycję Dodaj , aby skojarzyć tożsamość z aplikacją.

   

Interfejs wiersza polecenia platformy Azure

Użyj następujących poleceń interfejsu wiersza polecenia platformy Azure, aby skojarzyć tożsamość z aplikacją:

Pobierz identyfikator tożsamości zarządzanej utworzonej przy użyciu polecenia az identity show . Skopiuj wartość wyjściową do użycia w następnym kroku.

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

Azure App Service

Tożsamość zarządzaną można przypisać do wystąpienia usługi aplikacja systemu Azure za pomocą polecenia az webapp identity assign.

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

Azure Spring Apps

Tożsamość zarządzaną można przypisać do wystąpienia usługi Azure Spring Apps za pomocą polecenia 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>

Azure Container Apps

Tożsamość zarządzaną można przypisać do maszyny wirtualnej za pomocą polecenia az containerapp identity assign .

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

Maszyny wirtualne platformy Azure

Tożsamość zarządzaną można przypisać do maszyny wirtualnej za pomocą polecenia az vm identity assign .

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

Azure Kubernetes Service

Tożsamość zarządzaną można przypisać do wystąpienia usługi Azure Kubernetes Service (AKS) za pomocą polecenia 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>

Przypisywanie ról do tożsamości zarządzanej

Udziel uprawnień tożsamości zarządzanej, przypisując jej utworzoną rolę niestandardową, podobnie jak w przypadku lokalnego użytkownika dewelopera.

Aby przypisać rolę na poziomie zasobu przy użyciu interfejsu wiersza polecenia platformy Azure, należy najpierw pobrać identyfikator zasobu przy użyciu polecenia az cosmosdb show . Właściwości wyjściowe można filtrować przy użyciu parametru --query .

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

Skopiuj identyfikator wyjściowy z poprzedniego polecenia. Następnie możesz przypisać role przy użyciu polecenia az role assignment interfejsu wiersza polecenia platformy Azure.

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

Aktualizowanie kodu aplikacji

Należy skonfigurować kod aplikacji, aby wyszukać określoną tożsamość zarządzaną utworzoną podczas wdrażania na platformie Azure. W niektórych scenariuszach jawne ustawienie tożsamości zarządzanej aplikacji zapobiega również przypadkowemu wykryciu i użyciu innych tożsamości środowiska.

1. Na stronie przeglądu tożsamości zarządzanej skopiuj wartość identyfikatora klienta do schowka.

2. Zastosuj następujące zmiany specyficzne dla języka:

   .NET

   DefaultAzureCredentialOptions Utwórz obiekt i przekaż go do DefaultAzureCredentialobiektu . Ustaw właściwość ManagedIdentityClientId na identyfikator klienta.

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

   Przejdź

   Ustaw zmienną AZURE_CLIENT_ID środowiskową na identyfikator klienta tożsamości zarządzanej. DefaultAzureCredential odczytuje tę zmienną środowiskową.

   Java

   Wywołaj metodę managedIdentityClientId . Przekaż do niego identyfikator klienta.

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

   Node.js

   DefaultAzureCredentialClientIdOptions Utwórz obiekt z właściwością managedIdentityClientId ustawioną na identyfikator klienta. Przekaż ten obiekt do konstruktora DefaultAzureCredential .

   const credential = new DefaultAzureCredential({
     managedIdentityClientId
   });
   

   Python

   DefaultAzureCredential Ustaw parametr managed_identity_client_id konstruktora na identyfikator klienta.

   credential = DefaultAzureCredential(
       managed_identity_client_id = managed_identity_client_id
   )
   

3. Ponownie wdróż kod na platformie Azure po wprowadzeniu tej zmiany w celu zastosowania aktualizacji konfiguracji.

Testowanie aplikacji

Po wdrożeniu zaktualizowanego kodu przejdź do hostowanej aplikacji w przeglądarce. Aplikacja powinna mieć możliwość pomyślnego nawiązania połączenia z usługą Cosmos DB. Należy pamiętać, że propagowanie przypisań ról za pośrednictwem środowiska platformy Azure może potrwać kilka minut. Aplikacja jest teraz skonfigurowana do uruchamiania zarówno lokalnie, jak i w środowisku produkcyjnym bez konieczności zarządzania wpisami tajnymi w samej aplikacji.

Następne kroki

W tym samouczku przedstawiono sposób migrowania aplikacji do połączeń bez hasła.

Aby zapoznać się z pojęciami omówionymi w tym artykule, zapoznaj się z następującymi zasobami:

• Autoryzowanie dostępu do obiektów blob przy użyciu identyfikatora Entra firmy Microsoft)
• Aby dowiedzieć się więcej na temat platformy .NET, zobacz Wprowadzenie do platformy .NET w ciągu 10 minut.