教學課程：透過 Azure Key Vault 儲存和使用 Azure Cosmos DB 認證

  • 發行項

適用於：NoSQL MongoDB Cassandra Gremlin Table

重要

存取 Azure Cosmos DB 的建議方法，是使用系統指派的受控識別。 如果受控識別解決方案和以憑證為基礎的解決方案都不符合您的需求，請使用本文中的 Azure Key Vault 解決方案。

如果您使用 Azure Cosmos DB 作為資料庫，可以使用 SDK、API 端點，以及主要或次要金鑰來連線至資料庫、容器和項目。

將端點 URI 和敏感性讀寫金鑰直接儲存在應用程式程式碼或組態檔內，並不是很好的做法。 在理想情況下，應從主機內的環境變數讀取這項資料。 在 Azure App Service 中，應用程式設定可讓您為 Azure Cosmos DB 帳戶插入執行階段認證，而無須由開發人員以不安全的純文字形式儲存這些認證。

Azure Key Vault 可讓您安全地儲存這些認證，同時提供 Azure App Service 對認證的受控存取等服務，使這項最佳做法更加完善。 Azure App Service 會從 Azure Key Vault 中安全地讀取您的認證，並將這些認證插入執行中的應用程式中。

透過此最佳做法，開發人員可以儲存 Azure Cosmos DB 模擬器等工具的認證，或是在開發期間免費試用 Azure Cosmos DB。 然後，作業小組可確保會在執行階段插入正確的生產設定。

在本教學課程中，您會了解如何：

  • 建立 Azure 金鑰保存庫執行個體
  • 將 Azure Cosmos DB 認證作為秘密新增至金鑰保存庫
  • 建立並註冊 Azure App Service 資源，並且授與「讀取金鑰」權限
  • 將金鑰保存庫秘密插入 App Service 資源中

注意

本教學課程和範例應用程式使用 Azure Cosmos DB for NoSQL 帳戶。 您可以使用其他 API 執行許多相同的步驟。

必要條件

開始之前：取得 Azure Cosmos DB 認證

開始之前，您應取得現有帳戶的認證。

  1. 瀏覽至現有的 Azure Cosmos DB for NoSQL 帳戶的 [Azure 入口網站] 頁面。

  2. 從 Azure Cosmos DB for NoSQL 帳戶頁面，選取 [金鑰] 導覽功能表選項。

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

  3. 記錄 URI 和 PRIMARY KEY 欄位中的值。 本教學課程後續將用到這些值。

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

建立 Azure Key Vault 資源

首先，建立新的金鑰保存庫來儲存您的 API for NoSQL 認證。

  1. 登入 Azure 入口網站。

  2. 選取 [建立資源] > [安全性] > [Key Vault]。

  3. 在 [建立金鑰保存庫] 頁面上，輸入下列資訊：

    設定 描述
    訂用帳戶 選取要用於此 Azure Cosmos 帳戶的 Azure 訂用帳戶。
    資源群組 選取資源群組，或選取 [新建]，然後輸入新資源群組的唯一名稱。
    金鑰保存庫名稱 輸入金鑰保存庫的全域唯一名稱。
    區域 選取用來裝載 Azure Cosmos DB 帳戶的地理位置。 使用最接近使用者的位置，讓他們能以最快速度存取資料。
    定價層 選取 [標準]。

  4. 將其餘設定保留為預設值。

  5. 選取 [檢閱 + 建立]。

  6. 檢閱您提供的設定，然後選取 [建立]。 建立帳戶需要幾分鐘的時間。 繼續進行之前，請等候入口網站頁面顯示 [您的部署已完成] 訊息。

在 Key Vault 新增 Azure Cosmos DB 存取金鑰

現在，將 Azure Cosmos DB 認證儲存為金鑰保存庫中的秘密。

  1. 選取 [前往資源]，以移至 Azure Key Vault 資源頁面。

  2. 在 Azure Key Vault 資源頁面中，選取 [秘密] 導覽功能表選項。

  3. 從功能表中選取 [產生/匯入]。

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

  4. 在 [建立祕密] 頁面上，輸入下列資訊：

    設定 描述
    上傳選項 手動
    名稱 cosmos-endpoint
    祕密值 輸入您先前在本教學課程中複製的 URI。

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

  5. 選取 [建立] 以建立新的 cosmos-endpoint 秘密。

  6. 從功能表中再次選取 [產生/匯入]。 在 [建立祕密] 頁面上，輸入下列資訊：

    設定 描述
    上傳選項 手動
    名稱 cosmos-readwrite-key
    祕密值 輸入您先前在本教學課程中複製的主要金鑰。

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

  7. 選取 [建立] 以建立新的 cosmos-readwrite-key 秘密。

  8. 在秘密建立後，在 [秘密] 頁面內的秘密清單中加以檢視。

    Screenshot of the list of secrets for a key vault.

  9. 選取每個金鑰、選取最新版本，然後複製秘密識別碼。 稍後您將在本教學課程中將此識別碼用於 cosmos-endpoint 和 cosmos-readwrite-key 秘密。

    提示

    秘密識別碼的格式將是 https://<key-vault-name>.vault.azure.net/secrets/<secret-name>/<version-id>。 例如，如果金鑰保存庫的名稱為 msdocs-key-vault，金鑰的名稱為 cosmos-readwrite-key，版本為 83b995e363d947999ac6cf487ae0e12e，則秘密識別碼將是 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.

使用 Azure Key Vault 建立及註冊 Azure Web 應用程式

在本節中，使用 Azure Key Vault 建立新的 Azure Web 應用程式、部署範例應用程式，然後註冊 Web 應用程式的受控識別。

  1. 使用 cosmos-db-nosql-dotnet-sample-web-environment-variables 範本建立新的 GitHub 存放庫。

  2. 在 Azure 入口網站中，選取 [建立資源] > [Web] > [Web 應用程式]。

  3. 在 [建立 Web 應用程式] 頁面的 [基本] 索引標籤上，輸入下列資訊：

    設定 描述
    訂用帳戶 選取要用於此 Azure Cosmos 帳戶的 Azure 訂用帳戶。
    資源群組 選取資源群組，或選取 [新建]，然後輸入新資源群組的唯一名稱。
    名稱 輸入 Web 應用程式的全域唯一名稱。
    發行 選取 [程式碼]。
    執行階段堆疊 選取 [.NET 6 (LTS)]。
    作業系統 選取 [Windows]。
    區域 選取用來裝載 Azure Cosmos DB 帳戶的地理位置。 使用最接近使用者的位置，讓他們能以最快速度存取資料。

  4. 將其餘設定保留為預設值。

  5. 選取 [下一步：部署]。

  6. 在 [部署] 索引標籤上，輸入下列資訊：

    設定 描述
    持續部署 選取啟用。
    GitHub 帳戶 選取授權。 依照 GitHub 帳戶授權提示，為 Azure 授與讀取您新建立的 GitHub 存放庫的權限。
    組織 選取新 GitHub 存放庫的組織。
    存放庫 選取新 GitHub 存放庫的名稱。
    分支 選取 [主要]。

  7. 選取 [檢閱 + 建立]。

  8. 檢閱您提供的設定，然後選取 [建立]。 建立帳戶需要幾分鐘的時間。 繼續進行之前，請等候入口網站頁面顯示 [您的部署已完成] 訊息。

  9. Web 應用程式初次部署至 Web 應用程式時，可能需要額外花費幾分鐘的時間。 從 [Azure Web 應用程式資源] 頁面中選取 [瀏覽]，以查看應用程式的預設狀態。

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

  10. 選取 [身分識別] 導覽功能表選項。

  11. 在 [身分識別] 頁面上，針對 [系統指派的受控識別] 選取 [開啟]，然後選取 [儲存]。

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

將 Azure Key Vault 秘密插入為 Azure Web 應用程式的應用程式設定

最後，將儲存在金鑰保存庫中的秘密插入作為 Web 應用程式內的應用程式設定。 應用程式設定接著會在執行階段將認證插入應用程式中，而無須儲存純文字的認證。

  1. 返回 Azure 入口網站中的金鑰保存庫頁面。 從導覽功能表中選取 [存取原則]。

  2. 在 [存取原則] 頁面上，從功能表中選取 [建立]。

    Screenshot of the Create option in the Access policies menu.

  3. 在 [建立存取原則] 頁面的 [權限] 索引標籤上，選取 [祕密權限] 區段中的 [取得] 選項。 選取 [下一步]。

    Screenshot of the Get permission enabled for Secret permissions.

  4. 在 [主體] 索引標籤上，選取您先前在本教學課程中建立的 Web 應用程式名稱。 選取 [下一步]。

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

    注意

    在此範例螢幕擷取畫面中，Web 應用程式的名稱為 msdocs-dotnet-web。

  5. 再次選取 [下一步] 以略過 [應用程式] 索引標籤。在 [檢閱 + 建立] 索引標籤上檢閱您提供的設定，然後選取 [建立]。

  6. 返回 Azure 入口網站中的 Web 應用程式頁面。 從導覽功能表中選取 [設定]。

  7. 在 [設定] 頁面上，選取 [新增應用程式設定]。 在 [新增/編輯應用程式設定] 對話方塊中，輸入下列資訊：

    設定 描述
    名稱 CREDENTIALS__ENDPOINT
    索引鍵 在您先前在本教學課程中建立的金鑰保存庫中，取得 cosmos-endpoint 秘密的秘密識別碼。 輸入下列格式的識別碼：@Microsoft.KeyVault(SecretUri=<secret-identifier>)。

    提示

    請確定環境變數具有雙底線 (__) 值，而不是單一底線。 雙底線是 .NET 在所有平台上支援的索引鍵分隔符號。 如需詳細資訊，請參閱環境變數設定。

    注意

    例如，如果秘密識別碼為 https://msdocs-key-vault.vault.azure.net/secrets/cosmos-endpoint/69621c59ef5b4b7294b5def118921b07，則參考將是 @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. 選取 [確定] 以保存新的應用程式設定

  9. 再次選取 [新增應用程式設定]。 在 [新增/編輯應用程式設定] 對話方塊中輸入下列資訊，然後選取 [確定]：

    設定 描述
    名稱 CREDENTIALS__KEY
    索引鍵 在您先前在本教學課程中建立的金鑰保存庫中，取得 cosmos-readwrite-key 秘密的秘密識別碼。 輸入下列格式的識別碼：@Microsoft.KeyVault(SecretUri=<secret-identifier>)。

  10. 回到 [設定] 頁面，選取 [儲存] 以更新 Web 應用程式的應用程式設定。

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

  11. 等候幾分鐘，讓 Web 應用程式以新的應用程式設定重新啟動。 此時，新的應用程式設定應該會指出這是金鑰保存庫參考。

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

  12. 從導覽功能表中選取 [概觀]。 選取 [瀏覽] 以查看已填入認證的應用程式。

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

下一步