你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
适用于 .NET 的 Azure 密钥保管库 证书客户端库 - 版本 4.5.1
Azure 密钥保管库 是一种云服务,可安全存储和自动管理整个云应用程序中使用的证书。 多个证书和同一证书的多个版本可以保存在 Azure 密钥保管库中。 保管库中的每个证书都有一个与之关联的策略,该策略控制证书的颁发和生存期,以及要作为证书即将过期采取的操作。
Azure 密钥保管库证书客户端库支持以编程方式管理证书,并提供创建、更新、列出和删除证书、策略、颁发者和联系人的方法。 该库还支持管理挂起的证书操作和管理已删除的证书。
源代码 | 包 (NuGet) | API 参考文档 | 产品文档 | 样品 | 迁移指南
使用 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
实例化 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
Azure 密钥保管库中的基本资源。 你将使用证书来加密和验证已加密或已签名的数据。
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 密钥保管库 证书的示例代码,包括:
- 创建证书
- 列出密钥保管库中的所有证书
- 列出指定证书的版本
- 从密钥保管库中删除证书
- 列出密钥保管库中删除的证书
有关构建、测试和参与这些库的详细信息,请参阅 CONTRIBUTING.md 。
本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA),并声明你有权(并且确实有权)授予我们使用你的贡献的权利。 有关详细信息,请访问 https://cla.microsoft.com 。
提交拉取请求时,CLA 机器人将自动确定你是否需要提供 CLA,并相应地修饰 PR(例如标签、注释)。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。
此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息,请参阅行为准则常见问题解答,或如果有任何其他问题或意见,请与 联系。