There are a few support options available:

For information on the Spring Vault source code repository, nightly builds and snapshot artifacts please see the Spring Vault homepage. You can help make Spring Vault best serve the needs of the Spring community by interacting with developers through the Community on Stackoverflow. If you encounter a bug or want to suggest an improvement, please create a ticket on the Spring Vault issue tracker. To stay up to date with the latest news and announcements in the Spring ecosystem, subscribe to the Spring Community Portal. Lastly, you can follow the Spring blog or the project team on Twitter (SpringCentral).

The easiest way to find compatible versions of Spring Vault dependencies is by relying on the Spring Vault BOM we ship with the compatible versions defined. In a Maven project you would declare this dependency in the <dependencyManagement /> section of your pom.xml:

The current version is 2.2.1.RELEASE. The version name follows the following pattern: ${version}-${release} where release can be one of the following:

The current version of Spring Vault requires Spring Framework in version 5.2.3.RELEASE or better. The modules might also work with an older bugfix version of that minor version. However, using the most recent version within that generation is highly recommended.

Using Spring Vault does not require a Spring Context. However, instances of VaultTemplate and SessionManager registered inside a managed context will participate in lifecycle events provided by the Spring IoC container. This is useful to dispose active Vault sessions upon application shutdown. You also benefit from reusing the same VaultTemplate instance across your application.

Spring Vault comes with a supporting configuration class that provides bean definitions for use inside a Spring context. Application configuration classes typically extend from AbstractVaultConfiguration and are required to provide additional details that are environment specific.

Extending from AbstractVaultConfiguration requires to implement ` VaultEndpoint vaultEndpoint()` and ClientAuthentication clientAuthentication() methods.

Spring Vault requires a ClientAuthentication to login and access Vault. See Authentication Methods on details regarding authentication. Vault login should not occur on each authenticated Vault interaction but must be reused throughout a session. This aspect is handled by a SessionManager implementation. A SessionManager decides how often it obtains a token, about revocation and renewal. Spring Vault comes with two implementations:

Spring Vault includes EnvironmentVaultConfiguration configure the Vault client from Spring’s Environment and a set of predefined property keys. EnvironmentVaultConfiguration supports frequently applied configurations. Other configurations are supported by deriving from the most appropriate configuration class. Include EnvironmentVaultConfiguration with @Import(EnvironmentVaultConfiguration.class) to existing Java-based configuration classes and supply configuration properties through any of Spring’s PropertySources.

Property keys

Authentication-specific property keys

Token authentication

AppId authentication

AppRole authentication

AWS-EC2 authentication

Azure (MSI) authentication

TLS certificate authentication

No configuration options.

Cubbyhole authentication

Kubernetes authentication

One common design feature of all Spring template classes is that all functionality is routed into one of the templates execute callback methods. This helps ensure that exceptions and any resource management that maybe required are performed consistency. While this was of much greater need in the case of JDBC and JMS than with Vault, it still offers a single spot for access and logging to occur. As such, using the execute callback is the preferred way to access the Vault API to perform uncommon operations that we’ve not exposed as methods on VaultTemplate.

Here is a list of execute callback methods.

Here is an example that uses the ClientCallback to initialize Vault:

In plain terms reactive programming is about non-blocking applications that are asynchronous and event-driven and require a small number of threads to scale vertically (i.e. within the JVM) rather than horizontally (i.e. through clustering).

A key aspect of reactive applications is the concept of backpressure which is a mechanism to ensure producers don’t overwhelm consumers. For example in a pipeline of reactive components extending from the database to the HTTP response when the HTTP connection is too slow the data repository can also slow down or stop completely until network capacity frees up.

Spring Vault’s reactive client support is built on top of composable authentication steps and Spring’s functional WebClient via Reactor Netty or Jetty, which feature both a fully non-blocking, event-driven HTTP client.

It exposes VaultTokenSupplier as supplier of VaultToken to authenticate HTTP requests and ReactiveVaultOperations as the primary entry point. The core configuration of VaultEndpoint, ClientOptions and SSL are reused across the various client implementation.

The class ReactiveVaultTemplate, located in the package org.springframework.vault.core, is the central class of the Spring’s reactive Vault support providing a rich feature set to interact with Vault. The template offers convenience operations to read, write and delete data in Vault and provides a mapping between your domain objects and Vault data.

The mapping between Vault documents and domain classes is done by delegating to WebClient and its codecs.

The ReactiveVaultTemplate class implements the interface ReactiveVaultOperations. In as much as possible, the methods on ReactiveVaultOperations are named after methods available on the Vault API to make the API familiar to existing Vault developers who are used to the API and CLI. For example, you will find methods such as "write", "delete", and "read". The design goal was to make it as easy as possible to transition between the use of the Vault API and ReactiveVaultOperations. A major difference in between the two APIs is that ReactiveVaultOperations can be passed domain objects instead of JSON Key-Value pairs.

Functionality not explicitly exposed by the ReactiveVaultTemplate you can use one of several execute callback methods to access underlying APIs. The execute callbacks will give you a reference to a WebClient object. Please see the section Execution Callbacks for more information.

Now let’s look at a examples of how to work with Vault in the context of the Spring container.

Using Spring Vault does not require a Spring Context. However, instances of ReactiveVaultTemplate and VaultTokenSupplier registered inside a managed context will participate in lifecycle events provided by the Spring IoC container. This is useful to dispose active Vault sessions upon application shutdown. You also benefit from reusing the same ReactiveVaultTemplate instance across your application.

Spring Vault comes with a supporting configuration class that provides bean definitions for use inside a Spring context. Application configuration classes typically extend from AbstractVaultConfiguration and are required to provide additional details that are environment specific.

Extending from AbstractVaultConfiguration requires to implement ` VaultEndpoint vaultEndpoint()` and ClientAuthentication clientAuthentication() methods.

Spring Vault requires a token to authenticate Vault requests. See Authentication Methods on details regarding authentication. The reactive client requires a non-blocking token supplier whose contract is defined in VaultTokenSupplier. Tokens can be static or obtained through a declared authentication flow. Vault login should not occur on each authenticated Vault interaction but the session token should be kept across a session. This aspect is handled by a session manager implementing ReactiveSessionManager, such as ReactiveLifecycleAwareSessionManager.

One common design feature of all Spring template classes is that all functionality is routed into one of the templates execute callback methods. This helps ensure that exceptions and any resource management that maybe required are performed consistency. While this was of much greater need in the case of JDBC and JMS than with Vault, it still offers a single spot for access and logging to occur. As such, using the execute callback is the preferred way to access the Vault API to perform uncommon operations that we’ve not exposed as methods on ReactiveVaultTemplate.

Here is a list of execute callback methods.

Here is an example that uses the callback to initialize Vault:

Spring Vault provides a VaultPropertySource to be used with Vault to obtain properties. It uses the nested data element to expose properties stored and encrypted in Vault.

In the code above, VaultPropertySource has been added with highest precedence in the search. If it contains a ´foo` property, it will be detected and returned ahead of any foo property in any other PropertySource. MutablePropertySources exposes a number of methods that allow for precise manipulation of the set of property sources.

The @VaultPropertySource annotation provides a convenient and declarative mechanism for adding a PropertySource to Spring’s Environment to be used in conjunction with @Configuration classes.

@VaultPropertySource takes a Vault path such as secret/my-application and exposes the data stored at the node in a PropertySource. @VaultPropertySource supports lease renewal for secrets associated with a lease (i. e. credentials from the mysql backend) and credential rotation upon terminal lease expiration. Lease renewal is disabled by default.

Any ${…​} placeholders present in a @VaultPropertySource path are resolved against the set of property sources already registered against the environment, as the following example shows:

Assuming that my.placeholder is present in one of the property sources already registered (for example, system properties or environment variables), the placeholder is resolved to the corresponding value. If not, then fallback/value is used as a default. If no default is specified and a property cannot be resolved, an IllegalArgumentException is thrown.

In certain situations, it may not be possible or practical to tightly control property source ordering when using @VaultPropertySource annotations. For example, if the @Configuration classes above were registered via component-scanning, the ordering is difficult to predict. In such cases - and if overriding is important - it is recommended that the user fall back to using the programmatic PropertySource API. See ConfigurableEnvironment and MutablePropertySources for details.

To access domain entities stored in Vault you can leverage repository support that eases implementing those quite significantly.

We have a pretty simple domain object here. Note that it has a property named id annotated with org.springframework.data.annotation.Id and a @Secret annotation on its type. Those two are responsible for creating the actual key used to persist the object as JSON inside Vault.

The next step is to declare a repository interface that uses the domain object.

As our repository extends CrudRepository it provides basic CRUD and query methods. Vault repositories require Spring Data components. Make sure to include spring-data-commons and spring-data-keyvalue artifacts in your class path.

The easiest way to achive this, is by setting up dependency management and adding the artifacts to your pom.xml:

Then add the following to pom.xml dependencies section.

The thing we need in between to glue things together is the according Spring configuration.

Given the setup above we can go on and inject CredentialsRepository into our components.

Vault repositories store objects in Vault using JSON as interchange format. Object mapping between JSON and the entity is done by VaultConverter. The converter reads and writes SecretDocument that contains the body from a VaultResponse. VaultResponses are read from Vault and the body is deserialized by Jackson into a Map of String and Object. The default VaultConverter implementation reads the Map with nested values, List and Map objects and converts these to entities and vice versa.

Given the Credentials type from the previous sections the default mapping is as follows:

You can customize the mapping behavior by registering a Converter in VaultCustomConversions. Those converters can take care of converting from/to a type such as LocalDate as well as SecretDocument whereas the first one is suitable for converting simple properties and the last one complex types to their JSON representation. The second option offers full control over the resulting SecretDocument. Writing objects to Vault will delete the content and re-create the whole entry, so not mapped data will be lost.

Query methods allow automatic derivation of simple queries from the method name. Vault has no query engine but requires direct access of HTTP context paths. Vault query methods translate Vault’s API possibilities to queries. A query method execution lists children under a context path, applies filtering to the Id, optionally limits the Id stream with offset/limit and applies sorting after fetching the results.

Here’s an overview of the keywords supported for Vault.

Java’s builtin HttpURLConnection is available out-of-the-box without additional configuration. Using HttpURLConnection comes with a limitation regarding SSL configuration. Spring Vault won’t apply customized SSL configuration as it would require a deep reconfiguration of the JVM. This configuration would affect all components relying on the default SSL context. Configuring SSL settings using HttpURLConnection requires you providing these settings as System Properties. See Customizing JSSE for further details.

You can use external clients to access Vault’s API. Simply add one of the following dependencies to your project. You can omit the version number if using Spring Vault’s Dependency BOM

SSL can be configured using SslConfiguration by setting various properties. You can set either javax.net.ssl.trustStore to configure JVM-wide SSL settings or configure SslConfiguration to set SSL settings only for Spring Vault.

Please note that providing SslConfiguration can be only applied when either Apache Http Components or the OkHttp client is on your class-path.

Obtaining first-time access to a secured system is known as secure introduction. Any client requires ephemeral or permanent credentials to access Vault. Externalizing credentials is a good pattern to keep code maintainability high but comes at a risk of increased disclosure.

Disclosure of login credentials to any party allows login to Vault and access secrets that are permitted by the underlying role. Picking the appropriate client authentication and injecting credentials into the application is subject to risk evaluation.

Spring’s PropertySource abstraction is a natural fit to keep configuration outside the application code. You can use system properties, environment variables or property files to store login credentials. Each approach comes with its own properties. Keep in mind that the command line and environment properties can be introspected with appropriate OS access levels.

See SecurePropertyUsage.java for a sample on referencing properties in components and other property sources.

Tokens are the core method for authentication within Vault. Token authentication requires a static token to be provided.

Typically, Token authentication is used in scenarios in which the token is created and renewed externally (such as HashiCorp Vault service broker). Depending on the actual setup, you may or may not want token renewal and revocation. See LifecycleAwareSessionManager for details about TTL and token revocation.

See also:

Vault supports AppId authentication that consists of two hard to guess tokens. The AppId defaults to spring.application.name that is statically configured. The second token is the UserId which is a part determined by the application, usually related to the runtime environment. IP address, Mac address or a Docker container name are good examples. Spring Vault supports IP address, Mac address and static UserId’s (e.g. supplied via System properties). The IP and Mac address are represented as Hex-encoded SHA256 hash.

IP address-based UserId’s use the local host’s IP address.

The corresponding command to generate the IP address UserId from a command line is:

Mac address-based UserId’s obtain their network device from the localhost-bound device. The configuration also allows specifying a network-interface hint to pick the right device. The value of network-interface is optional and can be either an interface name or interface index (0-based).

The corresponding command to generate the Mac address UserId from a command line is:

AppRole allows machine authentication, like the deprecated (since Vault 0.6.1) AppId authentication. AppRole authentication consists of two hard to guess (secret) tokens: RoleId and SecretId.

Spring Vault supports AppRole authentication by providing either RoleId only or together with a provided SecretId and fetching RoleId/SecretId from Vault (push and pull modes with response unwrapping).

Spring Vault also support full pull mode: If RoleId and SecretId are not provided, Spring Vault will retrieve them using the role name and an initial token. The initial token may be associated with a TTL and usage limit.

See also: Vault Documentation: Using the AppRole auth backend

The aws-ec2 auth backend provides a secure introduction mechanism for AWS EC2 instances, allowing automated retrieval of a Vault token. Unlike most Vault authentication backends, this backend does not require first-deploying, or provisioning security-sensitive credentials (tokens, username/password, client certificates, etc.). Instead, it treats AWS as a Trusted Third Party and uses the cryptographically signed dynamic metadata information that uniquely represents each EC2 instance.

AWS-EC2 authentication enables nonce by default to follow the Trust On First Use (TOFU) principle. Any unintended party that gains access to the PKCS#7 identity metadata can authenticate against Vault.

During the first login, Spring Vault generates a nonce that is stored in the auth backend aside the instance Id. Re-authentication requires the same nonce to be sent. Any other party does not have the nonce and can raise an alert in Vault for further investigation.

The nonce is kept in memory and is lost during application restart.

AWS-EC2 authentication roles are optional and default to the AMI. You can configure the authentication role by setting it in AwsEc2AuthenticationOptions.

See also: Vault Documentation: Using the AWS-EC2 auth backend

The aws auth backend allows Vault login by using existing AWS IAM credentials.

AWS IAM authentication creates a signed HTTP request that is executed by Vault to get the identity of the signer using AWS STS GetCallerIdentity method. AWSv4 signatures require IAM credentials.

IAM credentials can be obtained from either the runtime environment or supplied externally. Runtime environments such as AWS-EC2, Lambda and ECS with assigned IAM principals do not require client-specific configuration of credentials but can obtain these from its metadata source.

AwsIamAuthentication requires the AWS Java SDK dependency (com.amazonaws:aws-java-sdk-core) as the authentication implementation uses AWS SDK types for credentials and request signing.

You can configure the authentication via AwsIamAuthenticationOptions.

See also:

The azure auth backend provides a secure introduction mechanism for Azure VM instances, allowing automated retrieval of a Vault token. Unlike most Vault authentication backends, this backend does not require first-deploying, or provisioning security-sensitive credentials (tokens, username/password, client certificates, etc.). Instead, it treats Azure as a Trusted Third Party and uses the managed service identity and instance metadata information that can be bound to a VM instance.

Azure authentication requires details about the VM environment (subscription Id, resource group name, VM name). These details can be either configured through AzureMsiAuthenticationOptionsBuilder. If left unconfigured, AzureMsiAuthentication queries Azure’s instance metadata service to obtain these details.

See also:

The gcp auth backend allows Vault login by using existing GCP (Google Cloud Platform) IAM and GCE credentials.

GCP GCE (Google Compute Engine) authentication creates a signature in the form of a JSON Web Token (JWT) for a service account. A JWT for a Compute Engine instance is obtained from the GCE metadata service using Instance identification. This API creates a JSON Web Token that can be used to confirm the instance identity.

Unlike most Vault authentication backends, this backend does not require first-deploying, or provisioning security-sensitive credentials (tokens, username/password, client certificates, etc.). Instead, it treats GCP as a Trusted Third Party and uses the cryptographically signed dynamic metadata information that uniquely represents each GCP service account.

You can configure the authentication via GcpComputeAuthenticationOptions.

See also:

The gcp auth backend allows Vault login by using existing GCP (Google Cloud Platform) IAM and GCE credentials.

GCP IAM authentication creates a signature in the form of a JSON Web Token (JWT) for a service account. A JWT for a service account is obtained by calling GCP IAM’s projects.serviceAccounts.signJwt API. The caller authenticates against GCP IAM and proves thereby its identity. This Vault backend treats GCP as a Trusted Third Party.

IAM credentials can be obtained from either the runtime environment or supplied externally as e.g. JSON. JSON is the preferred form as it carries the project id and service account identifier required for calling projects.serviceAccounts.signJwt.

GcpIamAuthenticationOptions requires the Google Cloud Java SDK dependency (com.google.apis:google-api-services-iam and com.google.auth:google-auth-library-oauth2-http) as the authentication implementation uses Google APIs for credentials and JWT signing.

You can configure the authentication via GcpIamAuthenticationOptions.

See also:

The pcf auth backend allows Vault login for PCF instances. It leverages PCF’s App and Container Identity Assurance.

PCF authentication uses the instance key and certificate to create a signature that is validated by Vault. If the signature matches, and potentially bound organization/space/application Id’s match, Vault issues an appropriately-scoped token.

Instance credentials are available from files at CF_INSTANCE_CERT and CF_INSTANCE_KEY variables.

PcfAuthenticationOptions requires the BouncyCastle library for creating RSA-PSS signatures.

You can configure the authentication via PcfAuthenticationOptions.

See also:

The cert auth backend allows authentication using SSL/TLS client certificates that are either signed by a CA or self-signed.

To enable cert authentication you need to:

See also: Vault Documentation: Using the Cert auth backend

Cubbyhole authentication uses Vault primitives to provide a secured authentication workflow. Cubbyhole authentication uses tokens as primary login method. An ephemeral token is used to obtain a second, login VaultToken from Vault’s Cubbyhole secret backend. The login token is usually longer-lived and used to interact with Vault. The login token can be retrieved either from a wrapped response or from the data section.

Creating a wrapped token

Using stored tokens

Remaining TTL/Renewability

Tokens retrieved from Cubbyhole associated with a non-zero TTL start their TTL at the time of token creation. That time is not necessarily identical with application startup. To compensate for the initial delay, Cubbyhole authentication performs a self lookup for tokens associated with a non-zero TTL to retrieve the remaining TTL. Cubbyhole authentication will not self-lookup wrapped tokens without a TTL because a zero TTL indicates there is no TTL associated.

Non-wrapped tokens do not provide details regarding renewability and TTL by just retrieving the token. A self-lookup will lookup renewability and the remaining TTL.

See also:

Vault supports since 0.8.3 kubernetes-based authentication using Kubernetes tokens.

Using Kubernetes authentication requires a Kubernetes Service Account Token, usually mounted at /var/run/secrets/kubernetes.io/serviceaccount/token. The file contains the token which is read and sent to Vault. Vault verifies its validity using Kubernetes' API during login.

Configuring Kubernetes authentication requires at least the role name to be provided:

You can configure the authentication via KubernetesAuthenticationOptions.

See also:

ClientAuthentication objects describe the authentication flow and perform the actual authentication steps. Pre-composed authentications are easy to use and to configure with a tight binding to synchronous execution.

The composition of authentication methods and reusing common steps, such as posting login payload to Vault or retrieving authentication input from an HTTP source is not intended with ClientAuthentication objects.

Authentication steps provide reusability of common authentication activity. Steps created via AuthenticationSteps describe an authentication flow in a functional style leaving the actual authentication execution to specific executors.

A single-step authentication flow can be created from a single input. Flows declaring multiple authentication steps start with a Supplier or HttpRequest that provide an authentication state object which can be used to map or post to Vault for login.

Authentication flows require an executor to perform the actual login. We provide two executors for different execution models:

Many ClientAuthentication's come with static factory methods to create AuthenticationSteps for their authentication-specific options:

Vault’s tokens can be associated with a time to live. Tokens obtained by an authentication method are intended to be used as long as the session is active and should not expire while the application is active.

Spring Vault provides with LifecycleAwareSessionManager a session manager that can renew the token until it reaches its terminal TTL to then perform another login to obtain the next token which is associated with the session.

Depending on the authentication method, a login can create two kinds of tokens:

Authentication methods such as TokenAuthentication just create a VaultToken which does not carry any renewability/TTL details. LifecycleAwareSessionManager will run a self-lookup on the token to retrieve renewability and TTL from Vault. VaultToken are renewed periodically if self-lookup is enabled. Note that VaultToken are never revoked, only LoginToken are revoked.

Authentication methods creating LoginToken directly (all login-based authentication methods) already provide all necessary details to setup token renewal. Tokens obtained from a login are revoked by LifecycleAwareSessionManager if the session manager is shut down.

Spring Vault integrates with Spring Security by providing implementations for BytesKeyGenerator and BytesEncryptor. Both implementations use Vault’s transit backend.

Vault encapsulates an entropy source that is decoupled from your JVM along with server-side key-management. This relieves the burden of proper encryption/decryption from application developers and pushes the burden onto the operators of Vault. Operators of Vault commonly include the security team at an organization, which means they can ensure that data is encrypted/decrypted properly. Additionally, since encrypt/decrypt operations must enter the audit log, any decryption event is recorded.

The backend also supports key rotation, which allows a new version of the named key to be generated. All data encrypted with the key will use the newest version of the key; previously encrypted data can be decrypted using old versions of the key. Administrators can control which previous versions of a key are available for decryption, to prevent an attacker gaining an old copy of ciphertext to be able to successfully decrypt it.

Vault is after all a networked service that incurs each operation with a latency. Components heavily using encryption or random bytes generation may experience a difference in throughput and performance.