spring-projects/spring-vault

= Spring Vault image:https://github.com/spring-projects/spring-vault/actions/workflows/ci.yml/badge.svg?branch=main["Build Status", link="https://github.com/spring-projects/spring-vault/actions/workflows/ci.yml?query=branch%3Amain"] image:https://img.shields.io/badge/Revved%20up%20by-Develocity-06A0CE?logo=Gradle&labelColor=02303A["Revved up by Develocity", link="https://ge.spring.io/scans?search.rootProjectNames=Spring%20Vault"]

:docs: https://docs.spring.io/spring-vault/reference :github: https://github.com/spring-projects/spring-vault

Spring Vault provides client-side support for accessing, storing and revoking secrets. With https://www.vaultproject.io[HashiCorp Vault] you have a central place to manage external secret data for applications across all environments. Vault can manage static and dynamic secrets such as application data, username/password for remote applications/resources and provide credentials for external services such as MySQL, PostgreSQL, Apache Cassandra, Consul, AWS and more.

Our primary goals are:

• Provide a Java configuration model for the Vault client, including {docs}/vault/client-support.html#vault.client-ssl[SSL] and proxy support.
• Provide imperative and reactive VaultTemplate implementations to read, write and delete secrets and to work with {docs}/vault/vault-secret-engines.html[secrets engines] such as Key/Value, Transit and PKI.
• Support Vault {docs}/vault/authentication.html[authentication methods] including Token, AppRole, AWS, Azure, GCP, Kubernetes, JWT, TLS certificates and Cubbyhole.
• Expose secrets as Spring Environment properties through {docs}/vault/propertysource.html[@VaultPropertySource].
• Renew and rotate leased secrets transparently.

== Installation and Getting Started

The {docs}[reference documentation] includes a {docs}/introduction/getting-started.html[getting started] guide and describes the {docs}/introduction/dependencies.html[dependencies] to add to your build.

Add the Maven dependency:

[source,xml]

org.springframework.vault spring-vault-core ${version} ----

Releases and milestones are available from Maven Central. Snapshots of upcoming versions are available from the https://repo.spring.io/snapshot[Spring snapshot] repository.

Here is a quick teaser of a Spring Vault configuration and a component that reads and writes secrets through VaultTemplate:

[source,java]

@Configuration public class AppConfig extends AbstractVaultConfiguration {

@Override
public VaultEndpoint vaultEndpoint() {
	return VaultEndpoint.create("localhost", 8200);
}

@Override
public ClientAuthentication clientAuthentication() {
	return new TokenAuthentication("…");
}

}

[source,java]

@Component public class SecretsClient {

private final VaultOperations vaultOperations;

public SecretsClient(VaultOperations vaultOperations) {
	this.vaultOperations = vaultOperations;
}

public void useVault() {

	vaultOperations.write("secret/myapp", new Secrets("hello", "world"));

	VaultResponseSupport<Secrets> response = vaultOperations.read("secret/myapp", Secrets.class);
	System.out.println(response.getRequiredData().username());

	vaultOperations.delete("secret/myapp");
}

record Secrets(String username, String password) {
}

}

Spring Boot users can use https://github.com/spring-cloud/spring-cloud-vault-config[Spring Cloud Vault], which builds on Spring Vault to provide auto-configuration and Vault-backed configuration properties.

== Getting Help

Are you having trouble with Spring Vault? We want to help!

• Check the {docs}[reference documentation] and the https://docs.spring.io/spring-vault/docs/current/api/[Javadoc].
• Learn the Vault basics -- Spring Vault builds on https://www.vaultproject.io[HashiCorp Vault]; the https://developer.hashicorp.com/vault/docs[Vault documentation] explains secrets engines, authentication methods and leases.
• If you are upgrading, read the {github}/wiki[release notes] for upgrade instructions and "new and noteworthy" features.
• Ask a question -- we monitor https://stackoverflow.com[stackoverflow.com] for questions tagged with https://stackoverflow.com/tags/spring-vault[`spring-vault`].
• Report bugs with Spring Vault at {github}/issues[github.com/spring-projects/spring-vault/issues].

== Contributing

We welcome contributions of all kinds! Please read our link:CONTRIBUTING.adoc[contribution guidelines] before submitting a pull request.

== Reporting Issues

Spring Vault uses GitHub's integrated issue tracking system to record bugs and feature requests. If you want to raise an issue, please follow the recommendations below:

• Before you log a bug, please search the {github}/issues[issue tracker] to see if someone has already reported the problem.
• If the issue doesn't already exist, {github}/issues/new[create a new issue].
• Please provide as much information as possible with the issue report. We like to know the Spring Vault version, the Vault server version, operating system, and JVM version you're using.
• If you need to paste code or include a stack trace, use Markdown. +++```+++ escapes before and after your text.
• If possible, try to create a test case or project that replicates the problem and attach it to the issue.

== Building from Source

You don't need to build from source to use Spring Vault. If you want to try out the latest and greatest, Spring Vault can be built and installed into your local Maven cache using the https://maven.apache.org/wrapper/[Maven wrapper]. You also need JDK 17.

[source,shell]

$ ./mvnw install -DskipTests

This command builds all modules and installs them into your local Maven cache. It won't run any of the tests. The integration tests require a Vault server listening on localhost:8200. The scripts in src/test/bash download, configure and start one for you. If you want to build everything, start Vault and run the full build:

[source,shell]

$ ./src/test/bash/start.sh $ ./mvnw install

See {github}/wiki/Working-with-the-Code[Working with the Code] on the wiki for details on the Vault setup, building the documentation, and IDE configuration.

== License

Spring Vault is Open Source software released under the https://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 license].