254 lines
9.3 KiB
Plaintext
254 lines
9.3 KiB
Plaintext
[[quick-start]]
|
|
= Quick Start
|
|
|
|
This section explains how to get you started with Vault and Spring Cloud Vault.
|
|
|
|
== Prerequisites
|
|
|
|
To get started with Vault and this guide you need a *NIX-like operating systems that provides:
|
|
|
|
* `wget`, `openssl` and `unzip`
|
|
* at least Java 8 and a properly configured `JAVA_HOME` environment variable
|
|
|
|
NOTE: This guide explains Vault setup from a Spring Cloud Vault perspective for integration testing.
|
|
You can find a getting started guide directly on the Vault project site: https://learn.hashicorp.com/vault
|
|
|
|
*Install Vault*
|
|
|
|
[source,bash]
|
|
----
|
|
$ wget https://releases.hashicorp.com/vault/${vault_version}/vault_${vault_version}_${platform}.zip
|
|
$ unzip vault_${vault_version}_${platform}.zip
|
|
----
|
|
|
|
NOTE: These steps can be achieved by downloading and running https://github.com/spring-cloud/spring-cloud-vault/blob/master/src/test/bash/install_vault.sh[`install_vault.sh`].
|
|
|
|
== Create SSL certificates for Vault
|
|
|
|
Next, you're required to generate a set of certificates:
|
|
|
|
* Root CA
|
|
* Vault Certificate (decrypted key `work/ca/private/localhost.decrypted.key.pem` and certificate `work/ca/certs/localhost.cert.pem`)
|
|
|
|
Make sure to import the Root Certificate into a Java-compliant truststore.
|
|
|
|
The easiest way to achieve this is by using OpenSSL.
|
|
|
|
NOTE: https://github.com/spring-cloud/spring-cloud-vault/blob/master/src/test/bash/[`create_certificates.sh`] creates certificates in `work/ca` and a JKS truststore `work/keystore.jks`.
|
|
If you want to run Spring Cloud Vault using this quickstart guide you need to configure the truststore the `spring.cloud.vault.ssl.trust-store` property to `file:work/keystore.jks`.
|
|
|
|
[[quickstart.vault.start]]
|
|
== Start Vault server
|
|
|
|
Next create a config file along the lines of:
|
|
|
|
[source]
|
|
----
|
|
backend "inmem" {
|
|
}
|
|
|
|
listener "tcp" {
|
|
address = "0.0.0.0:8200"
|
|
tls_cert_file = "work/ca/certs/localhost.cert.pem"
|
|
tls_key_file = "work/ca/private/localhost.decrypted.key.pem"
|
|
}
|
|
|
|
disable_mlock = true
|
|
----
|
|
|
|
NOTE: You can find an example config file at https://github.com/spring-clod/spring-cloud-vault/blob/master/src/test/bash/vault.conf[`vault.conf`].
|
|
|
|
[source,bash]
|
|
----
|
|
$ vault server -config=vault.conf
|
|
----
|
|
|
|
Vault is started listening on `0.0.0.0:8200` using the `inmem` storage and `https`.
|
|
Vault is sealed and not initialized when starting up.
|
|
|
|
NOTE: If you want to run tests, leave Vault uninitialized.
|
|
The tests will initialize Vault and create a root token `00000000-0000-0000-0000-000000000000`.
|
|
|
|
If you want to use Vault for your application or give it a try then you need to initialize it first.
|
|
|
|
[source,bash]
|
|
----
|
|
$ export VAULT_ADDR="https://localhost:8200"
|
|
$ export VAULT_SKIP_VERIFY=true # Don't do this for production
|
|
$ vault operator init
|
|
----
|
|
|
|
You should see something like:
|
|
|
|
[source,bash]
|
|
----
|
|
Key 1: 7149c6a2e16b8833f6eb1e76df03e47f6113a3288b3093faf5033d44f0e70fe701
|
|
Key 2: 901c534c7988c18c20435a85213c683bdcf0efcd82e38e2893779f152978c18c02
|
|
Key 3: 03ff3948575b1165a20c20ee7c3e6edf04f4cdbe0e82dbff5be49c63f98bc03a03
|
|
Key 4: 216ae5cc3ddaf93ceb8e1d15bb9fc3176653f5b738f5f3d1ee00cd7dccbe926e04
|
|
Key 5: b2898fc8130929d569c1677ee69dc5f3be57d7c4b494a6062693ce0b1c4d93d805
|
|
Initial Root Token: 19aefa97-cccc-bbbb-aaaa-225940e63d76
|
|
|
|
Vault initialized with 5 keys and a key threshold of 3. Please
|
|
securely distribute the above keys. When the Vault is re-sealed,
|
|
restarted, or stopped, you must provide at least 3 of these keys
|
|
to unseal it again.
|
|
|
|
Vault does not store the master key. Without at least 3 keys,
|
|
your Vault will remain permanently sealed.
|
|
----
|
|
|
|
Vault will initialize and return a set of unsealing keys and the root token.
|
|
Pick 3 keys and unseal Vault.
|
|
Store the Vault token in the `VAULT_TOKEN`
|
|
environment variable.
|
|
|
|
[source,bash]
|
|
----
|
|
$ vault operator unseal (Key 1)
|
|
$ vault operator unseal (Key 2)
|
|
$ vault operator unseal (Key 3)
|
|
$ export VAULT_TOKEN=(Root token)
|
|
# Required to run Spring Cloud Vault tests after manual initialization
|
|
$ vault token create -id="00000000-0000-0000-0000-000000000000" -policy="root"
|
|
----
|
|
|
|
Spring Cloud Vault accesses different resources.
|
|
By default, the secret backend is enabled which accesses secret config settings via JSON endpoints.
|
|
|
|
The HTTP service has resources in the form:
|
|
|
|
----
|
|
/secret/{application}/{profile}
|
|
/secret/{application}
|
|
/secret/{defaultContext}/{profile}
|
|
/secret/{defaultContext}
|
|
----
|
|
|
|
where the "application" is injected as the `spring.application.name` in the
|
|
`SpringApplication` (i.e. what is normally "application" in a regular Spring Boot app), "profile" is an active profile (or comma-separated list of properties).
|
|
Properties retrieved from Vault will be used "as-is" without further prefixing of the property names.
|
|
|
|
[[client-side-usage]]
|
|
== Client Side Usage
|
|
|
|
To use these features in an application, just build it as a Spring Boot application that depends on `spring-cloud-vault-config` (e.g. see the test cases).
|
|
Example Maven configuration:
|
|
|
|
.pom.xml
|
|
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
<parent>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-starter-parent</artifactId>
|
|
<version>$\{springBootVersion}</version>
|
|
<relativePath /> <!-- lookup parent from repository -->
|
|
</parent>
|
|
|
|
<dependencies>
|
|
<dependency>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-starter-vault-config</artifactId>
|
|
<version>{project-version}</version>
|
|
</dependency>
|
|
<dependency>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-starter-test</artifactId>
|
|
<scope>test</scope>
|
|
</dependency>
|
|
</dependencies>
|
|
|
|
<build>
|
|
<plugins>
|
|
<plugin>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-maven-plugin</artifactId>
|
|
</plugin>
|
|
</plugins>
|
|
</build>
|
|
|
|
<!-- repositories also needed for snapshots and milestones -->
|
|
----
|
|
|
|
Then you can create a standard Spring Boot application, like this simple HTTP server:
|
|
|
|
[source,java]
|
|
----
|
|
@SpringBootApplication
|
|
@RestController
|
|
public class Application {
|
|
|
|
@RequestMapping("/")
|
|
public String home() {
|
|
return "Hello World!";
|
|
}
|
|
|
|
public static void main(String[] args) {
|
|
SpringApplication.run(Application.class, args);
|
|
}
|
|
}
|
|
----
|
|
|
|
When it runs it will pick up the external configuration from the default local Vault server on port `8200` if it is running.
|
|
To modify the startup behavior you can change the location of the Vault server using `application.properties`, for example
|
|
|
|
.application.yml
|
|
[source,yaml]
|
|
----
|
|
spring.cloud.vault:
|
|
host: localhost
|
|
port: 8200
|
|
scheme: https
|
|
uri: https://localhost:8200
|
|
connection-timeout: 5000
|
|
read-timeout: 15000
|
|
spring.config.import: vault://
|
|
----
|
|
|
|
* `host` sets the hostname of the Vault host.
|
|
The host name will be used for SSL certificate validation
|
|
* `port` sets the Vault port
|
|
* `scheme` setting the scheme to `http` will use plain HTTP.
|
|
Supported schemes are `http` and `https`.
|
|
* `uri` configure the Vault endpoint with an URI. Takes precedence over host/port/scheme configuration
|
|
* `connection-timeout` sets the connection timeout in milliseconds
|
|
* `read-timeout` sets the read timeout in milliseconds
|
|
* `spring.config.import` mounts Vault as `PropertySource` using all enabled secret backends (key-value enabled by default)
|
|
|
|
Enabling further integrations requires additional dependencies and configuration.
|
|
Depending on how you have set up Vault you might need additional configuration like
|
|
xref:advanced-topics.adoc#vault.config.ssl[SSL] and
|
|
xref:authentication.adoc#vault.config.authentication[authentication].
|
|
|
|
If the application imports the `spring-boot-starter-actuator` project, the status of the vault server will be available via the `/health` endpoint.
|
|
|
|
The vault health indicator can be enabled or disabled through the property `management.health.vault.enabled` (default to `true`).
|
|
|
|
NOTE: With Spring Cloud Vault 3.0 and Spring Boot 2.4, the bootstrap context initialization (`bootstrap.yml`, `bootstrap.properties`) of property sources was deprecated.
|
|
Instead, Spring Cloud Vault favors Spring Boot's Config Data API which allows importing configuration from Vault. With Spring Boot Config Data approach, you need to set the `spring.config.import` property in order to bind to Vault. You can read more about it in the xref:config-data.adoc#vault.configdata.locations[Config Data Locations section].
|
|
You can enable the bootstrap context either by setting the configuration property `spring.cloud.bootstrap.enabled=true` or by including the dependency `org.springframework.cloud:spring-cloud-starter-bootstrap`.
|
|
|
|
[[authentication]]
|
|
== Authentication
|
|
|
|
Vault requires an https://www.vaultproject.io/docs/concepts/auth.html[authentication mechanism] to https://www.vaultproject.io/docs/concepts/tokens.html[authorize client requests].
|
|
|
|
Spring Cloud Vault supports multiple xref:authentication.adoc[authentication mechanisms] to authenticate applications with Vault.
|
|
|
|
For a quickstart, use the root token printed by the xref:quickstart.adoc#quickstart.vault.start[Vault initialization].
|
|
|
|
.application.yml
|
|
[source,yaml]
|
|
----
|
|
spring.cloud.vault:
|
|
token: 19aefa97-cccc-bbbb-aaaa-225940e63d76
|
|
spring.config.import: vault://
|
|
----
|
|
|
|
WARNING: Consider carefully your security requirements.
|
|
Static token authentication is fine if you want quickly get started with Vault, but a static token is not protected any further.
|
|
Any disclosure to unintended parties allows Vault use with the associated token roles.
|
|
|
|
|
|
|