Azure.Security.KeyVault.Certificates 4.6.0

.NET 的 Azure 密钥保管库证书客户端库

Azure 密钥保管库是一种云服务，它提供了在整个云应用程序中使用证书的安全存储和自动管理。可以在 Azure 密钥保管库中保持多个证书，以及相同证书的多个版本。保管库中的每个证书都关联有一个策略，该策略控制证书的颁发和有效期，以及当证书临近到期时应执行的操作。

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

源代码 | 包（NuGet） | API参考文档 | 产品文档 | 示例 | 迁移指南

入门指南

安装包

使用 NuGet 安装 .NET 的 Azure Key Vault 证书客户端库

dotnet add package Azure.Security.KeyVault.Certificates

先决条件

• 一个 Azure订阅。
• 一个现有的 Azure Key Vault。如果您需要创建 Azure Key Vault，可以使用 Azure 门户或 Azure CLI。
• 使用 RBAC（推荐）或 访问控制授权对现有 Azure Key Vault 的访问。

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

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

客户端认证

为了与 Azure Key Vault 服务交互，您需要创建 CertificateClient 类的一个实例。您需要一个 保管库 URL（您可以在门户中看到为“DNS名称”），以及用于实例化客户端对象的凭据。

下面显示的示例使用了一个 DefaultAzureCredential，这适用于大多数场景，包括本地开发和生产环境。此外，我们建议在生产环境中使用托管标识进行认证。您可以在 Azure Identity 文档中找到有关不同认证方式和相应的凭证类型的更多信息。

要使用下面的 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 Key Vault 中的基本资源。您将使用证书来加密和验证加密或签名后的数据。

CertificateClient

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

线程安全

我们保证所有客户端实例方法都是线程安全的，彼此独立（《指南》）。这确保了在多线程中的重新使用客户端实例总是安全的。

其他概念

客户端选项 | 访问响应 | 长时间运行的操作 | 处理失败 | 诊断 | 模拟 | 客户端生命周期

示例

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

以下部分提供了一些使用上面创建的 client客户端 的代码片段，涵盖了 Azure Key Vault 证书服务的一些最常见任务。

同步示例

• 创建证书
• 检索证书
• 更新现有证书
• 列出证书
• 删除证书

异步示例

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

创建证书

StartCreateCertificate 在 Azure Key Vault 中创建证书。如果已存在同名证书，则创建新版本。在创建证书时，用户可以指定控制证书生命周期的策略。如果没有指定策略，则使用默认策略。 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 Key Vault 中的证书的最新版本及其 CertificatePolicy。

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

GetCertificateVersion 获取保险库中证书的特定版本。

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

更新现有证书

UpdateCertificate 更新存储在 Azure Key Vault 中的证书。

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

KeyVaultCertificate updated = client.UpdateCertificateProperties(certificateProperties);

列出证书

GetCertificates 在保险库中枚举证书，返回证书的选定属性。不会返回证书的敏感字段。此操作需要 certificates/list 权限。

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

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

删除证书

DeleteCertificate 删除存储在 Azure Key Vault 中的证书的所有版本。当 Azure Key Vault 没有启用软删除时，此操作永久删除证书。如果启用软删除，则证书将被标记为删除，并可以可选地清除或恢复，直到其计划清除日期。

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 与其同步对应版本相同，但异步方法返回具有典型 "Async" 后缀，并返回一个 Task。

此示例使用指定的可选参数在 Azure Key Vault 中创建证书。

// 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 方法，但返回一个可使用 await foreach 语句的 AsyncPageable<CertificateProperties>。

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 Key Vault证书客户端库交互时，服务返回的错误对应于REST API请求返回的相同HTTP状态码。

例如，如果尝试检索在您的Azure Key Vault中不存在的密钥，将返回404错误，表示“未找到”。

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 Key Vault证书客户端库示例。这些示例提供了在使用Azure Key Vault时遇到的常见场景的示例代码。

• Sample1_HelloWorld.md - 用于与Azure Key Vault证书交互，包括

  • 创建证书
  • 获取现有证书
  • 更新现有证书
  • 删除证书

• Sample2_GetCertificates.md - 用于与Azure Key Vault证书交互的示例代码，包括

  • 创建证书
  • 列出Key Vault中所有证书
  • 列出指定证书的版本
  • 从Key Vault中删除证书
  • 列出Key Vault中已删除的证书

其他文档

• 有关Azure Key Vault的更详细文档，请参阅API参考文档。
• 有关密钥客户端库，请参阅Secrets客户端库。
• 有关密钥客户端库，请参阅Keys客户端库。

贡献

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

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

提交拉取请求时，CLA-bot将自动确定您是否需要提供CLA，并适当装饰PR（例如，标签、注释）。只需遵循机器人提供的说明即可。您在整个使用我们CLA的所有存储库中只需这样做一次。

本项目采用Microsoft开源行为准则。有关更多信息，请参阅行为准则常见问题解答或通过[email protected]联系以获取任何额外的问题或评论。