移轉應用程式以搭配使用無密碼連線與 Azure Cosmos DB for NoSQL

必須驗證對 Azure Cosmos DB for NoSQL 的應用程式要求。 雖然有多個選項可以向 Azure Cosmos DB 進行驗證，但您應該盡可能在應用程式中排定無密碼連線的優先順序。 搭配使用連接字串與密碼或祕密金鑰的傳統驗證方法會產生安全性風險和複雜度。 請造訪 Azure 服務中樞的無密碼連線，以深入了解移至無密碼連線的優點。

下列教學課程說明如何將現有的應用程式移轉成使用無密碼連線來連線至 Azure Cosmos DB for NoSQL，而不是金鑰型解決方案。

設定角色和使用者以支援本機開發驗證

使用無密碼驗證在本機開發時，請確定連線至 Cosmos DB 的使用者帳戶已獲指派具有執行資料作業正確權限的角色。 目前，Azure Cosmos DB for NoSQL 未包括資料作業的內建角色，但您可以使用 Azure CLI 或 PowerShell 來建立自己的角色。

角色包含允許使用者執行的權限或動作集合，例如讀取、寫入和刪除。 您可以在 Cosmos DB 安全性設定文件中深入閱讀設定角色型存取控制 (RBAC)。

建立自訂角色

1. 使用 az role definition create 命令來建立角色。 傳入 Cosmos DB 帳戶名稱和資源群組，後面接著可定義自訂角色的 JSON 主體。 下列範例會建立名為 PasswordlessReadWrite 的角色，而且其具有在 Cosmos DB 容器中讀取和寫入項目的權限。 此角色也會使用 / 將範圍設定為帳戶層級。

   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. 命令完成時，請從 name 欄位複製 ID 值，並將其貼入某處以供稍後使用。

3. 將您建立的角色指派給將連線至 Cosmos DB 的使用者帳戶或服務主體。 在本機開發期間，這一般是您自己已登入 Visual Studio 或 Azure CLI 這類開發工具的帳戶。 使用 az ad user 命令來擷取帳戶的詳細資料。

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

4. 複製結果中的 id 屬性值，然後將其貼到某處以供稍後使用。

5. 使用 az cosmosdb sql role assignment create 命令和您先前複製的識別碼，將您建立的自訂角色指派給使用者帳戶。

   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> 
   

在本機登入 Azure

針對本機開發，請確定使用您指派角色的相同 Microsoft Entra 帳戶進行驗證。 您可以透過 Azure CLI 或 Azure PowerShell 這類熱門開發工具來進行驗證。 您可以用來驗證的開發工具會因語言而異。

Azure CLI

使用下列命令透過 Azure CLI 登入 Azure：

az login

Visual Studio

選取 Visual Studio 右上方的 [登入] 按鈕。

使用您先前指派角色的 Microsoft Entra 帳戶來登入。

Visual Studio Code

您將需要安裝 Azure CLI，才能透過 Visual Studio Code 來使用 DefaultAzureCredential。

在 Visual Studio Code 的主功能表上，瀏覽至 [終端機] > [新增終端機]。

使用下列命令透過 Azure CLI 登入 Azure：

az login

PowerShell

使用 PowerShell 透過下列命令登入 Azure：

Connect-AzAccount

將應用程式碼移轉為使用無密碼連線

.NET

1. 若要在 .NET 應用程式中使用 DefaultAzureCredential，請安裝 Azure.Identity 套件：

   dotnet add package Azure.Identity
   

2. 在檔案頂端，新增下列程式碼：

   using Azure.Identity;
   

3. 在程式碼中找出哪些位置建立 CosmosClient 物件以連線至 Azure Cosmos DB。 更新程式碼，使其符合下列範例。

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

Go

1. 若要在 Go 應用程式中使用 DefaultAzureCredential，請安裝 azidentity 模組：

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

2. 在檔案頂端，新增下列程式碼：

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

3. 在程式碼中找出哪些位置建立 Client 執行個體以連線至 Azure Cosmos DB。 將程式碼更新為符合下列範例：

   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. 若要在 Java 應用程式中使用 DefaultAzureCredential，請透過下列其中一種方式來安裝 azure-identity 套件：

   1. 包括 BOM 檔案。
   2. 包括直接相依性。

2. 在檔案頂端，新增下列程式碼：

   import com.azure.identity.DefaultAzureCredentialBuilder;
   

3. 在程式碼中找出哪些位置建立 CosmosClient 或 CosmosAsyncClient 物件以連線至 Azure Cosmos DB。 將程式碼更新為符合下列範例：

   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. 若要在 Node.js 應用程式中使用 DefaultAzureCredential，請安裝 @azure/identity 套件：

   npm install --save @azure/identity
   

2. 在檔案頂端，新增下列程式碼：

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

3. 在程式碼中找出哪些位置建立 CosmosClient 物件以連線至 Azure Cosmos DB。 將程式碼更新為符合下列範例：

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

Python

1. 若要在 Python 應用程式中使用 DefaultAzureCredential，請安裝 azure-identity 套件：

   pip install azure-identity
   

2. 在檔案頂端，新增下列程式碼：

   from azure.identity import DefaultAzureCredential
   

3. 在程式碼中找出哪些位置建立 BlobServiceClient 物件以連線至 Azure Blob 儲存體。 將程式碼更新為符合下列範例：

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

在本機執行應用程式

完成這些程式碼變更之後，請在本機執行您的應用程式。 新的組態應該會挑選您的本機認證，例如 Azure CLI、Visual Studio 或 IntelliJ。 您在 Azure 中指派給本機開發使用者的角色可讓您的應用程式在本機連線至 Azure 服務。

設定 Azure 裝載環境

應用程式設定為使用無密碼連線並在本機執行之後，相同的程式碼在部署至 Azure 之後就可以向 Azure 服務進行驗證。 下列各節說明如何設定已部署的應用程式，以使用受控識別來連線至 Azure Cosmos DB。

建立受控識別

您可以使用 Azure 入口網站或 Azure CLI 來建立使用者指派的受控識別。 您的應用程式使用身分識別向其他服務進行驗證。

Azure 入口網站

1. 在 Azure 入口網站頂端，搜尋「受控識別」。 選取 [受控識別] 結果。
2. 選取 [受控識別] 概觀頁面頂端的 [+ 建立]。
3. 在 [基本] 索引標籤上，輸入下列值：
   • 訂用帳戶：選取您想要的訂用帳戶。
   • 資源群組：選取您想要的資源群組。
   • 區域：選取靠近您所在位置的區域。
   • 名稱：輸入身分識別的可辨識名稱，例如 MigrationIdentity。
4. 選取頁面底部的 [檢閱 + 建立] 。
5. 驗證檢查完成時，請選取 [建立]。 Azure 會建立新的使用者指派身分識別。

建立資源之後，請選取 [移至資源] 以檢視受控識別的詳細資料。

Azure CLI

使用 az identity create 命令，以建立使用者指派的受控識別：

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

將受控識別與您的 Web 應用程式相關聯

您需要將 Web 應用程式設定為使用您所建立的受控識別。 使用 Azure 入口網站或 Azure CLI，以將身分識別指派給應用程式。

Azure 入口網站

完成 Azure 入口網站中的下列步驟，以將身分識別與您的應用程式相關聯。 這些相同的步驟適用於下列 Azure 服務：

• Azure Spring Apps
• Azure 容器應用程式
• Azure 虛擬機器
• Azure Kubernetes Service

1. 導覽至您 Web 應用程式的概觀頁面。

2. 從左側導覽中，選取 [身分識別]。

3. 在 [身分識別] 頁面上，切換至 [使用者指派] 索引標籤。

4. 選取 [+ 新增]，以開啟 [新增使用者指派的受控識別] 飛出視窗。

5. 選取先前用來建立身分識別的訂用帳戶。

6. 依名稱搜尋 MigrationIdentity，然後從搜尋結果中予以選取。

7. 選取 [新增]，以將身分識別與您的應用程式相關聯。

   

Azure CLI

使用下列 Azure CLI 命令，以將身分識別與您的應用程式相關聯：

使用 az identity show 命令，以擷取您所建立受控識別的識別碼。 請複製輸出值，以用於下一個步驟。

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

Azure App Service

您可以使用 az webapp identity assign 命令，將受控識別指派給 Azure App Service 執行個體。

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

Azure Spring Apps

您可以使用 az spring app identity assign 命令，將受控識別指派給 Azure Spring 應用程式執行個體。

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

Azure 容器應用程式

您可以使用 az containerapp identity assign 命令，以將受控識別指派給虛擬機器。

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

Azure 虛擬機器

您可以使用 az vm identity assign 命令，將受控識別指派給虛擬機器。

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

Azure Kubernetes Service

您可以使用 az aks update命令，將受控識別指派給 Azure Kubernetes Service (AKS) 執行個體。

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>

將角色指派給受控識別

授與受控識別的權限，方法是將您所建立的自訂角色指派給受控識別，就像指派給本機開發使用者一樣。

若要使用 Azure CLI 在資源層級指派角色，您必須先使用 az cosmosdb show 命令來擷取資源識別碼。 您可以使用 --query 參數來篩選輸出屬性。

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

複製上述命令的輸出識別碼。 接著，您可以使用 Azure CLI 的 az role assignment 命令來指派角色。

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

更新應用程式碼

您需要設定應用程式碼，以尋找您在部署至 Azure 時所建立的特定受控識別。 在某些情況下，明確設定應用程式的受控識別也會防止意外偵測到以及自動使用其他環境身分識別。

1. 在受控識別概觀頁面上，將用戶端識別碼值複製至剪貼簿。

2. 套用下列語言特定變更：

   .NET

   建立 DefaultAzureCredentialOptions 物件，並將其傳遞給 DefaultAzureCredential。 將 ManagedIdentityClientId 屬性設定為用戶端識別碼。

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

   Go

   將 AZURE_CLIENT_ID 環境變數設定為受控識別用戶端識別碼。 DefaultAzureCredential 會讀取此環境變數。

   Java

   呼叫 managedIdentityClientId 方法。 將用戶端識別碼傳遞給它。

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

   Node.js

   建立其 managedIdentityClientId 屬性設定為用戶端識別碼的 DefaultAzureCredentialClientIdOptions 物件。 將該物件傳遞給 DefaultAzureCredential 建構函式。

   const credential = new DefaultAzureCredential({
     managedIdentityClientId
   });
   

   Python

   將 DefaultAzureCredential 建構函式的 managed_identity_client_id 參數設定為用戶端識別碼。

   credential = DefaultAzureCredential(
       managed_identity_client_id = managed_identity_client_id
   )
   

3. 在進行這項變更之後，將您的程式碼重新部署至 Azure，以套用設定更新。

測試應用程式

部署已變更的程式碼之後，請在瀏覽器中瀏覽至您的託管應用程式。 您的應用程式應該能夠成功連線至 Cosmos DB。 請記住，角色指派可能需要幾分鐘才會傳播到整個 Azure 環境。 您的應用程式現在已設定為在本機和實際執行環境中執行，而不需要開發人員管理應用程式本身的秘密。

下一步

在本教學課程中，您已了解如何將應用程式移轉為無密碼連線。

您可以閱讀下列資源，以更深入探索本文所討論的概念：

• 使用 Microsoft Entra ID 授權存取 Blob)
• 若要深入了解 .NET，請參閱在 10 分鐘內開始使用 .NET。