快速入門：適用於 Java 的 Azure Key Vault 憑證用戶端程式庫 (憑證)

發行項
10/05/2024

開始使用適用於 Java 的 Azure Key Vault 憑證用戶端程式庫。請遵循下列步驟來安裝套件，並試用基本工作的程式碼範例。

提示

如果您在 Spring 應用程式中使用 Azure Key Vault 憑證資源，建議您考慮將 Spring Cloud Azure 作為替代方案。 Spring Cloud Azure 是開放原始碼專案，可提供與 Azure 服務的 Spring 無縫整合。若要深入了解 Spring Cloud Azure，以及查看使用 Key Vault 憑證的範例，請參閱使用 Azure Key Vault 憑證在 Spring Boot 中啟用 HTTPS。

其他資源：

必要條件

Azure 訂用帳戶 - 建立免費帳戶。
Java 開發套件 (JDK) 8 版或更新版本
Apache Maven
Azure CLI

本快速入門假設您是在 Linux 終端機視窗中執行 Azure CLI 和 Apache Maven。

設定

本快速入門會使用 Azure 身分識別程式庫搭配 Azure CLI，向 Azure 服務驗證使用者。開發人員也可以使用 Visual Studio 或 Visual Studio Code 來驗證其呼叫。如需詳細資訊，請參閱使用 Azure 身分識別用戶端程式庫驗證用戶端。

執行 login 命令。
```
az login
```
如果此 CLI 可以開啟您的預設瀏覽器，它會開啟瀏覽器並載入 Azure 登入頁面。

否則，請在 https://aka.ms/devicelogin 中開啟瀏覽器頁面，並輸入顯示在您的終端機中的授權碼。
請在瀏覽器中使用您的帳戶認證登入。

建立新的 Java 主控台應用程式

在主控台視窗中，使用 mvn 命令建立名為 akv-certificates-java 的新 Java 主控台應用程式。

mvn archetype:generate -DgroupId=com.keyvault.certificates.quickstart
                       -DartifactId=akv-certificates-java
                       -DarchetypeArtifactId=maven-archetype-quickstart
                       -DarchetypeVersion=1.4
                       -DinteractiveMode=false

產生專案的輸出會顯示如下：

[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.4
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: com.keyvault.certificates.quickstart
[INFO] Parameter: artifactId, Value: akv-certificates-java
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.keyvault.certificates.quickstart
[INFO] Parameter: packageInPathFormat, Value: com/keyvault/quickstart
[INFO] Parameter: package, Value: com.keyvault.certificates.quickstart
[INFO] Parameter: groupId, Value: com.keyvault.certificates.quickstart
[INFO] Parameter: artifactId, Value: akv-certificates-java
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Project created from Archetype in dir: /home/user/quickstarts/akv-certificates-java
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  38.124 s
[INFO] Finished at: 2019-11-15T13:19:06-08:00
[INFO] ------------------------------------------------------------------------

將目錄變更為新建立的 akv-certificates-java/ 資料夾。

cd akv-certificates-java

Install the package

在文字編輯器中開啟 pom.xml 檔案。將下列相依性元素新增至相依性群組。

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

    <dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-identity</artifactId>
      <version>1.2.0</version>
    </dependency>

建立資源群組和金鑰保存庫

本快速入門會使用預先建立的 Azure 金鑰保存庫。您可以遵循 Azure CLI 快速入門、Azure PowerShell 快速入門或 Azure 入口網站快速入門中的步驟來建立金鑰保存庫。

或者，您也可以直接執行這些 Azure CLI 或 Azure PowerShell 命令。

重要

每個金鑰保存庫必須有唯一的名稱。在下列範例中，將 <your-unique-keyvault-name> 取代為您的金鑰保存庫名稱。

Azure CLI
Azure PowerShell

az group create --name "myResourceGroup" -l "EastUS"

az keyvault create --name "<your-unique-keyvault-name>" -g "myResourceGroup" --enable-rbac-authorization

New-AzResourceGroup -Name myResourceGroup -Location eastus

New-AzKeyVault -Name <your-unique-keyvault-name> -ResourceGroupName myResourceGroup -Location eastus

授與對金鑰保存庫的存取權

若要透過角色型存取控制 (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)。

設定環境變數

此應用程式使用您的金鑰保存庫名稱作為名為 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>

物件模型

適用於 Java 的 Azure Key Vault 憑證用戶端程式庫可讓您管理憑證。程式碼範例一節說明如何建立用戶端、建立憑證、擷取憑證及刪除憑證。

整個主控台應用程式如下。

程式碼範例

新增指示詞

將下列指示詞新增至程式碼頂端：

import com.azure.core.util.polling.SyncPoller;
import com.azure.identity.DefaultAzureCredentialBuilder;

import com.azure.security.keyvault.certificates.CertificateClient;
import com.azure.security.keyvault.certificates.CertificateClientBuilder;
import com.azure.security.keyvault.certificates.models.CertificateOperation;
import com.azure.security.keyvault.certificates.models.CertificatePolicy;
import com.azure.security.keyvault.certificates.models.DeletedCertificate;
import com.azure.security.keyvault.certificates.models.KeyVaultCertificate;
import com.azure.security.keyvault.certificates.models.KeyVaultCertificateWithPolicy;

驗證並建立用戶端

對大部分 Azure 服務的應用程式要求都必須獲得授權。使用 DefaultAzureCredential 是在您的程式碼中實作 Azure 服務無密碼連線的建議方法。 DefaultAzureCredential 支援多個驗證方法，並在執行階段判斷應該使用哪個方法。此方法可讓您的應用程式在不同的環境中 (本機或實際執行環境) 使用不同的驗證方法，而不需要實作環境特有的程式碼。

在本快速入門中，DefaultAzureCredential 使用已登入 Azure CLI 之本機開發使用者的認證向金鑰保存庫進行驗證。將應用程式部署至 Azure 時，相同的 DefaultAzureCredential 程式碼可以自動探索並使用指派給 App Service、虛擬機器或其他服務的受控識別。如需詳細資訊，請參閱受控識別概觀。

在此範例中，金鑰保存庫的名稱會以 https://<your-key-vault-name>.vault.azure.net 格式，擴充至金鑰保存庫 URI。如需對金鑰保存庫進行驗證的詳細資訊，請參閱開發人員指南。

String keyVaultName = System.getenv("KEY_VAULT_NAME");
String keyVaultUri = "https://" + keyVaultName + ".vault.azure.net";

CertificateClient certificateClient = new CertificateClientBuilder()
    .vaultUrl(keyVaultUri)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

儲存秘密

現在應用程式已通過驗證，您可以使用 certificateClient.beginCreateCertificate 方法在金鑰保存庫中建立憑證。這需要憑證的名稱和憑證原則 -- 我們已將 "myCertificate" 值指派給此範例中的 certificateName 變數，並使用預設原則。

憑證建立是長時間執行的作業，您可以輪詢進度或等待其完成。

SyncPoller<CertificateOperation, KeyVaultCertificateWithPolicy> certificatePoller =
    certificateClient.beginCreateCertificate(certificateName, CertificatePolicy.getDefault());
certificatePoller.waitForCompletion();

建立完成後，您可以透過下列呼叫取得憑證：

KeyVaultCertificate createdCertificate = certificatePoller.getFinalResult();

擷取憑證

您現在可以使用 certificateClient.getCertificate 方法擷取先前建立的憑證。

KeyVaultCertificate retrievedCertificate = certificateClient.getCertificate(certificateName);

您現在可以使用 retrievedCertificate.getName、retrievedCertificate.getProperties 等作業來存取已取出之憑證的詳細資料，以及其內容 retrievedCertificate.getCer。

刪除憑證

最後，我們將使用 certificateClient.beginDeleteCertificate 方法 (也是長時間執行的作業)，從您的金鑰保存庫中刪除憑證。

SyncPoller<DeletedCertificate, Void> deletionPoller = certificateClient.beginDeleteCertificate(certificateName);
deletionPoller.waitForCompletion();

清除資源

若不再需要，您可以使用 Azure CLI 或 Azure PowerShell 來移除金鑰保存庫和對應的資源群組。

az group delete -g "myResourceGroup"

Remove-AzResourceGroup -Name "myResourceGroup"

範例指令碼

package com.keyvault.certificates.quickstart;

import com.azure.core.util.polling.SyncPoller;
import com.azure.identity.DefaultAzureCredentialBuilder;

import com.azure.security.keyvault.certificates.CertificateClient;
import com.azure.security.keyvault.certificates.CertificateClientBuilder;
import com.azure.security.keyvault.certificates.models.CertificateOperation;
import com.azure.security.keyvault.certificates.models.CertificatePolicy;
import com.azure.security.keyvault.certificates.models.DeletedCertificate;
import com.azure.security.keyvault.certificates.models.KeyVaultCertificate;
import com.azure.security.keyvault.certificates.models.KeyVaultCertificateWithPolicy;

public class App {
    public static void main(String[] args) throws InterruptedException, IllegalArgumentException {
        String keyVaultName = System.getenv("KEY_VAULT_NAME");
        String keyVaultUri = "https://" + keyVaultName + ".vault.azure.net";

        System.out.printf("key vault name = %s and kv uri = %s \n", keyVaultName, keyVaultUri);

        CertificateClient certificateClient = new CertificateClientBuilder()
            .vaultUrl(keyVaultUri)
            .credential(new DefaultAzureCredentialBuilder().build())
            .buildClient();

        String certificateName = "myCertificate";

        System.out.print("Creating a certificate in " + keyVaultName + " called '" + certificateName + " ... ");

        SyncPoller<CertificateOperation, KeyVaultCertificateWithPolicy> certificatePoller =
            certificateClient.beginCreateCertificate(certificateName, CertificatePolicy.getDefault());
        certificatePoller.waitForCompletion();

        System.out.print("done.");
        System.out.println("Retrieving certificate from " + keyVaultName + ".");

        KeyVaultCertificate retrievedCertificate = certificateClient.getCertificate(certificateName);

        System.out.println("Your certificate's ID is '" + retrievedCertificate.getId() + "'.");
        System.out.println("Deleting your certificate from " + keyVaultName + " ... ");

        SyncPoller<DeletedCertificate, Void> deletionPoller = certificateClient.beginDeleteCertificate(certificateName);
        deletionPoller.waitForCompletion();

        System.out.print("done.");
    }
}

下一步

在本快速入門中，您已建立金鑰保存庫和憑證、擷取該憑證然後刪除。若要深入了解 Key Vault 以及要如何將其與應用程式整合，請繼續閱讀下列文章。

共用方式為