快速入門：適用於 Java 的 Azure Key Vault 金鑰用戶端程式庫

發行項
10/05/2024

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

其他資源：

必要條件

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-keys-java 的新 Java 主控台應用程式。

mvn archetype:generate -DgroupId=com.keyvault.keys.quickstart
                       -DartifactId=akv-keys-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.keys.quickstart
[INFO] Parameter: artifactId, Value: akv-keys-java
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.keyvault.keys.quickstart
[INFO] Parameter: packageInPathFormat, Value: com/keyvault/quickstart
[INFO] Parameter: package, Value: com.keyvault.keys.quickstart
[INFO] Parameter: groupId, Value: com.keyvault.keys.quickstart
[INFO] Parameter: artifactId, Value: akv-keys-java
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Project created from Archetype in dir: /home/user/quickstarts/akv-keys-java
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  38.124 s
[INFO] Finished at: 2019-11-15T13:19:06-08:00
[INFO] ------------------------------------------------------------------------

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

cd akv-keys-java

Install the package

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

    <dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-security-keyvault-keys</artifactId>
      <version>4.2.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 Crypto 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.keys.KeyClient;
import com.azure.security.keyvault.keys.KeyClientBuilder;
import com.azure.security.keyvault.keys.models.DeletedKey;
import com.azure.security.keyvault.keys.models.KeyType;
import com.azure.security.keyvault.keys.models.KeyVaultKey;

驗證並建立用戶端

大部分 Azure 服務的應用程式要求都必須獲得授權。在程式碼中實作對 Azure 服務的無密碼連線時，建議使用 DefaultAzureCredential 類別。 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";

KeyClient keyClient = new KeyClientBuilder()
    .vaultUrl(keyVaultUri)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

建立金鑰

現在應用程式已通過驗證，您可以使用 keyClient.createKey 方法在金鑰保存庫中建立金鑰。這需要金鑰名稱和金鑰類型。我們已將 "myKey" 值指派給 keyName 變數，並在此範例中使用 RSA KeyType。

keyClient.createKey(keyName, KeyType.RSA);

您可以確認金鑰是否已使用 az keyvault key show 命令來加以設定：

az keyvault key show --vault-name <your-unique-key-vault-name> --name myKey

擷取金鑰

您現在可以使用 keyClient.getKey 方法來擷取先前建立的金鑰。

KeyVaultKey retrievedKey = keyClient.getKey(keyName);

您現在可以使用 retrievedKey.getProperties、retrievedKey.getKeyOperations 等作業來存取已取出金鑰的詳細資料。

刪除金鑰

最後，我們將使用 keyClient.beginDeleteKey 方法從金鑰保存庫中刪除金鑰。

刪除金鑰是長時間執行的作業，您可以輪詢進度或等待其完成。

SyncPoller<DeletedKey, Void> deletionPoller = keyClient.beginDeleteKey(keyName);
deletionPoller.waitForCompletion();

您可以確認金鑰是否已使用 az keyvault key show 命令來加以刪除：

az keyvault key show --vault-name <your-unique-key-vault-name> --name myKey

清除資源

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

az group delete -g "myResourceGroup"

Remove-AzResourceGroup -Name "myResourceGroup"

範例指令碼

package com.keyvault.keys.quickstart;

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

import com.azure.security.keyvault.keys.KeyClient;
import com.azure.security.keyvault.keys.KeyClientBuilder;
import com.azure.security.keyvault.keys.models.DeletedKey;
import com.azure.security.keyvault.keys.models.KeyType;
import com.azure.security.keyvault.keys.models.KeyVaultKey;

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 key vault URI = %s \n", keyVaultName, keyVaultUri);

        KeyClient keyClient = new KeyClientBuilder()
             .vaultUrl(keyVaultUri)
             .credential(new DefaultAzureCredentialBuilder().build())
             .buildClient();

        String keyName = "myKey";

        System.out.print("Creating a key in " + keyVaultName + " called '" + keyName + " ... ");

        keyClient.createKey(keyName, KeyType.RSA);

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

        KeyVaultKey retrievedKey = keyClient.getKey(keyName);

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

        SyncPoller<DeletedKey, Void> deletionPoller = keyClient.beginDeleteKey(keyName);
        deletionPoller.waitForCompletion();

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

下一步

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

共用方式為