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

适用于 .NET 的 Azure 密钥保管库证书客户端库 - 版本 4.5.1

项目
04/06/2023

Azure 密钥保管库是一种云服务，可安全存储和自动管理整个云应用程序中使用的证书。多个证书和同一证书的多个版本可以保存在 Azure 密钥保管库中。保管库中的每个证书都有一个与之关联的策略，该策略控制证书的颁发和生存期，以及要作为证书即将过期采取的操作。

Azure 密钥保管库证书客户端库支持以编程方式管理证书，并提供创建、更新、列出和删除证书、策略、颁发者和联系人的方法。该库还支持管理挂起的证书操作和管理已删除的证书。

入门

安装包

使用 NuGet 安装适用于 .NET 的 Azure 密钥保管库证书客户端库：

dotnet add package Azure.Security.KeyVault.Certificates

先决条件

一个 Azure 订阅。
现有的 Azure 密钥保管库。如果需要创建 Azure 密钥保管库，可以使用 Azure 门户或 Azure CLI。
使用 RBAC (建议) 或访问控制授权现有 Azure 密钥保管库。

如果使用 Azure CLI，请将和 <your-key-vault-name> 替换为<your-resource-group-name>自己的唯一名称：

az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>

验证客户端

若要与 Azure 密钥保管库服务交互，需要创建 CertificateClient 类的实例。需要一个 保管库 URL（可能在门户中显示为“DNS 名称”），以及用于实例化客户端对象的凭据。

下面显示的示例使用 DefaultAzureCredential，它适用于大多数方案，包括本地开发和生产环境。此外，我们建议使用托管标识在生产环境中进行身份验证。可以在 Azure 标识文档中找到有关不同身份验证方式及其相应凭据类型的详细信息。

若要使用如下所示的 DefaultAzureCredential 提供程序或 Azure SDK 提供的其他凭据提供程序，必须先安装 Azure.Identity 包：

dotnet add package Azure.Identity

创建 CertificateClient

实例化 DefaultAzureCredential 以传递给客户端。如果多个客户端将使用相同的标识进行身份验证，则可以将令牌凭据的同一实例用于这些客户端。

// Create a new certificate client using the default credential from Azure.Identity using environment variables previously set,
// including AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID.
var client = new CertificateClient(vaultUri: new Uri(vaultUrl), credential: new DefaultAzureCredential());

关键概念

KeyVaultCertificate

是 KeyVaultCertificate Azure 密钥保管库中的基本资源。你将使用证书来加密和验证已加密或已签名的数据。

CertificateClient

CertificateClient使用可以从保管库获取证书、创建新证书和现有证书的新版本、更新证书元数据以及删除证书。还可以管理证书颁发者、联系人和证书的管理策略。以下示例对此进行了说明。

线程安全

我们保证所有客户端实例方法都是线程安全的，并且彼此独立 (准则) 。这可确保重用客户端实例的建议始终是安全的，即使在线程之间也是如此。

其他概念

示例

Azure.Security.KeyVault.Certificates 包支持同步和异步 API。

以下部分提供了使用client上面创建的几个代码片段，涵盖了一些最常见的 Azure 密钥保管库证书服务相关任务：

异步示例

异步创建证书
异步列出证书
异步删除证书

创建证书

StartCreateCertificate创建要存储在 Azure 密钥保管库中的证书。如果已存在同名证书，则会创建该证书的新版本。创建证书时，用户可以指定控制证书生存期的策略。如果未指定任何策略，将使用默认策略。操作 StartCreateCertificate 返回 CertificateOperation。以下示例使用默认策略创建自签名证书。

// Create a certificate. This starts a long running operation to create and sign the certificate.
CertificateOperation operation = client.StartCreateCertificate("MyCertificate", CertificatePolicy.Default);

// You can await the completion of the create certificate operation.
// You should run UpdateStatus in another thread or do other work like pumping messages between calls.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

KeyVaultCertificateWithPolicy certificate = operation.Value;

注意：根据证书颁发者和验证方法，证书创建和签名可能需要不确定的时间。用户应仅在操作可以在应用程序范围内合理完成时才等待证书操作，例如使用自签名证书或具有已知响应时间的颁发者。

检索证书

GetCertificate检索存储在 Azure 密钥保管库中的证书的最新版本及其 CertificatePolicy。

KeyVaultCertificateWithPolicy certificateWithPolicy = client.GetCertificate("MyCertificate");

GetCertificateVersion 检索保管库中证书的特定版本。

KeyVaultCertificate certificate = client.GetCertificateVersion(certificateWithPolicy.Name, certificateWithPolicy.Properties.Version);

更新现有证书

UpdateCertificate更新 Azure 密钥保管库中存储的证书。

CertificateProperties certificateProperties = new CertificateProperties(certificate.Id);
certificateProperties.Tags["key1"] = "value1";

KeyVaultCertificate updated = client.UpdateCertificateProperties(certificateProperties);

列出证书

GetCertificates 枚举保管库中的证书，并返回证书的 select 属性。不会返回证书的敏感字段。此操作需要证书/列表权限。

Pageable<CertificateProperties> allCertificates = client.GetPropertiesOfCertificates();

foreach (CertificateProperties certificateProperties in allCertificates)
{
    Console.WriteLine(certificateProperties.Name);
}

删除证书

DeleteCertificate删除存储在 Azure 密钥保管库中的所有证书版本。如果未为 Azure 密钥保管库启用软删除，此操作将永久删除证书。如果启用了软删除，则会将证书标记为要删除，并且可以选择清除或恢复证书，直到其计划的清除日期为止。

DeleteCertificateOperation operation = client.StartDeleteCertificate("MyCertificate");

// You only need to wait for completion if you want to purge or recover the certificate.
// You should call `UpdateStatus` in another thread or after doing additional work like pumping messages.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

DeletedCertificate certificate = operation.Value;
client.PurgeDeletedCertificate(certificate.Name);

异步创建证书

异步 API 与其同步 API 相同，但使用异步方法的典型“Async”后缀返回，并返回 Task。

此示例使用指定的可选参数在 Azure 密钥保管库中创建证书。

// Create a certificate. This starts a long running operation to create and sign the certificate.
CertificateOperation operation = await client.StartCreateCertificateAsync("MyCertificate", CertificatePolicy.Default);

// You can await the completion of the create certificate operation.
KeyVaultCertificateWithPolicy certificate = await operation.WaitForCompletionAsync();

异步列出证书

列出证书并不依赖于等待 GetPropertiesOfCertificatesAsync 方法，而是返回 AsyncPageable<CertificateProperties> 可与语句一起使用的 await foreach ：

AsyncPageable<CertificateProperties> allCertificates = client.GetPropertiesOfCertificatesAsync();

await foreach (CertificateProperties certificateProperties in allCertificates)
{
    Console.WriteLine(certificateProperties.Name);
}

异步删除证书

在清除证书之前异步删除证书时，可以等待 WaitForCompletionAsync 操作的方法。默认情况下，此循环无限期，但你可以通过传递 CancellationToken来取消它。

DeleteCertificateOperation operation = await client.StartDeleteCertificateAsync("MyCertificate");

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

DeletedCertificate certificate = operation.Value;
await client.PurgeDeletedCertificateAsync(certificate.Name);

故障排除

有关如何诊断各种故障方案的详细信息，请参阅故障排除指南。

常规

使用 .NET SDK 与 Azure 密钥保管库证书客户端库交互时，服务返回的错误对应于为 REST API 请求返回的相同 HTTP 状态代码。

例如，如果尝试检索 Azure 密钥保管库中不存在的密钥，则会返回错误404，指示 Not Found。

try
{
    KeyVaultCertificateWithPolicy certificateWithPolicy = client.GetCertificate("SomeCertificate");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

你会注意到记录了其他信息，例如操作的客户端请求 ID。

Message:
    Azure.RequestFailedException : Service request failed.
    Status: 404 (Not Found)
Content:
    {"error":{"code":"CertificateNotFound","message":"Certificate not found: MyCertificate"}}

Headers:
    Cache-Control: no-cache
    Pragma: no-cache
    Server: Microsoft-IIS/10.0
    x-ms-keyvault-region: westus
    x-ms-request-id: 625f870e-10ea-41e5-8380-282e5cf768f2
    x-ms-keyvault-service-version: 1.1.0.866
    x-ms-keyvault-network-info: addr=131.107.174.199;act_addr_fam=InterNetwork;
    X-AspNet-Version: 4.0.30319
    X-Powered-By: ASP.NET
    Strict-Transport-Security: max-age=31536000;includeSubDomains
    X-Content-Type-Options: nosniff
    Date: Tue, 18 Jun 2019 16:02:11 GMT
    Content-Length: 75
    Content-Type: application/json; charset=utf-8
    Expires: -1

后续步骤

此 GitHub 存储库中提供了多个 Azure 密钥保管库证书客户端库示例。这些示例提供了使用 Azure 密钥保管库时经常遇到的其他方案的示例代码：

Sample1_HelloWorld.md - 用于使用 Azure 密钥保管库证书，包括：
- 创建证书
- 获取现有证书
- 更新现有证书
- 删除证书
Sample2_GetCertificates.md - 使用 Azure 密钥保管库证书的示例代码，包括：
- 创建证书
- 列出密钥保管库中的所有证书
- 列出指定证书的版本
- 从密钥保管库中删除证书
- 列出密钥保管库中删除的证书

其他文档

有关 Azure 密钥保管库的更多文档，请参阅 API 参考文档。
有关机密客户端库，请参阅机密客户端库。
有关密钥客户端库，请参阅密钥客户端库。

供稿

有关构建、测试和参与这些库的详细信息，请参阅 CONTRIBUTING.md 。

本项目欢迎贡献和建议。大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。有关详细信息，请访问 https://cla.microsoft.com 。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。直接按机器人提供的说明操作。只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与联系。

曝光数

通过

适用于 .NET 的 Azure 密钥保管库 证书客户端库 - 版本 4.5.1

入门

安装包