Biblioteca de clientes do Azure Key Vault Secret para Java – versão 4.7.1

  • Artigo

O Azure Key Vault é um serviço de nuvem que fornece armazenamento seguro para segredos, como senhas e cadeias de conexão de banco de dados.

A biblioteca de clientes do Azure Key Vault Secrets permite que você armazene e controle com segurança o acesso a tokens, senhas, chaves de API e outros segredos. Essa biblioteca oferece operações para criar, recuperar, atualizar, excluir, limpar, fazer backup, restaurar e listar os segredos e suas versões.

Use a biblioteca de clientes do Azure Key Vault Secrets para criar e gerenciar segredos.

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-secrets</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-secrets</artifactId>
    <version>4.7.1</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 SecretClient 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, é recomendável usar uma identidade gerenciada 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 secreto

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

SecretClient secretClient = new SecretClientBuilder()
    .vaultUrl("<your-key-vault-url>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

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

Principais conceitos

Segredo

Um segredo é o recurso fundamental no Azure Key Vault. Da perspectiva do desenvolvedor, APIs Key Vault aceitam e retornam valores do segredo como cadeias de caracteres. Além dos dados de segredo, os seguintes atributos podem ser especificados:

  • enabled: especifica se os dados secretos podem ser recuperados.
  • notBefore: identifica a hora após a qual o segredo estará ativo.
  • expira: identifica o tempo de expiração em ou após o qual os dados secretos não devem ser recuperados.
  • criado: indica quando esta versão do segredo foi criada.
  • atualizado: indica quando esta versão do segredo foi atualizada.

Cliente secreto:

O cliente secreto executa as interações com o serviço de Key Vault do Azure para obter, configurar, atualizar, excluir e listar segredos e suas versões. Existem clientes assíncronos (SecretAsyncClient) e síncronos (SecretClient) no SDK, permitindo a seleção de um cliente com base no caso de uso de um aplicativo. Depois de inicializar um segredo, você poderá interagir com os tipos de recursos primários no 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 do Azure Key Vault Secret, incluindo:

Criar um segredo

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

  • setSecretcria um novo segredo no Key Vault do Azure. Se um segredo com o nome fornecido já existir, uma nova versão do segredo será criada.
KeyVaultSecret secret = secretClient.setSecret("<secret-name>", "<secret-value>");
System.out.printf("Secret created with name \"%s\" and value \"%s\"%n", secret.getName(), secret.getValue());

Recuperar um segredo

Recupere um segredo armazenado anteriormente chamando getSecret.

KeyVaultSecret secret = secretClient.getSecret("<secret-name>");
System.out.printf("Retrieved secret with name \"%s\" and value \"%s\"%n", secret.getName(), secret.getValue());

Atualizar um segredo existente

Atualize um segredo existente chamando updateSecretProperties.

// Get the secret to update.
KeyVaultSecret secret = secretClient.getSecret("<secret-name>");
// Update the expiry time of the secret.
secret.getProperties().setExpiresOn(OffsetDateTime.now().plusDays(30));
SecretProperties updatedSecretProperties = secretClient.updateSecretProperties(secret.getProperties());
System.out.printf("Secret's updated expiry time: %s%n", updatedSecretProperties.getExpiresOn());

Excluir um segredo

Exclua um segredo existente chamando beginDeleteSecret.

SyncPoller<DeletedSecret, Void> deletedSecretPoller = secretClient.beginDeleteSecret("<secret-name>");

// Deleted secret is accessible as soon as polling begins.
PollResponse<DeletedSecret> deletedSecretPollResponse = deletedSecretPoller.poll();

// Deletion date only works for a SoftDelete-enabled Key Vault.
System.out.printf("Deletion date: %s%n", deletedSecretPollResponse.getValue().getDeletedOn());

// Secret is being deleted on server.
deletedSecretPoller.waitForCompletion();

Listar segredos

Liste os segredos no Key Vault do Azure chamando listPropertiesOfSecrets.

// List operations don't return the secrets with value information. So, for each returned secret we call getSecret to
// get the secret with its value information.
for (SecretProperties secretProperties : secretClient.listPropertiesOfSecrets()) {
    KeyVaultSecret secretWithValue = secretClient.getSecret(secretProperties.getName(), secretProperties.getVersion());
    System.out.printf("Retrieved secret with name \"%s\" and value \"%s\"%n", secretWithValue.getName(),
        secretWithValue.getValue());
}

API assíncrona

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns do Serviço Secreto do Azure Key Vault assíncronas, 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 segredo de forma assíncrona

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

  • setSecretcria um novo segredo no Key Vault do Azure. Se um segredo com o nome fornecido já existir, uma nova versão do segredo será criada.
secretAsyncClient.setSecret("<secret-name>", "<secret-value>")
    .subscribe(secret -> System.out.printf("Created secret with name \"%s\" and value \"%s\"%n",
        secret.getName(), secret.getValue()));

Recuperar um segredo de forma assíncrona

Recupere um segredo armazenado anteriormente chamando getSecret.

secretAsyncClient.getSecret("<secret-name>")
    .subscribe(secret -> System.out.printf("Retrieved secret with name \"%s\" and value \"%s\"%n",
        secret.getName(), secret.getValue()));

Atualizar um segredo existente de forma assíncrona

Atualize um segredo existente chamando updateSecretProperties.

secretAsyncClient.getSecret("<secret-name>")
    .flatMap(secret -> {
        // Update the expiry time of the secret.
        secret.getProperties().setExpiresOn(OffsetDateTime.now().plusDays(50));
        return secretAsyncClient.updateSecretProperties(secret.getProperties());
    }).subscribe(updatedSecretProperties ->
        System.out.printf("Secret's updated expiry time: %s%n", updatedSecretProperties.getExpiresOn()));

Excluir um segredo de forma assíncrona

Exclua um segredo existente chamando beginDeleteSecret.

secretAsyncClient.beginDeleteSecret("<secret-name>")
    .subscribe(pollResponse -> {
        System.out.printf("Deletion status: %s%n", pollResponse.getStatus());
        System.out.printf("Deleted secret name: %s%n", pollResponse.getValue().getName());
        System.out.printf("Deleted secret value: %s%n", pollResponse.getValue().getValue());
    });

Listar segredos de forma assíncrona

Liste os segredos no Key Vault do Azure chamando listPropertiesOfSecrets.

// The List secrets operation returns secrets without their value, so for each secret returned we call `getSecret`
// to get its value as well.
secretAsyncClient.listPropertiesOfSecrets()
    .flatMap(secretProperties ->
        secretAsyncClient.getSecret(secretProperties.getName(), secretProperties.getVersion()))
    .subscribe(secretResponse ->
        System.out.printf("Retrieved secret with name \"%s\" and value \"%s\"%n", secretResponse.getName(),
            secretResponse.getValue()));

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 Azure Key Vault Secret geram exceções. Por exemplo, se você tentar recuperar um segredo 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 {
    secretClient.getSecret("<deleted-secret-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 o Azure 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