Biblioteca de clientes do Certificado Key Vault do Azure para Java – versão 4.5.7

  • Artigo

O Azure Key Vault permite que você gerencie e controle seus certificados com segurança. A biblioteca de clientes do Certificado Key Vault do Azure dá suporte a certificados com suporte de chaves RSA e EC.

Vários certificados e várias versões do mesmo certificado podem ser mantidos no Key Vault. As chaves criptográficas no Azure Key Vault que dão suporte aos certificados são representadas como objetos JWK (Chave Web JSON). Essa biblioteca oferece operações para criar, recuperar, atualizar, excluir, limpar, fazer backup, restaurar e listar os certificados, bem como suas versões.

Código-fonte | Documentação de referência da API | Documentação do produto | Exemplos

Introdução

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga (disponibilidade geral) da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre a BOM, consulte o BOM README do SDK do AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

e inclua a dependência direta na seção dependências sem a marca de versão, conforme mostrado abaixo.

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

Incluir dependência direta

Se você quiser assumir a dependência de uma versão específica da biblioteca que não está presente na BOM, adicione a dependência direta ao seu projeto da seguinte maneira.

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

Pré-requisitos

Autenticar o cliente

Para interagir com o serviço de Key Vault do Azure, você precisará criar uma instância da CertificateClient classe , uma URL do cofre e um objeto de credencial. Os exemplos mostrados neste documento usam um objeto de credencial chamado DefaultAzureCredential, que é apropriado para a maioria dos cenários, incluindo ambientes locais de desenvolvimento e produção. Além disso, recomendamos usar uma [identidade gerenciada][managed_identity] para autenticação em ambientes de produção.

Você pode encontrar mais informações sobre diferentes maneiras de autenticação e seus tipos de credenciais correspondentes na documentação da Identidade do Azure.

Criar cliente de certificado

Depois de executar a configuração de autenticação mais adequada a você e substituir your-key-vault-url pela URL do cofre de chaves, você poderá criar o CertificateClient:

CertificateClient certificateClient = new CertificateClientBuilder()
    .vaultUrl("<your-key-vault-url>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

OBSERVAÇÃO: para usar um cliente assíncrono, use CertificateAsyncClient em vez de CertificateClient e chame buildAsyncClient().

Principais conceitos

Certificado

O Azure Key Vault dá suporte a certificados com tipos de conteúdo secreto (PKCS12&PEM). O certificado pode ser apoiado por chaves no Azure Key Vault de tipos (EC&RSA). Além da política de certificado, os seguintes atributos podem ser especificados:

  • enabled: especifica se o certificado está habilitado e utilizável.
  • criado: indica quando esta versão do certificado foi criada.
  • atualizado: indica quando esta versão do certificado foi atualizada.

Cliente de certificado

O cliente de certificado executa as interações com o serviço de Key Vault do Azure para obter, definir, atualizar, excluir e listar certificados e suas versões. O cliente também dá suporte a operações CRUD para emissores de certificado e contatos no cofre de chaves. Existem clientes assíncronos (CertificateAsyncClient) e síncronos (CertificateClient) no SDK, permitindo a seleção de um cliente com base no caso de uso de um aplicativo. Depois de inicializar um certificado, você poderá interagir com os tipos de recursos primários no Azure Key Vault.

Exemplos

API síncrona

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns do serviço certificado do Azure Key Vault, incluindo:

Criar um certificado

Crie um certificado a ser armazenado no Key Vault do Azure.

  • beginCreateCertificatecria um novo certificado no Key Vault do Azure. Se um certificado com o mesmo nome já existir, uma nova versão do certificado será criada.
SyncPoller<CertificateOperation, KeyVaultCertificateWithPolicy> certificatePoller =
    certificateClient.beginCreateCertificate("certificateName", CertificatePolicy.getDefault());
certificatePoller.waitUntil(LongRunningOperationStatus.SUCCESSFULLY_COMPLETED);
KeyVaultCertificate certificate = certificatePoller.getFinalResult();
System.out.printf("Certificate created with name \"%s\"%n", certificate.getName());

Recuperar um certificado

Recupere um certificado armazenado anteriormente chamando getCertificate ou getCertificateVersion.

KeyVaultCertificateWithPolicy certificate = certificateClient.getCertificate("<certificate-name>");
System.out.printf("Received certificate with name \"%s\", version %s and secret id %s%n",
    certificate.getProperties().getName(), certificate.getProperties().getVersion(), certificate.getSecretId());

Atualizar um certificado existente

Atualize um certificado existente chamando updateCertificateProperties.

// Get the certificate to update.
KeyVaultCertificate certificate = certificateClient.getCertificate("<certificate-name>");
// Update certificate enabled status.
certificate.getProperties().setEnabled(false);
KeyVaultCertificate updatedCertificate = certificateClient.updateCertificateProperties(certificate.getProperties());
System.out.printf("Updated certificate with name \"%s\" and enabled status \"%s\"%n",
    updatedCertificate.getProperties().getName(), updatedCertificate.getProperties().isEnabled());

Excluir um certificado

Exclua um certificado existente chamando beginDeleteCertificate.

SyncPoller<DeletedCertificate, Void> deleteCertificatePoller =
    certificateClient.beginDeleteCertificate("<certificate-name>");

// Deleted certificate is accessible as soon as polling beings.
PollResponse<DeletedCertificate> pollResponse = deleteCertificatePoller.poll();

// Deletion date only works for a SoftDelete-enabled Key Vault.
System.out.printf("Deleted certificate with name \"%s\" and recovery id %s", pollResponse.getValue().getName(),
    pollResponse.getValue().getRecoveryId());

// Certificate is being deleted on server.
deleteCertificatePoller.waitForCompletion();

Listar certificados

Liste os certificados no cofre de chaves chamando listPropertiesOfCertificates.

// List operations don't return the certificates with their full information. So, for each returned certificate we call
// getCertificate to get the certificate with all its properties excluding the policy.
for (CertificateProperties certificateProperties : certificateClient.listPropertiesOfCertificates()) {
    KeyVaultCertificate certificateWithAllProperties =
        certificateClient.getCertificateVersion(certificateProperties.getName(), certificateProperties.getVersion());
    System.out.printf("Received certificate with name \"%s\" and secret id %s",
        certificateWithAllProperties.getProperties().getName(), certificateWithAllProperties.getSecretId());
}

API assíncrona

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas de serviço de certificado do Azure Key Vault assíncronas mais comuns, incluindo:

Observação: você deve adicionar System.in.read() ou depois que Thread.sleep() a função chamar no main classe/thread para permitir que funções/operações assíncronas sejam executadas e concluídas antes que o main aplicativo/thread seja encerrado.

Criar um certificado de forma assíncrona

Crie um certificado a ser armazenado no Key Vault do Azure.

  • beginCreateCertificatecria um novo certificado no Key Vault do Azure. Se um certificado com o mesmo nome já existir, uma nova versão do certificado será criada.
// Creates a certificate using the default policy and polls on its progress.
certificateAsyncClient.beginCreateCertificate("<certificate-name>", CertificatePolicy.getDefault())
    .subscribe(pollResponse -> {
        System.out.println("---------------------------------------------------------------------------------");
        System.out.println(pollResponse.getStatus());
        System.out.println(pollResponse.getValue().getStatus());
        System.out.println(pollResponse.getValue().getStatusDetails());
    });

Recuperar um certificado de forma assíncrona

Recupere um certificado armazenado anteriormente chamando getCertificate ou getCertificateVersion.

certificateAsyncClient.getCertificate("<certificate-name>")
    .subscribe(certificateResponse ->
        System.out.printf("Certificate was returned with name \"%s\" and secretId %s%n",
            certificateResponse.getProperties().getName(), certificateResponse.getSecretId()));

Atualizar um certificado existente de forma assíncrona

Atualize um certificado existente chamando updateCertificateProperties.

certificateAsyncClient.getCertificate("<certificate-name>")
    .flatMap(certificate -> {
        // Update enabled status of the certificate.
        certificate.getProperties().setEnabled(false);
        return certificateAsyncClient.updateCertificateProperties(certificate.getProperties());
    }).subscribe(certificateResponse -> System.out.printf("Certificate's enabled status: %s%n",
        certificateResponse.getProperties().isEnabled()));

Excluir um certificado de forma assíncrona

Exclua um certificado existente chamando beginDeleteCertificate.

certificateAsyncClient.beginDeleteCertificate("<certificate-name>")
    .subscribe(pollResponse -> {
        System.out.printf("Deletion status: %s%n", pollResponse.getStatus());
        System.out.printf("Deleted certificate name: %s%n", pollResponse.getValue().getName());
        System.out.printf("Certificate deletion date: %s%n", pollResponse.getValue().getDeletedOn());
    });

Listar certificados de forma assíncrona

Liste os certificados no Key Vault do Azure chamando listPropertiesOfCertificates.

// The List Certificates operation returns certificates without their full properties, so for each certificate returned
// we call `getCertificate` to get all its attributes excluding the policy.
certificateAsyncClient.listPropertiesOfCertificates()
    .flatMap(certificateProperties -> certificateAsyncClient
        .getCertificateVersion(certificateProperties.getName(), certificateProperties.getVersion()))
    .subscribe(certificateResponse ->
        System.out.printf("Received certificate with name \"%s\" and key id %s", certificateResponse.getName(),
            certificateResponse.getKeyId()));

Solução de problemas

Consulte nosso guia de solução de problemas para obter detalhes sobre como diagnosticar vários cenários de falha.

Geral

Os clientes do Certificado Key Vault do Azure geram exceções. Por exemplo, se você tentar recuperar um certificado depois que ele for excluído, um 404 erro será retornado, indicando que o recurso não foi encontrado. No snippet a seguir, o erro é tratado normalmente capturando a exceção e exibindo informações adicionais sobre o erro.

try {
    certificateClient.getCertificate("<deleted-certificate-name>");
} catch (ResourceNotFoundException e) {
    System.out.println(e.getMessage());
}

Cliente HTTP padrão

Por padrão, todas as bibliotecas de cliente usam o cliente HTTP do Netty. Adicionar a dependência acima configurará automaticamente a biblioteca de cliente para usar o cliente HTTP do Netty. A configuração ou a alteração do cliente HTTP é detalhada no wiki de clientes HTTP.

Biblioteca SSL padrão

Todas as bibliotecas de cliente, por padrão, usam a biblioteca SSL com o uso do Tomcat nativo para habilitar o desempenho de nível nativo para operações SSL. A biblioteca SSL Chato é um JAR do Uber que contém bibliotecas nativas para Linux/macOS/Windows e fornece melhor desempenho em comparação com a implementação de SSL padrão no JDK. Para obter mais informações, incluindo como reduzir o tamanho da dependência, consulte a seção ajuste de desempenho da wiki.

Próximas etapas

Várias Key Vault exemplos do SDK do Java estão disponíveis para você no repositório GitHub do SDK. Esses exemplos fornecem código de exemplo para cenários adicionais comumente encontrados ao trabalhar com Key Vault.

Exemplos das próximas etapas

Os exemplos são explicados em detalhes aqui.

Documentação adicional

Para obter uma documentação mais abrangente sobre o Azure Key Vault, consulte a documentação de referência da API.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas Frequentes Sobre o Código de Conduta ou entre em contato pelo email opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões