適用于 .NET 的 Azure KeyVault 系統管理用戶端程式庫 - 4.3.0 版

Azure 金鑰保存庫受控 HSM 是完全受控、高可用性、符合標準的標準雲端服務，可讓您使用 FIPS 140-2 層級 3 驗證的 HSM 來保護雲端應用程式的密碼編譯金鑰。

Azure 金鑰保存庫系統管理程式庫用戶端支援系統管理工作，例如完整備份/還原和金鑰層級角色型存取控制 (RBAC) 。

| 原始程式碼套件 (NuGet) | 產品檔 | 樣品

開始使用

安裝套件

使用NuGet安裝適用于 .NET 的 Azure 金鑰保存庫管理用戶端程式庫：

dotnet add package Azure.Security.KeyVault.Administration

必要條件

• Azure 訂用帳戶。
• 現有的 Azure 金鑰保存庫。 如果您需要建立 Azure 金鑰保存庫，您可以使用Azure CLI。
• 使用RBAC (建議) 或存取控制授權給現有的 Azure 金鑰保存庫。

若要建立受控 HSM 資源，請執行下列 CLI 命令：

az keyvault create --hsm-name <your-key-vault-name> --resource-group <your-resource-group-name> --administrators <your-user-object-id> --location <your-azure-location>

若要取得 <your-user-object-id> ，您可以執行下列 CLI 命令：

az ad user show --id <your-user-principal> --query id

驗證用戶端

若要與 Azure 金鑰保存庫 服務互動，您必須建立下列用戶端類別的實例。 您需要保存 庫 URL，您可能會在入口網站中看到「DNS 名稱」，以及具現化用戶端物件的認證。

以下顯示的範例會使用 DefaultAzureCredential ，適用于大部分案例，包括本機開發和生產環境。 此外，我們建議在生產環境中使用受控識別進行驗證。 您可以在 Azure 身分識別 檔中，找到不同驗證方式及其對應認證類型的詳細資訊。

若要使用如下所示的 DefaultAzureCredential 提供者，或其他 Azure SDK 提供的認證提供者，您必須先安裝 Azure.Identity 套件：

dotnet add package Azure.Identity

啟動您的受控 HSM

在 HSM 啟動前，所有資料平面命令都會停用。 您將無法建立金鑰或指派角色。 只有在 create 命令執行期間指派的指定管理員，才可以啟用 HSM。 若要啟用 HSM，您必須下載安全性網域。

若要啟動 HSM，您需要：

• 至少 3 個 RSA 金鑰組， (最多 10 個)
• 指定解密安全性網域所需的最小金鑰數目， (仲裁)

若要啟動 HSM，您至少必須將 3 個 (最多 10 個) RSA 公開金鑰傳送至 HSM。 HSM 會使用這些金鑰將安全性網域加密，並加以傳回。 成功下載此安全性網域之後，您的 HSM 即可供使用。 您也需要指定仲裁，這是解密安全性網域所需的私密金鑰數目下限。

下列範例示範如何使用 openssl 來產生 3 個自我簽署憑證。

openssl req -newkey rsa:2048 -nodes -keyout cert_0.key -x509 -days 365 -out cert_0.cer
openssl req -newkey rsa:2048 -nodes -keyout cert_1.key -x509 -days 365 -out cert_1.cer
openssl req -newkey rsa:2048 -nodes -keyout cert_2.key -x509 -days 365 -out cert_2.cer

使用 az keyvault security-domain download 命令下載安全性網域，並啟動您的受控 HSM。 下列範例使用 3 個 RSA 金鑰組， (此命令只需要公開金鑰) ，並將仲裁設定為 2。

az keyvault security-domain download --hsm-name <your-managed-hsm-name> --sd-wrapping-keys ./certs/cert_0.cer ./certs/cert_1.cer ./certs/cert_2.cer --sd-quorum 2 --security-domain-file ContosoMHSM-SD.json

控制受控 HSM 的存取

在建立期間指派的指定系統管理員會自動新增至「受控 HSM 系統管理員」 內建角色，這些角色能夠下載安全性網域並 管理資料平面存取的角色，以及其他有限的許可權。

若要對金鑰執行其他動作，您必須將主體指派給其他角色，例如「受控 HSM 密碼編譯使用者」，以執行非破壞性金鑰作業：

az keyvault role assignment create --hsm-name <your-managed-hsm-name> --role "Managed HSM Crypto User" --scope / --assignee-object-id <principal-or-user-object-ID> --assignee-principal-type <principal-type>

請閱讀妥善保護受控 HSM 的 最佳做法 。

建立 KeyVaultAccessControlClient

具現化 DefaultAzureCredential ，以傳遞至 KeyVaultAccessControlClient 。 如果權杖認證的實例會使用相同的身分識別進行驗證，則可以與多個用戶端搭配使用。

KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

建立 KeyVaultBackupClient

具現化 DefaultAzureCredential ，以傳遞至 KeyVaultBackupClient 。 如果權杖認證的實例會使用相同的身分識別進行驗證，則可以與多個用戶端搭配使用。

KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

建立 KeyVaultSettingClient

具現化 DefaultAzureCredential ，以傳遞至 KeyVaultSettingsClient 。 如果權杖認證的實例會使用相同的身分識別進行驗證，則可以與多個用戶端搭配使用。

KeyVaultSettingsClient client = new KeyVaultSettingsClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

重要概念

KeyVaultRoleDefinition

KeyVaultRoleDefinition是許可權的集合。 角色定義會定義可執行檔作業，例如讀取、寫入和刪除。 它也可以定義從允許的作業中排除的作業。

KeyVaultRoleDefinitions 可以列出並指定為 的一 KeyVaultRoleAssignment 部分。

KeyVaultRoleAssignment

是 KeyVaultRoleAssignment KeyVaultRoleDefinition 與服務主體的關聯。 您可以個別建立、列出、擷取和刪除它們。

KeyVaultAccessControlClient

同時 KeyVaultAccessControlClient 提供允許管理 KeyVaultRoleDefinition 和 物件的同步和 KeyVaultRoleAssignment 非同步作業。

KeyVaultBackupClient

提供 KeyVaultBackupClient 同步和非同步作業來執行完整金鑰備份、完整金鑰還原，以及選擇性金鑰還原。

BackupOperation

BackupOperation表示完整金鑰備份的長時間執行作業。

RestoreOperation

表示 RestoreOperation 完整金鑰和選擇性金鑰還原的長時間執行作業。

執行緒安全

我們保證所有用戶端實例方法都是安全線程，且彼此獨立 (指導方針) 。 這可確保重複使用用戶端實例的建議一律是安全的，即使是跨執行緒也一樣。

其他概念

用戶端選項 | 存取回應 | 長時間執行的作業 | 處理失敗 | 診斷 | 嘲笑 | 用戶端存留期

範例

Azure.Security.KeyVault.Administration 套件支援同步和非同步 API。

下一節會使用 client 上述針對存取控制或備份用戶端所建立的數個程式碼片段，涵蓋一些最常見的 Azure 金鑰保存庫存取控制相關工作：

同步範例

• 存取控制
  • 列出所有角色定義
  • 列出所有角色指派
  • 建立角色指派
  • 取得角色指派
  • 刪除角色指派
• 備份與還原
  • 執行完整金鑰備份
  • 執行完整金鑰還原

非同步範例

• 存取控制
  • 列出所有角色定義
  • 列出所有角色指派
  • 建立角色指派
  • 取得角色指派
  • 刪除角色指派
• 備份與還原
  • 執行完整金鑰備份
  • 執行完整金鑰還原

疑難排解

如需如何診斷各種失敗案例的詳細資料，請參閱 我們的疑難排解指南 。

一般

當您使用 .NET SDK 與 Azure 金鑰保存庫 系統管理程式庫互動時，服務傳回的錯誤會對應至針對REST API要求傳回的相同 HTTP 狀態碼。

例如，如果您嘗試擷取 Azure 金鑰保存庫中不存在的角色指派， 404 則會傳回錯誤，指出「找不到」。

try
{
    KeyVaultRoleAssignment roleAssignment = client.GetRoleAssignment(KeyVaultRoleScope.Global, "example-name");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Azure.RequestFailedException: Service request failed.
Status: 404 (Not Found)

Content:
{"error":{"code":"RoleAssignmentNotFound","message":"Requested role assignment not found (Activity ID: a67f09f4-b68e-11ea-bd6d-0242ac120006)"}}

Headers:
X-Content-Type-Options: REDACTED
x-ms-request-id: a67f09f4-b68e-11ea-bd6d-0242ac120006
Content-Length: 143
Content-Type: application/json

設定主控台記錄

查看記錄的最簡單方式是啟用主控台記錄。 若要建立將訊息輸出至主控台的 Azure SDK 記錄接聽程式，請使用 AzureEventSourceListener.CreateConsoleLogger 方法。

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

若要深入瞭解其他記錄機制，請參閱 這裡。

後續步驟

開始使用我們的範例。

參與

此專案歡迎參與和提供建議。 大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。 如需詳細資料，請前往 https://cla.microsoft.com 。

此專案採用了 Microsoft 開放原始碼管理辦法。 如需詳細資訊，請參閱管理辦法常見問題集，如有任何其他問題或意見請連絡 opencode@microsoft.com。