Java Vault Connector

Usage Examples

This section provides usage examples.
All code snippets are written in Java.
The examples assume using the latest published version of the connector.
Common use cases are shown tha do not necessarily show the full functionality.
For a complete guide refer to the API docs.

Connection »

The package features an HTTP connector by default.
To establish connection to your Vault cluster, the connector needs to be instantiated with the relevant parameters.
To do so, use the builder to configure your connector.

Simple instantiation

// Instantiate using builder pattern style factory
VaultConnector vault = HTTPVaultConnector.builder()
    .withHost("127.0.0.1")
    .withPort(8200)
    .withTLS()
    .build();

Provide custom CA certificate

For internal sites or to enforce a specific CA you might provide a custom CA certificate to trust.


// Initialization from environment variables
VaultConnector vault = HTTPVaultConnector.builder()
    .withHost("vault.example.com")
    .withPort(8200)
    .withTrustedCA(Paths.get("/path/to/CA.pem"))
    .build();

Configuration from environment variables

It is also possible to provide the configuration externally through environment variables.
This feature supports the default Vault environment variables: 


VaultConnector vault = VaultConnectorBuilder.http()
    .fromEnv()
    .build();

// Or with automatic authentication.
VaultConnector vault = VaultConnectorBuilder.http()
    .fromEnv()
    .buildAndAuth();
↑

Authentication »

The connector currently supports four authorization methods.

Token

Authenticate
VaultConnector vault = ...;
vault.authToken("01234567-89ab-cdef-0123-456789abcdef");
Create new Token
// Create new token using the builder (supports all current parameters).
Token token = Token.builder()
                   .withId("token-id")
                   .withDisplayName("token name")
                   .build();

// Write token to Vault (orphan creation and role binding possible).
AuthResponse createResponse = vault.createToken(token);

Username & Password

Authenticate
VaultConnector vault = ...;
vault.authUserPass("username", "p4ssw0rd");

AppRole

Authenticate
VaultConnector vault = ...;
vault.authAppRole("01234567-89ab-cdef-0123-456789abcdef",
                  "fedcba98-7654-3210-fedc-ba9876543210");
Manage roles and secrets
// Create new role using the builder. Supports all current role parameters.
AppRole role = AppRole.builder("role-name").build();

// Write the new role to Vault.
boolean created = vault.createAppRole(role);

// Lookup the role by name.
AppRoleResponse res = vault.lookupAppRole("role-name");

// Create a new secret with random ID.
AppRoleSecretResponse secret = vault.createAppRoleSecret("role-name");

// Destroy the secret.
boolean destroyed = vault.destroyAppRoleSecret("role-name",
                                               secret.getSecret().getId());

AppID

Authenticate
VaultConnector vault = ...;
vault.authAppId("01234567-89ab-cdef-0123-456789abcdef",
                "fedcba98-7654-3210-fedc-ba9876543210");
↑

Secrets »

The connector supports reading and writing of secrets to any exposed location inside Vault.
Several common features have been abstracted to reduce overhead code.

Basic read and write operations

VaultConnector vault = ...;
// Read arbitrary location.
SecretResponse secret = vault.read("secret/to/read");
// Get attribute from secret.
Object value = secret.get("value");
// Parse attribute (JSON) into custom class.
MyClass customValue = secret.get("custom_value", MyClass.class);

// Write data to Vault.
Map<String, Object> data = Map.of(
    "attr1", "value1",
    "attr2", 42
);
vault.write("secret/to/write", data);

// Delete a secret.
vault.delete("secret/to/delete");

Read and write to default secret/ mount

// Read from "secret/to/read".
SecretResponse secret = vault.read("secret/to/read");

// Write to "secret/to/write".
vault.write("secret/to/write", data);

// Delete a secret "secret/to/delete.
vault.delete("secret/to/delete");

Read and write data/metadata with KV v2 backend

// Read current data version, expands to "mount/data/to/read".
SecretResponse secret = vault.readSecretData("mount", "to/read");

// Read a specific version of this secret.
secret = vault.readSecretVersion("mount", "to/read", 5);

// Read metadata, expands to "mount/metadata/to/read".
MetadataResponse meta = vault.readSecretMetadata("mount", "to/read");

// Write a KV v2 secret, expands to "mount/data/to/write".
SecretVersionResponse newVersion = vault.writeSecretData("mount", data);

// Write to KV v2 with Check-And-Set for specific version.
newVersion = vault.writeSecretData("mount", data, 3);

// Update metadata to maximum Versions 10 and enforce CAS.
vault.updateSecretMetadata("mount", "to/write", 10, true);

// Delete specific secret version(s).
// undelete...() and destroy...() also available.
vault.deleteSecretVersions("mount", "to/delete", 1, 2, 4);

Read database credentials

// For arbitrary mount point.
CredentialsResponse cred = vault.readDbCredentials("role", "mount");
String username = cred.getUsername();
String password = cred.getPassword();

// Convenience for default MySQL, PostgreSQL and MongoDB backends.
cred = vault.readMySqlCredentials("role");
cred = vault.readPostgreSqlCredentials("role");
cred = vault.readMongoDbCredentials("role");
↑