Guia de início rápido: biblioteca de cliente do Azure Key Vault Certificate para Java (Certificados)

Artigo
04/08/2024

Introdução à biblioteca de cliente do Azure Key Vault Certificate para Java. Siga as etapas abaixo para instalar o pacote e experimentar o código de exemplo para tarefas básicas.

Gorjeta

Se você estiver trabalhando com recursos do Azure Key Vault Certificates em um aplicativo Spring, recomendamos que considere o Spring Cloud Azure como uma alternativa. O Spring Cloud Azure é um projeto de código aberto que fornece integração perfeita do Spring com os serviços do Azure. Para saber mais sobre o Spring Cloud Azure e ver um exemplo usando certificados do Key Vault, consulte Habilitar HTTPS no Spring Boot com certificados do Azure Key Vault.

Recursos adicionais:

Pré-requisitos

Uma assinatura do Azure - crie uma gratuitamente.
Java Development Kit (JDK) versão 8 ou superior
Apache Maven
CLI do Azure

Este início rápido pressupõe que você esteja executando a CLI do Azure e o Apache Maven em uma janela de terminal Linux.

Configuração

Este guia de início rápido está usando a biblioteca de Identidade do Azure com a CLI do Azure para autenticar o usuário nos Serviços do Azure. Os desenvolvedores também podem usar o Visual Studio ou o Visual Studio Code para autenticar suas chamadas, para obter mais informações, consulte Autenticar o cliente com a biblioteca de cliente do Azure Identity.

Execute o comando login.
```
az login
```
Se a CLI puder abrir seu navegador padrão, ela fará isso e carregará uma página de entrada do Azure.

Caso contrário, abra uma página do navegador e https://aka.ms/devicelogin insira o código de autorização exibido no seu terminal.
Inicie sessão com as credenciais da sua conta no browser.

Criar um novo aplicativo de console Java

Em uma janela do console, use o mvn comando para criar um novo aplicativo de console Java com o nome akv-certificates-java.

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

A saída da geração do projeto será mais ou menos assim:

[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] ------------------------------------------------------------------------

Altere seu diretório para a pasta recém-criada akv-certificates-java/ .

cd akv-certificates-java

Instalar o pacote

Abra o arquivo pom.xml no editor de texto. Adicione os seguintes elementos de dependência ao grupo de dependências.

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

Criar um grupo de recursos e um cofre de chaves

Este guia de início rápido usa um cofre de chaves do Azure pré-criado. Você pode criar um cofre de chaves seguindo as etapas no início rápido da CLI do Azure, início rápido do Azure PowerShell ou início rápido do portal do Azure.

Como alternativa, você pode simplesmente executar os comandos da CLI do Azure ou do Azure PowerShell abaixo.

Importante

Cada cofre de chaves deve ter um nome exclusivo. Substitua <your-unique-keyvault-name> pelo nome do seu cofre de chaves nos exemplos a seguir.

CLI do Azure
Azure PowerShell

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

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

New-AzResourceGroup -Name myResourceGroup -Location eastus

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

Para conceder permissões ao seu aplicativo para seu cofre de chaves por meio do RBAC (Controle de Acesso Baseado em Função), atribua uma função usando o comando az role assignment create da CLI do Azure.

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>"

Para conceder permissões ao seu aplicativo para seu cofre de chaves por meio do RBAC (Controle de Acesso Baseado em Função), atribua uma função usando o cmdlet New-AzRoleAssignment do Azure PowerShell.

New-AzRoleAssignment -ObjectId "<app-id>" -RoleDefinitionName "Key Vault Secrets User" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

Substitua <app-id>, <subscription-id>, <resource-group-name> e <your-unique-keyvault-name> pelos seus valores reais. <app-id> é a ID do Aplicativo (cliente) do seu aplicativo registrado no Azure AD.

Definir variáveis de ambiente

Este aplicativo está usando o nome do cofre de chaves como uma variável de ambiente chamada KEY_VAULT_NAME.

Windows

set KEY_VAULT_NAME=<your-key-vault-name>

Windows PowerShell

$Env:KEY_VAULT_NAME="<your-key-vault-name>"

macOS ou Linux

export KEY_VAULT_NAME=<your-key-vault-name>

Modelo de objeto

A biblioteca de cliente do Azure Key Vault Certificate para Java permite gerenciar certificados. A seção Exemplos de código mostra como criar um cliente, criar um certificado, recuperar um certificado e excluir um certificado.

Todo o aplicativo do console está abaixo.

Exemplos de código

Adicionar diretivas

Adicione as seguintes diretivas à parte superior do seu código:

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;

Autenticar e criar um cliente

As solicitações de aplicativo para a maioria dos serviços do Azure devem ser autorizadas. Usar o DefaultAzureCredential é a abordagem recomendada para implementar conexões sem senha aos serviços do Azure em seu código. DefaultAzureCredential suporta vários métodos de autenticação e determina qual método deve ser usado em tempo de execução. Essa abordagem permite que seu aplicativo use métodos de autenticação diferentes em ambientes diferentes (local versus produção) sem implementar código específico do ambiente.

Neste início rápido, DefaultAzureCredential autentica-se no cofre de chaves usando as credenciais do usuário de desenvolvimento local conectado à CLI do Azure. Quando o aplicativo é implantado no Azure, o mesmo DefaultAzureCredential código pode descobrir e usar automaticamente uma identidade gerenciada atribuída a um Serviço de Aplicativo, Máquina Virtual ou outros serviços. Para obter mais informações, consulte Visão geral da identidade gerenciada.

Neste exemplo, o nome do cofre de chaves é expandido para o URI do cofre de chaves, no formato https://<your-key-vault-name>.vault.azure.net. Para obter mais informações sobre como autenticar no cofre de chaves, consulte o Guia do desenvolvedor.

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

Guarde um segredo

Agora que seu aplicativo está autenticado, você pode criar um certificado em seu cofre de chaves usando o certificateClient.beginCreateCertificate método. Isso requer um nome para o certificado e uma política de certificado -- atribuímos o valor "myCertificate" à certificateName variável neste exemplo e usamos uma política padrão.

A criação de certificados é uma operação de longa duração, para a qual você pode sondar seu progresso ou aguardar sua conclusão.

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

Você pode obter o certificado assim que a criação for concluída através da seguinte chamada:

KeyVaultCertificate createdCertificate = certificatePoller.getFinalResult();

Recuperar um certificado

Agora você pode recuperar o certificado criado anteriormente com o certificateClient.getCertificate método.

KeyVaultCertificate retrievedCertificate = certificateClient.getCertificate(certificateName);

Agora você pode acessar os detalhes do certificado recuperado com operações como retrievedCertificate.getName, retrievedCertificate.getProperties, etc. Bem como o seu conteúdo retrievedCertificate.getCer.

Excluir um certificado

Finalmente, vamos excluir o certificado do seu cofre de chaves com o certificateClient.beginDeleteCertificate método, que também é uma operação de longa execução.

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

Clean up resources (Limpar recursos)

Quando não for mais necessário, você poderá usar a CLI do Azure ou o Azure PowerShell para remover seu cofre de chaves e o grupo de recursos correspondente.

az group delete -g "myResourceGroup"

Remove-AzResourceGroup -Name "myResourceGroup"

Código de exemplo

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.");
    }
}

Próximos passos

Neste início rápido, você criou um cofre de chaves, criou um certificado, recuperou-o e o excluiu. Para saber mais sobre o Key Vault e como integrá-lo com seus aplicativos, continue nos artigos abaixo.

Leia uma visão geral do Azure Key Vault
Consulte o guia do desenvolvedor do Azure Key Vault
Como proteger o acesso a um cofre de chaves