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

适用于 Java 的 Azure 密钥保管库 证书客户端库 - 版本 4.5.7

使用 Azure 密钥保管库，可以安全地管理和严格控制证书。 Azure 密钥保管库 证书客户端库支持 RSA 和 EC 密钥支持的证书。

可以在密钥保管库中保留多个证书和多个版本的同一证书。 Azure 密钥保管库中支持证书的加密密钥表示为 JSON Web 密钥 (JWK) 对象。 此库提供创建、检索、更新、删除、清除、备份、还原和列出证书及其版本的操作。

源代码 | API 参考文档 | 产品文档 | 示例

入门

添加包

包括 BOM 文件

请将 包含在 azure-sdk-bom 项目中，以依赖于库的正式发布 (正式发布) 版本。 在以下代码段中，将 {bom_version_to_target} 占位符替换为版本号。 若要详细了解 BOM，请参阅 AZURE SDK BOM 自述文件。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

然后在 dependencies 节中包含直接依赖项，不带版本标记，如下所示。

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-security-keyvault-certificates</artifactId>
    </dependency>
</dependencies>

包括直接依赖项

如果要依赖于 BOM 中不存在的特定版本的库，请将直接依赖项添加到项目中，如下所示。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-security-keyvault-certificates</artifactId>
    <version>4.5.7</version>
</dependency>

先决条件

• Java 开发工具包 (JDK) 8 或更高版本。
• 一个 Azure 订阅。
• 现有的 Azure 密钥保管库。 如果需要创建密钥保管库，可以在 Azure 门户中按照 本文档中的步骤操作。 或者，可以按照 本文档中的步骤使用 Azure CLI。

验证客户端

若要与 Azure 密钥保管库 服务交互，需要创建 类的CertificateClient实例、保管库 URL 和凭据对象。 本文档中显示的示例使用名为 的 DefaultAzureCredential凭据对象，该对象适用于大多数方案，包括本地开发和生产环境。 此外，我们建议使用 [托管标识][managed_identity] 在生产环境中进行身份验证。

可以在 Azure 标识文档中找到有关不同身份验证方式及其相应凭据类型的详细信息。

创建证书客户端

执行 最适合你的身份验证设置 并将 your-key-vault-url 替换为密钥保管库的 URL 后，可以创建 CertificateClient：

CertificateClient certificateClient = new CertificateClientBuilder()
    .vaultUrl("<your-key-vault-url>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

注意：对于使用异步客户端，请使用 CertificateAsyncClient 而不是 CertificateClient 和 调用 buildAsyncClient()。

关键概念

证书

Azure 密钥保管库支持具有机密内容类型的证书 (PKCS12&PEM) 。 证书可由 Azure 密钥保管库中 () EC&RSA 类型的密钥提供支持。 除了证书策略之外，还可以指定以下属性：

• enabled：指定证书是否已启用且可用。
• created：指示创建此版本的证书。
• updated：指示更新此版本的证书的时间。

证书客户端

证书客户端与 Azure 密钥保管库 服务执行交互，以获取、设置、更新、删除和列出证书及其版本。 客户端还支持密钥保管库中证书颁发者和联系人的 CRUD 操作。 异步 (CertificateAsyncClient) 和同步 (CertificateClient) 客户端存在于 SDK 中，允许根据应用程序的用例选择客户端。 初始化证书后，可以与 Azure 密钥保管库中的主要资源类型进行交互。

示例

同步 API

以下部分提供了几个代码片段，涵盖了一些最常见的 Azure 密钥保管库 证书服务任务，包括：

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

创建证书

创建要存储在 Azure 密钥保管库中的证书。

• beginCreateCertificate在 Azure 密钥保管库中创建新证书。 如果已存在同名证书，则会创建该证书的新版本。

SyncPoller<CertificateOperation, KeyVaultCertificateWithPolicy> certificatePoller =
    certificateClient.beginCreateCertificate("certificateName", CertificatePolicy.getDefault());
certificatePoller.waitUntil(LongRunningOperationStatus.SUCCESSFULLY_COMPLETED);
KeyVaultCertificate certificate = certificatePoller.getFinalResult();
System.out.printf("Certificate created with name \"%s\"%n", certificate.getName());

检索证书

通过调用 getCertificate 或 getCertificateVersion检索以前存储的证书。

KeyVaultCertificateWithPolicy certificate = certificateClient.getCertificate("<certificate-name>");
System.out.printf("Received certificate with name \"%s\", version %s and secret id %s%n",
    certificate.getProperties().getName(), certificate.getProperties().getVersion(), certificate.getSecretId());

更新现有证书

通过调用 updateCertificateProperties更新现有证书。

// Get the certificate to update.
KeyVaultCertificate certificate = certificateClient.getCertificate("<certificate-name>");
// Update certificate enabled status.
certificate.getProperties().setEnabled(false);
KeyVaultCertificate updatedCertificate = certificateClient.updateCertificateProperties(certificate.getProperties());
System.out.printf("Updated certificate with name \"%s\" and enabled status \"%s\"%n",
    updatedCertificate.getProperties().getName(), updatedCertificate.getProperties().isEnabled());

删除证书

通过调用 beginDeleteCertificate删除现有证书。

SyncPoller<DeletedCertificate, Void> deleteCertificatePoller =
    certificateClient.beginDeleteCertificate("<certificate-name>");

// Deleted certificate is accessible as soon as polling beings.
PollResponse<DeletedCertificate> pollResponse = deleteCertificatePoller.poll();

// Deletion date only works for a SoftDelete-enabled Key Vault.
System.out.printf("Deleted certificate with name \"%s\" and recovery id %s", pollResponse.getValue().getName(),
    pollResponse.getValue().getRecoveryId());

// Certificate is being deleted on server.
deleteCertificatePoller.waitForCompletion();

列出证书

通过调用 listPropertiesOfCertificates列出密钥保管库中的证书。

// List operations don't return the certificates with their full information. So, for each returned certificate we call
// getCertificate to get the certificate with all its properties excluding the policy.
for (CertificateProperties certificateProperties : certificateClient.listPropertiesOfCertificates()) {
    KeyVaultCertificate certificateWithAllProperties =
        certificateClient.getCertificateVersion(certificateProperties.getName(), certificateProperties.getVersion());
    System.out.printf("Received certificate with name \"%s\" and secret id %s",
        certificateWithAllProperties.getProperties().getName(), certificateWithAllProperties.getSecretId());
}

异步 API

以下部分提供了几个代码片段，涵盖了一些最常见的异步 Azure 密钥保管库 证书服务任务，包括：

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

注意：应在main类/线程中的函数调用后添加 System.in.read() 或 Thread.sleep() ，以允许在main应用程序/线程退出之前执行和完成异步函数/操作。

异步创建证书

创建要存储在 Azure 密钥保管库中的证书。

• beginCreateCertificate在 Azure 密钥保管库中创建新证书。 如果已存在同名证书，则会创建该证书的新版本。

// Creates a certificate using the default policy and polls on its progress.
certificateAsyncClient.beginCreateCertificate("<certificate-name>", CertificatePolicy.getDefault())
    .subscribe(pollResponse -> {
        System.out.println("---------------------------------------------------------------------------------");
        System.out.println(pollResponse.getStatus());
        System.out.println(pollResponse.getValue().getStatus());
        System.out.println(pollResponse.getValue().getStatusDetails());
    });

异步检索证书

通过调用 getCertificate 或 getCertificateVersion检索以前存储的证书。

certificateAsyncClient.getCertificate("<certificate-name>")
    .subscribe(certificateResponse ->
        System.out.printf("Certificate was returned with name \"%s\" and secretId %s%n",
            certificateResponse.getProperties().getName(), certificateResponse.getSecretId()));

异步更新现有证书

通过调用 updateCertificateProperties更新现有证书。

certificateAsyncClient.getCertificate("<certificate-name>")
    .flatMap(certificate -> {
        // Update enabled status of the certificate.
        certificate.getProperties().setEnabled(false);
        return certificateAsyncClient.updateCertificateProperties(certificate.getProperties());
    }).subscribe(certificateResponse -> System.out.printf("Certificate's enabled status: %s%n",
        certificateResponse.getProperties().isEnabled()));

异步删除证书

通过调用 beginDeleteCertificate删除现有证书。

certificateAsyncClient.beginDeleteCertificate("<certificate-name>")
    .subscribe(pollResponse -> {
        System.out.printf("Deletion status: %s%n", pollResponse.getStatus());
        System.out.printf("Deleted certificate name: %s%n", pollResponse.getValue().getName());
        System.out.printf("Certificate deletion date: %s%n", pollResponse.getValue().getDeletedOn());
    });

异步列出证书

通过调用 listPropertiesOfCertificates列出 Azure 密钥保管库中的证书。

// The List Certificates operation returns certificates without their full properties, so for each certificate returned
// we call `getCertificate` to get all its attributes excluding the policy.
certificateAsyncClient.listPropertiesOfCertificates()
    .flatMap(certificateProperties -> certificateAsyncClient
        .getCertificateVersion(certificateProperties.getName(), certificateProperties.getVersion()))
    .subscribe(certificateResponse ->
        System.out.printf("Received certificate with name \"%s\" and key id %s", certificateResponse.getName(),
            certificateResponse.getKeyId()));

疑难解答

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

常规

Azure 密钥保管库 证书客户端会引发异常。 例如，如果在删除证书后尝试检索证书，则会返回错误 404 ，指示找不到资源。 以下代码片段通过捕获异常并显示有关错误的其他信息来妥善处理该错误。

try {
    certificateClient.getCertificate("<deleted-certificate-name>");
} catch (ResourceNotFoundException e) {
    System.out.println(e.getMessage());
}

默认 HTTP 客户端

默认情况下，所有客户端库都使用 Netty HTTP 客户端。 添加上述依赖项会自动将客户端库配置为使用 Netty HTTP 客户端。 HTTP 客户端 Wiki 中详述了如何配置或更改 HTTP 客户端。

默认 SSL 库

默认情况下，所有客户端库均使用 Tomcat 原生 Boring SSL 库来为 SSL 操作启用原生级别性能。 无聊 SSL 库是一个 Uber JAR，包含适用于 Linux/macOS/Windows 的本机库，与 JDK 中的默认 SSL 实现相比，性能更佳。 有关详细信息（包括如何减小依赖项大小），请参阅 Wiki 的性能优化部分。

后续步骤

SDK 的 GitHub 存储库中提供了多个密钥保管库 Java SDK 示例。 这些示例提供了使用 密钥保管库 时经常遇到的其他方案的示例代码。

后续步骤示例

此处详细介绍了示例。

其他文档

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

贡献

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

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

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