通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：适用于 .NET 的 Azure 密钥保管库证书客户端库

  • 项目

适用于 .NET 的 Azure Key Vault 证书客户端库入门。 Azure Key Vault 是一项云服务，它为证书提供了安全的存储。 可以安全地存储密钥、密码、证书和其他机密。 可以通过 Azure 门户创建和管理 Azure Key Vault。 本快速入门介绍如何使用 .NET 客户端库在 Azure 密钥保管库中创建、检索和删除证书。

Key Vault 客户端库资源：

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

有关 Key Vault 和证书的详细信息，请参阅：

先决条件

本快速入门使用 dotnet 和 Azure CLI。

安装

本快速入门结合使用 Azure Identity 库和 Azure CLI，向 Azure 服务验证用户身份。 开发人员还可以使用 Visual Studio 或 Visual Studio Code 来验证其调用。有关详细信息，请参阅使用 Azure Identity 客户端库对客户端进行身份验证。

登录 Azure

  1. 运行 login 命令。

    az login

    如果 CLI 可以打开默认浏览器，它将这样做并加载 Azure 登录页。

    否则，请在 https://aka.ms/devicelogin 处打开浏览器页，然后输入终端中显示的授权代码。

  2. 在浏览器中使用帐户凭据登录。

授予对 Key Vault 的访问权限

若要通过基于角色的访问控制 (RBAC) 授予对密钥保管库的权限，请使用 Azure CLI 命令 az role assignment create 将角色分配给你的“用户主体名称”(UPN)。

az role assignment create --role "Key Vault Certificate Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

将 <upn>、<subscription-id>、<resource-group-name> 和 <your-unique-keyvault-name> 替换为你的实际值。 你的 UPN 通常采用电子邮件地址格式（例如 username@domain.com）。

创建新的 .NET 控制台应用

  1. 在命令外壳中，运行以下命令以创建名为 key-vault-console-app 的项目：

    dotnet new console --name key-vault-console-app

  2. 切换到新创建的 key-vault-console-app 目录，然后运行以下命令来生成项目：

    dotnet build

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

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

安装包

在命令外壳中，安装适用于 .NET 的 Azure Key Vault 证书客户端库：

dotnet add package Azure.Security.KeyVault.Certificates

对于本快速入门，还需要安装 Azure 标识客户端库：

dotnet add package Azure.Identity

设置环境变量。

应用程序从名为 KEY_VAULT_NAME 的环境变量中获取密钥保管库名称。

Windows

set KEY_VAULT_NAME=<your-key-vault-name>

Windows PowerShell

$Env:KEY_VAULT_NAME="<your-key-vault-name>"

macOS 或 Linux

export KEY_VAULT_NAME=<your-key-vault-name>

对象模型

使用适用于 .NET 的 Azure Key Vault 证书客户端库管理证书。 代码示例部分介绍了如何创建客户端，以及如何设置、检索和删除证书。

代码示例

添加指令

在 Program.cs 的顶部添加以下指令：

using System;
using Azure.Identity;
using Azure.Security.KeyVault.Certificates;

进行身份验证并创建客户端

对大多数 Azure 服务的应用程序请求必须获得授权。 要在代码中实现与 Azure 服务的无密码连接，建议使用 Azure 标识客户端库提供的 DefaultAzureCredential 类。 DefaultAzureCredential 支持多种身份验证方法，并确定应在运行时使用哪种方法。 通过这种方法，你的应用可在不同环境（本地与生产）中使用不同的身份验证方法，而无需实现特定于环境的代码。

在本快速入门中，DefaultAzureCredential 使用登录到 Azure CLI 的本地开发用户的凭据对密钥保管库进行身份验证。 将应用程序部署到 Azure 时，相同的 DefaultAzureCredential 代码可以自动发现并使用分配给应用服务、虚拟机或其他服务的托管标识。 有关详细信息，请参阅托管标识概述。

在此示例中，密钥保管库的名称扩展为密钥保管库 URI，格式为 https://<your-key-vault-name>.vault.azure.net。 有关向密钥保管库进行身份验证的详细信息，请参阅开发人员指南。

string keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
var kvUri = "https://" + keyVaultName + ".vault.azure.net";

var client = new CertificateClient(new Uri(kvUri), new DefaultAzureCredential());

保存证书

在此示例中，为简单起见，可以将自签名证书与默认颁发策略一起使用。 对于此任务，请使用 StartCreateCertificateAsync 方法。 该方法的参数接受证书名和证书策略。

var operation = await client.StartCreateCertificateAsync("myCertificate", CertificatePolicy.Default);
var certificate = await operation.WaitForCompletionAsync();

注意

如果证书名已存在，则上面的代码将创建该证书的新版本。

检索证书

现在，可以使用 GetCertificateAsync 方法检索以前创建的证书。

var certificate = await client.GetCertificateAsync("myCertificate");

删除证书

最后，让我们使用 StartDeleteCertificateAsync 和 PurgeDeletedCertificateAsync 方法从密钥保管库中删除并清除证书。

var operation = await client.StartDeleteCertificateAsync("myCertificate");

// You only need to wait for completion if you want to purge or recover the certificate.
await operation.WaitForCompletionAsync();

var certificate = operation.Value;
await client.PurgeDeletedCertificateAsync("myCertificate");

示例代码

通过完成以下步骤，将 .NET 控制台应用修改为与密钥保管库交互：

  • 将 Program.cs 中的代码替换为以下代码：

    using System;
using System.Threading.Tasks;
using Azure.Identity;
using Azure.Security.KeyVault.Certificates;

namespace key_vault_console_app
{
    class Program
    {
        static async Task Main(string[] args)
        {
            const string certificateName = "myCertificate";
            var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
            var kvUri = $"https://{keyVaultName}.vault.azure.net";

            var client = new CertificateClient(new Uri(kvUri), new DefaultAzureCredential());

            Console.Write($"Creating a certificate in {keyVaultName} called '{certificateName}' ...");
            CertificateOperation operation = await client.StartCreateCertificateAsync(certificateName, CertificatePolicy.Default);
            await operation.WaitForCompletionAsync();
            Console.WriteLine(" done.");

            Console.WriteLine($"Retrieving your certificate from {keyVaultName}.");
            var certificate = await client.GetCertificateAsync(certificateName);
            Console.WriteLine($"Your certificate version is '{certificate.Value.Properties.Version}'.");

            Console.Write($"Deleting your certificate from {keyVaultName} ...");
            DeleteCertificateOperation deleteOperation = await client.StartDeleteCertificateAsync(certificateName);
            // You only need to wait for completion if you want to purge or recover the certificate.
            await deleteOperation.WaitForCompletionAsync();
            Console.WriteLine(" done.");

            Console.Write($"Purging your certificate from {keyVaultName} ...");
            await client.PurgeDeletedCertificateAsync(certificateName);
            Console.WriteLine(" done.");
        }
    }
}

测试和验证

执行以下命令以生成项目

dotnet build

随即显示以下输出的变体：

Creating a certificate in mykeyvault called 'myCertificate' ... done.
Retrieving your certificate from mykeyvault.
Your certificate version is '8532359bced24e4bb2525f2d2050738a'.
Deleting your certificate from mykeyvault ... done
Purging your certificate from mykeyvault ... done

后续步骤

在本快速入门中，你创建了一个密钥保管库，存储了一个证书，然后检索了该证书。

若要详细了解 Key Vault 以及如何将其与应用集成，请参阅以下文章：