快速入门:适用于 Java 的 Azure Key Vault 机密客户端库
适用于 Java 的 Azure Key Vault 机密客户端库入门。 请按照以下步骤安装程序包并试用基本任务的示例代码。
提示
如果你正在 Spring 应用程序中使用 Azure Key Vault 机密资源,建议将 Spring Cloud Azure 视为替代方法。 Spring Cloud Azure 是一个开源项目,提供 Spring 与 Azure 服务的无缝集成。 若要详细了解 Spring Cloud Azure,并查看使用 Key Vault 机密的示例,请参阅在 Spring Boot 应用程序中从 Azure Key Vault 加载机密。
其他资源:
先决条件
- Azure 订阅 - 创建试用版订阅。
- Java 开发工具包 (JDK) 8 或更高版本
- Apache Maven
- Azure CLI
本快速入门假设你在 Linux 终端窗口中运行 Azure CLI 和 Apache Maven。
设置
本快速入门结合使用 Azure Identity 库和 Azure CLI,向 Azure 服务验证用户身份。 开发人员还可以使用 Visual Studio 或 Visual Studio Code 来验证其调用。有关详细信息,请参阅使用 Azure Identity 客户端库对客户端进行身份验证。
登录 Azure
运行
login
命令。az cloud set -n AzureChinaCloud az login # az cloud set -n AzureCloud //means return to Public Azure.
如果 CLI 可以打开默认浏览器,它将这样做并加载 Azure 登录页。
否则,请在 https://aka.ms/deviceloginchina 处打开浏览器页,然后输入终端中显示的授权代码。
在浏览器中使用帐户凭据登录。
创建新的 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
安装包
在文本编辑器中打开 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>
创建资源组和 Key Vault
本快速入门使用预先创建的 Azure 密钥保管库。 可以遵循 Azure CLI 快速入门、Azure PowerShell 快速入门或 Azure 门户快速入门中的步骤创建 Key Vault。
或者,也可运行这些 Azure CLI 或 Azure PowerShell 命令。
重要
每个密钥保管库必须具有唯一的名称。 在以下示例中,将 <your-unique-keyvault-name> 替换为密钥保管库的名称。
az group create --name "myResourceGroup" -l "ChinaEast"
az keyvault create --name "<your-unique-keyvault-name>" -g "myResourceGroup" --enable-rbac-authorization
授予对 Key Vault 的访问权限
若要通过基于角色的访问控制 (RBAC) 授予应用程序对密钥保管库的权限,请使用 Azure CLI 命令 az role assignment create 分配角色。
az role assignment create --role "Key Vault Secrets User" --assignee "<app-id>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"
将 <app-id>
、<subscription-id>
、<resource-group-name>
和 <your-unique-keyvault-name>
替换为实际值。 <app-id>
是在 Azure Entra 中注册的应用程序的应用程序(客户端)ID。
设置环境变量
此应用程序使用密钥保管库名称作为名为 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
代码可以自动发现并使用分配给应用服务、虚拟机或其他服务的托管标识。 有关详细信息,请参阅托管标识概述。
在此示例中,密钥保管库的名称扩展为密钥保管库 URI,格式为 https://<your-key-vault-name>.vault.azure.cn
。 有关向密钥保管库进行身份验证的详细信息,请参阅开发人员指南。
String keyVaultName = System.getenv("KEY_VAULT_NAME");
String keyVaultUri = "https://" + keyVaultName + ".vault.azure.cn";
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 来删除不再需要的 Key Vault 和相应的资源组。
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.cn";
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 以及如何将其与应用程序集成,请继续阅读以下文章。