快速入门：适用于 .NET 的 Azure Key Vault 客户端库 (SDK v3)

项目
06/02/2023

适用于 .NET 的 Azure Key Vault 客户端库入门。请遵循以下步骤安装包并试用基本任务的示例代码。

注意

此快速入门使用 v3.0.4 版本的 Microsoft.Azure.KeyVault 客户端库。若要使用 Key Vault 客户端库的最新版本，请参阅适用于 .NET 的 Azure Key Vault 客户端库 (SDK v4)。

Azure 密钥保管库可帮助保护云应用程序和服务使用的加密密钥和机密。使用适用于 .NET 的 Key Vault 客户端库可以：

提高安全性以及控制密钥和密码。
在几分钟内创建并导入加密密钥。
通过云扩展和全局冗余减少延迟。
简化和自动化与 TLS/SSL 证书相关的任务。

API 参考文档 | 库源代码 | 包 (NuGet)

注意

每个密钥保管库必须具有唯一的名称。在以下示例中，替换为密钥保管库的名称。

先决条件

本快速入门假定你正在 Windows 终端（例如 PowerShell Core、Windows PowerShell）中运行 dotnet、Azure CLI 和 Windows 命令。

设置

创建新的 .NET 控制台应用

在控制台窗口中，使用 dotnet new 命令新建名为 akv-dotnet 的 .NET 控制台应用。

dotnet new console -n akvdotnet

将目录更改为新创建的应用文件夹。可使用以下代码生成应用程序：

dotnet build

生成输出不应包含警告或错误。

Build succeeded.
 0 Warning(s)
 0 Error(s)

安装包

在控制台窗口中，安装适用于 .NET 的 Azure Key Vault 客户端库：

dotnet add package Microsoft.Azure.KeyVault

本快速入门还需要安装以下包：

dotnet add package System.Threading.Tasks
dotnet add package Microsoft.IdentityModel.Clients.ActiveDirectory
dotnet add package Microsoft.Azure.Management.ResourceManager.Fluent

创建资源组和 Key Vault

本快速入门使用预先创建的 Azure Key Vault。可以遵循 Azure CLI 快速入门、Azure PowerShell 快速入门或 Azure 门户快速入门中的步骤创建 Key Vault。或者，只需运行以下 Azure CLI 命令。

重要

每个密钥保管库必须具有唯一的名称。在以下示例中，替换为密钥保管库的名称。

az group create --name "myResourceGroup" -l "ChinaEast"

az keyvault create --name <your-unique-keyvault-name> -g "myResourceGroup"

创建服务主体

对基于云的 .NET 应用程序进行身份验证的最简单方法是使用托管标识；有关详细信息，请参阅使用应用服务托管标识访问 Azure Key Vault。

不过，为了简单起见，本快速入门创建了一个需要使用服务主体和访问控制策略的 .NET 控制台应用程序。服务主体要求使用格式为“http://<my-unique-service-principal-name>”的唯一名称。

使用 Azure CLI az ad sp create-for-rbac 命令创建服务主体：

az ad sp create-for-rbac -n "http://&lt;my-unique-service-principal-name&gt;" --sdk-auth

此操作将返回一系列键/值对。

{
  "clientId": "7da18cae-779c-41fc-992e-0527854c6583",
  "clientSecret": "b421b443-1669-4cd7-b5b1-394d5c945002",
  "subscriptionId": "443e30da-feca-47c4-b68f-1636b75e16b3",
  "tenantId": "35ad10f1-7799-4766-9acf-f2d946161b77",
  "activeDirectoryEndpointUrl": "https://login.chinacloudapi.cn",
  "resourceManagerEndpointUrl": "https://management.chinacloudapi.cn/",
  "sqlManagementEndpointUrl": "https://management.core.chinacloudapi.cn:8443/",
  "galleryEndpointUrl": "https://gallery.chinacloudapi.cn/",
  "managementEndpointUrl": "https://management.core.chinacloudapi.cn/"
}

请记下 clientId 和 clientSecret，因为在下面的向密钥保管库进行身份验证步骤中将要用到。

为服务主体授予对 Key Vault 的访问权限

通过将 clientId 传递给 az keyvault set-policy 命令，为密钥保管库创建授予服务主体权限的访问策略。授予服务主体对密钥和机密的 get、list 和 set 权限。

az keyvault set-policy -n <your-unique-keyvault-name> --spn <clientId-of-your-service-principal> --secret-permissions delete get list set --key-permissions create decrypt delete encrypt get list unwrapKey wrapKey

对象模型

使用适用于 .NET 的 Azure Key Vault 客户端库可以管理密钥和相关的资产（例如证书和机密）。以下代码示例演示如何设置机密和检索机密。

[https://github.com/Azure-Samples/key-vault-dotnet-core-quickstart/tree/master/akvdotnet](https://github.com/Azure-Samples/key-vault-dotnet-core-quickstart/tree/master/akvdotnet ) 中提供了整个控制台应用。

代码示例

添加指令

将以下指令添加到代码的顶部：

using System;
using System.Threading.Tasks;
using Microsoft.Azure.KeyVault;
using Microsoft.IdentityModel.Clients.ActiveDirectory;
using Microsoft.Azure.Management.ResourceManager.Fluent;
using Microsoft.Azure.Management.ResourceManager.Fluent.Authentication;

对 Key Vault 进行身份验证

本 .NET 快速入门依赖于使用环境变量来存储不应放入代码中的凭据。

在生成和运行应用之前，请使用 setx 命令将 akvClientId、akvClientSecret、akvTenantId 和 akvSubscriptionId 环境变量设置为上面记下的值。

Windows

setx akvClientId "<your-clientID>"
setx akvClientSecret "<your-clientSecret>"

Linux

export akvClientId = "<your-clientID>"
export akvClientSecret = "<your-clientSecret>"

MacOS

export akvClientId = "<your-clientID>"
export akvClientSecret = "<your-clientSecret>"

将这些环境变量分配到代码中的字符串，然后通过将这些字符串传递给 KeyVaultClient 类，来对应用程序进行身份验证：

string clientId = Environment.GetEnvironmentVariable("akvClientId");
string clientSecret = Environment.GetEnvironmentVariable("akvClientSecret");

KeyVaultClient kvClient = new KeyVaultClient(async (authority, resource, scope) =>
{
    var adCredential = new ClientCredential(clientId, clientSecret);
    var authenticationContext = new AuthenticationContext(authority, null);
    return (await authenticationContext.AcquireTokenAsync(resource, adCredential)).AccessToken;
});

保存机密

对应用程序进行身份验证后，可以使用 SetSecretAsync 方法将机密放入 Key Vault。这需要使用 Key Vault 的 URL，其格式为 https://<your-unique-keyvault-name>.vault.azure.cn/secrets/。还需要使用机密的名称 - 我们使用了“mySecret”。

await kvClient.SetSecretAsync($"{kvURL}", secretName, secretValue);

可以使用 az keyvault secret show 命令来验证是否设置了机密：

az keyvault secret show --vault-name <your-unique-keyvault-name> --name mySecret

检索机密

现在，可以使用 GetSecretAsync 方法检索以前设置的值

var keyvaultSecret = await kvClient.GetSecretAsync($"{kvURL}", secretName).ConfigureAwait(false);

机密现已保存为 keyvaultSecret.Value;。

清理资源

可以使用 Azure CLI 或 Azure PowerShell 来删除不再需要的 Key Vault 和相应的资源组。

az group delete -g "myResourceGroup"

Remove-AzResourceGroup -Name "myResourceGroup"

后续步骤

在本快速入门中，你创建了一个 Key Vault、存储了一个机密，然后检索了该机密。请查看 GitHub 中的整个控制台应用。

若要详细了解 Key Vault 以及如何将其与应用程序集成，请继续阅读以下文章。

实现使用 .NET 对 Azure Key Vault 进行服务到服务的身份验证
阅读 Azure Key Vault 概述
参阅 Azure Key Vault 开发人员指南
查看 Azure Key Vault 最佳做法

通过