快速入門：適用於 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 祕密的範例，請參閱在 Spring Boot 應用程式中從 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-secrets-java 的新 Java 主控台應用程式。

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

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

cd akv-secrets-java

Install the package

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

    <dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-security-keyvault-secrets</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 Secrets 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.secrets.SecretClient;
import com.azure.security.keyvault.secrets.SecretClientBuilder;
import com.azure.security.keyvault.secrets.models.DeletedSecret;
import com.azure.security.keyvault.secrets.models.KeyVaultSecret;

驗證並建立用戶端

大部分 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";

SecretClient secretClient = new SecretClientBuilder()
    .vaultUrl(keyVaultUri)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

儲存秘密

現在，您的應用程式已通過驗證，您可以使用 secretClient.setSecret 方法將秘密放入金鑰保存庫中。這需要密碼的名稱 -- 我們已將 "mySecret" 值指派給此範例中的 secretName 變數。

secretClient.setSecret(new KeyVaultSecret(secretName, secretValue));

您可以確認祕密是否已使用 az keyvault secret show 命令來加以設定：

az keyvault secret show --vault-name <your-unique-key-vault-name> --name mySecret

擷取祕密

您現在可以使用 secretClient.getSecret 方法來擷取先前設定的秘密。

KeyVaultSecret retrievedSecret = secretClient.getSecret(secretName);

您現在可以使用 retrievedSecret.getValue() 來存取已擷取的祕密值。

刪除祕密

最後，我們將使用 secretClient.beginDeleteSecret 方法從金鑰保存庫中刪除秘密。

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

SyncPoller<DeletedSecret, Void> deletionPoller = secretClient.beginDeleteSecret(secretName);
deletionPoller.waitForCompletion();

您可以使用 az keyvault secret show 命令來確認祕密是否已刪除：

az keyvault secret show --vault-name <your-unique-key-vault-name> --name mySecret

清除資源

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

az group delete -g "myResourceGroup"

Remove-AzResourceGroup -Name "myResourceGroup"

範例指令碼

package com.keyvault.secrets.quickstart;

import java.io.Console;

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

import com.azure.security.keyvault.secrets.SecretClient;
import com.azure.security.keyvault.secrets.SecretClientBuilder;
import com.azure.security.keyvault.secrets.models.DeletedSecret;
import com.azure.security.keyvault.secrets.models.KeyVaultSecret;

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);

        SecretClient secretClient = new SecretClientBuilder()
            .vaultUrl(keyVaultUri)
            .credential(new DefaultAzureCredentialBuilder().build())
            .buildClient();

        Console con = System.console();

        String secretName = "mySecret";

        System.out.println("Please provide the value of your secret > ");

        String secretValue = con.readLine();

        System.out.print("Creating a secret in " + keyVaultName + " called '" + secretName + "' with value '" + secretValue + "' ... ");

        secretClient.setSecret(new KeyVaultSecret(secretName, secretValue));

        System.out.println("done.");
        System.out.println("Forgetting your secret.");

        secretValue = "";
        System.out.println("Your secret's value is '" + secretValue + "'.");

        System.out.println("Retrieving your secret from " + keyVaultName + ".");

        KeyVaultSecret retrievedSecret = secretClient.getSecret(secretName);

        System.out.println("Your secret's value is '" + retrievedSecret.getValue() + "'.");
        System.out.print("Deleting your secret from " + keyVaultName + " ... ");

        SyncPoller<DeletedSecret, Void> deletionPoller = secretClient.beginDeleteSecret(secretName);
        deletionPoller.waitForCompletion();

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

下一步

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

共用方式為