diff --git a/spring-cloud-vault/1.0.0.M1/index.html b/spring-cloud-vault/1.0.0.M1/index.html new file mode 100644 index 00000000..2e63ef0b --- /dev/null +++ b/spring-cloud-vault/1.0.0.M1/index.html @@ -0,0 +1,1954 @@ + + + + + + + +Spring Cloud Vault + + + + + +
+
+
+
+

© 2016 The original authors.

+
+
+ + + + + +
+
Note
+		 +Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically. +
+
+
+

Spring Cloud Vault Config provides client-side support for externalized configuration in a distributed system. With HashiCorp's Vault you have a central place to manage external secret properties for applications across all environments. Vault can manage static and dynamic secrets such as username/password for remote applications/resources and provide credentials for external services such as MySQL, PostgreSQL, Apache Cassandra, MongoDB, Consul, AWS and more.

+
+
+
+
+

Quick Start

+
+
+

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 7 and a properly configured JAVA_HOME environment variable

    +
    • +
+
+
+

Install Vault

+
+
+
+
$ src/test/bash/install_vault.sh
+
+
+
+

Create SSL certificates for Vault

+
+
+
+
$ src/test/bash/create_certificates.sh
+
+
+
+ + + + + +
+
Note
+		 +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. +
+
+
+

Start Vault server

+
+
+
+
$ src/test/bash/local_run_vault.sh
+
+
+
+

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 +so you need to initialize it first.

+
+
+
+
$ export VAULT_ADDR="https://localhost:8200"
+$ export VAULT_SKIP_VERIFY=true # Don't do this for production
+$ vault init
+
+
+
+

You should see something like:

+
+
+
+
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.

+
+
+
+
$ vault unseal (Key 1)
+$ vault unseal (Key 2)
+$ vault unseal (Key 3)
+$ export VAULT_TOKEN=(Root token)
+
+
+
+

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

+
+
+

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:

+
+
+
Example 1. pom.xml
+
+
+
+
<parent>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-parent</artifactId>
+    <version>1.4.1.RELEASE</version>
+    <relativePath /> <!-- lookup parent from repository -->
+</parent>
+
+<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-starter-config</artifactId>
+        <version>x.y.z</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:

+
+
+
+
+
+
@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 bootstrap.properties (like application.properties but for +the bootstrap phase of an application context), e.g.

+
+
+
Example 2. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    host: localhost
+    port: 8200
+    scheme: https
+    connection-timeout: 5000
+    read-timeout: 15000
+    config:
+        order: -10
+
+
+
+
+
+
    +
  • +

    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.

    +
    • +
  • +

    connection-timeout sets the connection timeout in milliseconds

    +
    • +
  • +

    read-timeout sets the read timeout in milliseconds

    +
    • +
  • +

    config.order sets the order for the property source

    +
    • +
+
+
+

Enabling further integrations requires additional dependencies and +configuration. Depending on how you have set up Vault you might need +additional configuration like +SSL and +authentication. Checkout these +chapters in the +reference guide.

+
+
+

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 health.vault.enabled (default true)

+
+
+
+
+

Authentication methods

+
+
+

Different organizations have different requirements for security +and authentication. Vault reflects that need by shipping multiple authentication +methods. Spring Cloud Vault supports token and AppId authentication.

+
+
+

Token authentication

+
+

Tokens are the core method for authentication within Vault. +Token authentication requires a static token to be provided using the +Bootstrap Application Context.

+
+
+ + + + + +
+
Note
+		 +Token authentication is the default authentication method. +If a token is disclosed an unintended party gains access to Vault and +can access secrets for the intended client. +
+
+
+
Example 3. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: TOKEN
+    token: 00000000-0000-0000-0000-000000000000
+
+
+
+
+
+
    +
  • +

    authentication setting this value to TOKEN selects the Token +authentication method

    +
    • +
  • +

    token sets the static token to use

    +
    • +
+
+
+

See also: Vault Documentation: Tokens

+
+
+
+

AppId authentication

+
+

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 Cloud Vault Config 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.

+
+
+
Example 4. bootstrap.yml using SHA256 IP-Address UserId’s
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: IP_ADDRESS
+
+
+
+
+
+
    +
  • +

    authentication setting this value to APPID selects the AppId +authentication method

    +
    • +
  • +

    app-id-path sets the path of the AppId mount to use

    +
    • +
  • +

    user-id sets the UserId method. Possible values are IP_ADDRESS, +MAC_ADDRESS or a class name implementing a custom AppIdUserIdMechanism

    +
    • +
+
+
+

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

+
+
+
+
$ echo -n 192.168.99.1 | sha256sum
+
+
+
+ + + + + +
+
Note
+		 +Including the line break of echo leads to a different hash value +so make sure to include the -n flag. +
+
+
+

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).

+
+
+
Example 5. bootstrap.yml using SHA256 Mac-Address UserId’s
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: MAC_ADDRESS
+        network-interface: eth0
+
+
+
+
+
+
    +
  • +

    network-interface sets network interface to obtain the physical address

    +
    • +
+
+
+

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

+
+
+
+
$ echo -n 0AFEDE1234AC | sha256sum
+
+
+
+ + + + + +
+
Note
+		 +The Mac address is specified uppercase and without colons. +Including the line break of echo leads to a different hash value +so make sure to include the -n flag. +
+
+
+

Custom UserId

+
+

The UserId generation is an open mechanism. You can set +spring.cloud.vault.app-id.user-id to any string and the configured +value will be used as static UserId.

+
+
+

A more advanced approach lets you set spring.cloud.vault.app-id.user-id to a +classname. This class must be on your classpath and must implement +the org.springframework.cloud.vault.AppIdUserIdMechanism interface +and the createUserId method. Spring Cloud Vault will obtain the UserId +by calling createUserId each time it authenticates using AppId to +obtain a token.

+
+
+
Example 6. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: com.examlple.MyUserIdMechanism
+
+
+
+
+
+
Example 7. MyUserIdMechanism.java
+
+
+
+
public class MyUserIdMechanism implements AppIdUserIdMechanism {
+
+  @Override
+  public String createUserId() {
+    String userId = ...
+    return userId;
+  }
+}
+
+
+
+
+
+

See also: Vault Documentation: Using the App ID auth backend

+
+
+
+
+

AppRole authentication

+
+

AppRole is intended for 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 (push or pull mode).

+
+
+

RoleId and optionally SecretId must be provided by configuration, +Spring Vault will not look up these or create a custom SecretId.

+
+
+
Example 8. bootstrap.yml with AppRole authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
+
+
+
+
+
+
    +
  • +

    role-id sets the RoleId.

    +
    • +
+
+
+
Example 9. bootstrap.yml with all AppRole authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
+        secret-id: 1696536f-1976-73b1-b241-0b4213908d39
+        app-auth-path: approle
+
+
+
+
+
+
    +
  • +

    role-id sets the RoleId.

    +
    • +
  • +

    secret-id sets the SecretId. SecretId can be omitted if AppRole is configured without requiring SecretId (See bind_secret_id)

    +
    • +
  • +

    approle-path sets the path of the approle authentication mount to use

    +
    • +
+
+
+

See also: Vault Documentation: Using the AppRole auth backend

+
+
+
+

AWS-EC2 authentication

+
+

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.

+
+
+
Example 10. bootstrap.yml using AWS-EC2 Authentication
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+
+
+
+
+
+

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 Cloud 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.

+
+
+
Example 11. bootstrap.yml with disabled nonce
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        use-nonce: false
+
+
+
+
+
+

AWS-EC2 authentication roles are optional and default to the AMI. +You can configure the authentication role by setting the +spring.cloud.vault.aws-ec2.role property.

+
+
+
Example 12. bootstrap.yml with configured role
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server
+
+
+
+
+
+
Example 13. bootstrap.yml with all AWS EC2 authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server
+        aws-ec2-path: aws-ec2
+        identity-document: http://...
+        use-nonce: false
+
+
+
+
+
+
    +
  • +

    authentication setting this value to AWS_EC2 selects the AWS EC2 +authentication method

    +
    • +
  • +

    role sets the role name of the AWS EC2 role definition

    +
    • +
  • +

    aws-ec2-path sets the path of the AWS EC2 mount to use

    +
    • +
  • +

    identity-document sets URL of the PKCS#7 AWS EC2 identity document

    +
    • +
  • +

    use-nonce setting this value to false will disable nonce usage

    +
    • +
+
+
+

See also: Vault Documentation: Using the aws-ec2 auth backend

+
+
+
+

TLS certificate authentication

+
+

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:

+
+
+
    +
  1. +

    Use SSL, see Vault Client SSL configuration

    +
    2. +
  2. +

    Configure a Java Keystore that contains the client +certificate and the private key

    +
    3. +
  3. +

    Set the spring.cloud.vault.config.authentication to CERT

    +
    4. +
+
+
+
Example 14. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: CERT
+    ssl:
+        key-store: classpath:keystore.jks
+        key-store-password: changeit
+        cert-auth-path: cert
+
+
+
+
+
+

See also: Vault Documentation: Using the Cert auth backend

+
+
+
+

Cubbyhole authentication

+
+

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 will be retrieved from a wrapped +response stored at /cubbyhole/response.

+
+
+

Creating a wrapped token

+
+
+ + + + + +
+
Note
+		 +Response Wrapping for token creation requires Vault 0.6.0 or higher. +
+
+
+
Example 15. Crating and storing tokens
+
+
+
+
$ vault token-create -wrap-ttl="10m"
+Key                            Value
+---                            -----
+wrapping_token:                397ccb93-ff6c-b17b-9389-380b01ca2645
+wrapping_token_ttl:            0h10m0s
+wrapping_token_creation_time:  2016-09-18 20:29:48.652957077 +0200 CEST
+wrapped_accessor:              46b6aebb-187f-932a-26d7-4f3d86a68319
+
+
+
+
+
+
Example 16. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: CUBBYHOLE
+    token: 397ccb93-ff6c-b17b-9389-380b01ca2645
+
+
+
+
+
+

See also:

+
+
+ +
+
+
+
+
+

Secret Backends

+
+
+

Generic Backend

+
+

Spring Cloud Vault supports at the basic level the generic secret +backend. The generic secret backend allows storage of arbitrary +values as key-value store. A single context can store one or many +key-value tuples. Contexts can be organized hierarchically. +Spring Cloud Vault allows using the Application name set in +spring.application.name and a default context name (application) +in combination with active profiles.

+
+
+
+
/secret/{application}/{profile}
+/secret/{application}
+/secret/{default-context}/{profile}
+/secret/{default-context}
+
+
+
+

Spring Cloud Vault adds all active profiles to the list of possible context paths. +No active profiles will skip accessing contexts with a profile name. Properties +are exposed like they are stored (i.e. without additional prefixes).

+
+
+
+
+
+
spring.cloud.vault:
+    generic:
+        enabled: true
+        backend: secret
+        profile-separator: ','
+        default-context: application
+
+
+
+
+
+
    +
  • +

    enabled setting this value to false disables the secret backend +config usage

    +
    • +
  • +

    backend sets the path of the secret mount to use

    +
    • +
  • +

    default-context sets the context name used by all applications

    +
    • +
  • +

    profile-separator sets the value of the separator used to separate the +profile name in property sources with profiles

    +
    • +
+
+
+

See also: Vault Documentation: Using the generic secret backend

+
+
+
+

Consul

+
+

Spring Cloud Vault can obtain credentials for HashiCorp Consul. +The Consul integration requires the spring-cloud-vault-config-consul +dependency.

+
+
+
Example 17. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-consul</artifactId>
+        <version>x.y.z</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.consul.enabled=true (default false) and +providing the role name with spring.cloud.vault.consul.role=….

+
+
+

The obtained token is stored in spring.cloud.consul.token +so using Spring Cloud Consul can pick up the generated +credentials without further configuration. You can configure +the property name by setting spring.cloud.vault.consul.token-property.

+
+
+
+
+
+
spring.cloud.vault:
+    consul:
+        enabled: true
+        role: readonly
+        backend: consul
+        token-property: spring.cloud.consul.token
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the Consul backend config usage

    +
    • +
  • +

    role sets the role name of the Consul role definition

    +
    • +
  • +

    backend sets the path of the Consul mount to use

    +
    • +
  • +

    token-property sets the property name in which the Consul ACL token is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up Consul with Vault

+
+
+
+

RabbitMQ

+
+

Spring Cloud Vault can obtain credentials for RabbitMQ.

+
+
+

The RabbitMQ integration requires the spring-cloud-vault-config-rabbitmq +dependency.

+
+
+
Example 18. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-rabbitmq</artifactId>
+        <version>x.y.z</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.rabbitmq.enabled=true (default false) +and providing the role name with spring.cloud.vault.rabbitmq.role=….

+
+
+

Username and password are stored in spring.rabbitmq.username +and spring.rabbitmq.password so using Spring Boot will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.rabbitmq.username-property and +spring.cloud.vault.rabbitmq.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    rabbitmq:
+        enabled: true
+        role: readonly
+        backend: rabbitmq
+        username-property: spring.rabbitmq.username
+        password-property: spring.rabbitmq.password
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the RabbitMQ backend config usage

    +
    • +
  • +

    role sets the role name of the RabbitMQ role definition

    +
    • +
  • +

    backend sets the path of the RabbitMQ mount to use

    +
    • +
  • +

    username-property sets the property name in which the RabbitMQ username is stored

    +
    • +
  • +

    password-property sets the property name in which the RabbitMQ password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up RabbitMQ with Vault

+
+
+
+

AWS

+
+

Spring Cloud Vault can obtain credentials for AWS.

+
+
+

The AWS integration requires the spring-cloud-vault-config-aws +dependency.

+
+
+
Example 19. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-aws</artifactId>
+        <version>x.y.z</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.aws=true (default false) +and providing the role name with spring.cloud.vault.aws.role=….

+
+
+

The access key and secret key are stored in cloud.aws.credentials.accessKey +and cloud.aws.credentials.secretKey so using Spring Cloud AWS will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.aws.access-key-property and +spring.cloud.vault.aws.secret-key-property.

+
+
+
+
+
+
spring.cloud.vault:
+    aws:
+        enabled: true
+        role: readonly
+        backend: aws
+        access-key-property: cloud.aws.credentials.accessKey
+        secret-key-property: cloud.aws.credentials.secretKey
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the AWS backend config usage

    +
    • +
  • +

    role sets the role name of the AWS role definition

    +
    • +
  • +

    backend sets the path of the AWS mount to use

    +
    • +
  • +

    access-key-property sets the property name in which the AWS access key is stored

    +
    • +
  • +

    secret-key-property sets the property name in which the AWS secret key is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up AWS with Vault

+
+
+
+
+
+

Database backends

+
+
+

Vault supports several database secret backends to generate database +credentials dynamically based on configured roles. This means +services that need to access a database no longer need to configure +credentials: they can request them from Vault, and use Vault’s leasing +mechanism to more easily roll keys.

+
+
+

Spring Cloud Vault integrates with these backends:

+
+
+ +
+
+

Using a database secret backend requires to enable the +backend in the configuration and the spring-cloud-vault-config-databases +dependency.

+
+
+
Example 20. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-databases</artifactId>
+        <version>x.y.z</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+ + + + + +
+
Note
+		 +Enabling multiple JDBC-compliant databases will generate credentials +and store them by default in the same property keys hence property names for +JDBC secrets need to be configured separately. +
+
+
+

Apache Cassandra

+
+

Spring Cloud Vault can obtain credentials for Apache Cassandra. +The integration can be enabled by setting +spring.cloud.vault.cassandra.enabled=true (default false) and +providing the role name with spring.cloud.vault.cassandra.role=….

+
+
+

Username and password are stored in spring.data.cassandra.username +and spring.data.cassandra.password so using Spring Boot will pick +up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.cassandra.username-property and +spring.cloud.vault.cassandra.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    cassandra:
+        enabled: true
+        role: readonly
+        backend: cassandra
+        username-property: spring.data.cassandra.username
+        password-property: spring.data.cassandra.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the Cassandra backend config usage

    +
    • +
  • +

    role sets the role name of the Cassandra role definition

    +
    • +
  • +

    backend sets the path of the Cassandra mount to use

    +
    • +
  • +

    username-property sets the property name in which the Cassandra username is stored

    +
    • +
  • +

    password-property sets the property name in which the Cassandra password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up Apache Cassandra with Vault

+
+
+
+

MongoDB

+
+

Spring Cloud Vault can obtain credentials for MongoDB. +The integration can be enabled by setting +spring.cloud.vault.mongodb.enabled=true (default false) and +providing the role name with spring.cloud.vault.mongodb.role=….

+
+
+

Username and password are stored in spring.data.mongodb.username +and spring.data.mongodb.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mongodb.username-property and +spring.cloud.vault.mongodb.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    mongodb:
+        enabled: true
+        role: readonly
+        backend: mongodb
+        username-property: spring.data.mongodb.username
+        password-property: spring.data.mongodb.password
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the MongodB backend config usage

    +
    • +
  • +

    role sets the role name of the MongoDB role definition

    +
    • +
  • +

    backend sets the path of the MongoDB mount to use

    +
    • +
  • +

    username-property sets the property name in which the MongoDB username is stored

    +
    • +
  • +

    password-property sets the property name in which the MongoDB password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up MongoDB with Vault

+
+
+
+

MySQL

+
+

Spring Cloud Vault can obtain credentials for MySQL. +The integration can be enabled by setting +spring.cloud.vault.mysql.enabled=true (default false) and +providing the role name with spring.cloud.vault.mysql.role=….

+
+
+

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mysql.username-property and +spring.cloud.vault.mysql.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    mysql:
+        enabled: true
+        role: readonly
+        backend: mysql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the MySQL backend config usage

    +
    • +
  • +

    role sets the role name of the MySQL role definition

    +
    • +
  • +

    backend sets the path of the MySQL mount to use

    +
    • +
  • +

    username-property sets the property name in which the MySQL username is stored

    +
    • +
  • +

    password-property sets the property name in which the MySQL password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up MySQL with Vault

+
+
+
+

PostgreSQL

+
+

Spring Cloud Vault can obtain credentials for PostgreSQL. +The integration can be enabled by setting +spring.cloud.vault.postgresql.enabled=true (default false) and +providing the role name with spring.cloud.vault.postgresql.role=….

+
+
+

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.postgresql.username-property and +spring.cloud.vault.postgresql.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    postgresql:
+        enabled: true
+        role: readonly
+        backend: postgresql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the PostgreSQL backend config usage

    +
    • +
  • +

    role sets the role name of the PostgreSQL role definition

    +
    • +
  • +

    backend sets the path of the PostgreSQL mount to use

    +
    • +
  • +

    username-property sets the property name in which the PostgreSQL username is stored

    +
    • +
  • +

    password-property sets the property name in which the PostgreSQL password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up PostgreSQL with Vault

+
+
+
+
+
+

Vault Client Fail Fast

+
+
+

In some cases, it may be desirable to fail startup of a service if +it cannot connect to the Vault Server. If this is the desired +behavior, set the bootstrap configuration property +spring.cloud.vault.fail-fast=true and the client will halt with +an Exception.

+
+
+
+
+
+
spring.cloud.vault:
+    fail-fast: true
+
+
+
+
+
+
+
+

Vault Client SSL configuration

+
+
+

SSL can be configured declaratively by setting various properties. +You can set either javax.net.ssl.trustStore to configure +JVM-wide SSL settings or spring.cloud.vault.ssl.trust-store +to set SSL settings only for Spring Cloud Vault Config.

+
+
+
+
+
+
spring.cloud.vault:
+    ssl:
+        trust-store: classpath:keystore.jks
+        trust-store-password: changeit
+
+
+
+
+
+
    +
  • +

    trust-store sets the resource for the trust-store. SSL-secured Vault +communication will validate the Vault SSL certificate with the specified +trust-store.

    +
    • +
  • +

    trust-store-password sets the trust-store password

    +
    • +
+
+
+

Please note that configuring spring.cloud.vault.ssl.* can be only +applied when either Apache Http Components or the OkHttp client +is on your class-path.

+
+
+
+
+

Lease lifecycle management (renewal and revocation)

+
+
+

With every secret, Vault creates a lease: +metadata containing information such as a time duration, +renewability, and more.

+
+
+

Vault promises that the data will be valid for the given duration, +or Time To Live (TTL). Once the lease is expired, Vault can +revoke the data, and the consumer of the secret can no longer +be certain that it is valid.

+
+
+

Spring Cloud Vault maintains a lease lifecycle beyond +the creation of login tokens and secrets. That said, +login tokens and secrets associated with a lease +are scheduled for renewal just before the lease expires +until terminal expiry. +Application shutdown revokes obtained login tokens and renewable +leases.

+
+
+

Secret service and database backends (such as MongoDB or MySQL) +usually generate a renewable lease so generated credentials will +be disabled on application shutdown.

+
+
+ + + + + +
+
Note
+		 +Static tokens are not renewed or revoked. +
+
+
+

Lease renewal and revocation is enabled by default and can +be disabled by setting spring.cloud.vault.config.lifecycle.enabled +to false. This is not recommended as leases can expire and +Spring Cloud Vault cannot longer access Vault or services +using generated credentials and valid credentials remain active +after application shutdown.

+
+
+
+
+
+
spring.cloud.vault:
+    config.lifecycle.enabled: true
+
+
+
+
+
+

See also: Vault Documentation: Lease, Renew, and Revoke

+
+
+
+
+ + diff --git a/spring-cloud-vault/1.0.0.M2/index.html b/spring-cloud-vault/1.0.0.M2/index.html new file mode 100644 index 00000000..833474a3 --- /dev/null +++ b/spring-cloud-vault/1.0.0.M2/index.html @@ -0,0 +1,1992 @@ + + + + + + + +Spring Cloud Vault + + + + + +
+
+
+
+

© 2016 The original authors.

+
+
+ + + + + +
+
Note
+		 +Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically. +
+
+
+

Spring Cloud Vault Config provides client-side support for externalized configuration in a distributed system. With Hashicorp’s Vault you have a central place to manage external secret properties for applications across all environments. Vault can manage static and dynamic secrets such as username/password for remote applications/resources and provide credentials for external services such as MySQL, PostgreSQL, Apache Cassandra, MongoDB, Consul, AWS and more.

+
+
+
+
+

Quick Start

+
+
+

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 7 and a properly configured JAVA_HOME environment variable

    +
    • +
+
+
+

Install Vault

+
+
+
+
$ src/test/bash/install_vault.sh
+
+
+
+

Create SSL certificates for Vault

+
+
+
+
$ src/test/bash/create_certificates.sh
+
+
+
+ + + + + +
+
Note
+		 +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. +
+
+
+

Start Vault server

+
+
+
+
$ src/test/bash/local_run_vault.sh
+
+
+
+

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 +so you need to initialize it first.

+
+
+
+
$ export VAULT_ADDR="https://localhost:8200"
+$ export VAULT_SKIP_VERIFY=true # Don't do this for production
+$ vault init
+
+
+
+

You should see something like:

+
+
+
+
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.

+
+
+
+
$ vault unseal (Key 1)
+$ vault unseal (Key 2)
+$ vault unseal (Key 3)
+$ export VAULT_TOKEN=(Root token)
+
+
+
+

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

+
+
+

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:

+
+
+
Example 1. pom.xml
+
+
+
+
<parent>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-parent</artifactId>
+    <version>1.5.0.RELEASE</version>
+    <relativePath /> <!-- lookup parent from repository -->
+</parent>
+
+<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-starter-config</artifactId>
+        <version>{spring-cloud-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:

+
+
+
+
+
+
@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 bootstrap.properties (like application.properties but for +the bootstrap phase of an application context), e.g.

+
+
+
Example 2. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    host: localhost
+    port: 8200
+    scheme: https
+    connection-timeout: 5000
+    read-timeout: 15000
+    config:
+        order: -10
+
+
+
+
+
+
    +
  • +

    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.

    +
    • +
  • +

    connection-timeout sets the connection timeout in milliseconds

    +
    • +
  • +

    read-timeout sets the read timeout in milliseconds

    +
    • +
  • +

    config.order sets the order for the property source

    +
    • +
+
+
+

Enabling further integrations requires additional dependencies and +configuration. Depending on how you have set up Vault you might need +additional configuration like +SSL and +authentication. Checkout these +chapters in the +reference guide.

+
+
+

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 health.vault.enabled (default true)

+
+
+

Authentication

+
+

Vault requires an authentication mechanism to authorize client requests.

+
+
+

Spring Cloud Vault Config supports multiple authentication mechanisms to authenticate applications with Vault.

+
+
+

For a quickstart, use the root token printed by the Vault initialization.

+
+
+
Example 3. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    token: 19aefa97-cccc-bbbb-aaaa-225940e63d76
+
+
+
+
+
+ + + + + +
+
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. +
+
+
+
+
+
+

Authentication methods

+
+
+

Different organizations have different requirements for security +and authentication. Vault reflects that need by shipping multiple authentication +methods. Spring Cloud Vault supports token and AppId authentication.

+
+
+

Token authentication

+
+

Tokens are the core method for authentication within Vault. +Token authentication requires a static token to be provided using the +Bootstrap Application Context.

+
+
+ + + + + +
+
Note
+		 +Token authentication is the default authentication method. +If a token is disclosed an unintended party gains access to Vault and +can access secrets for the intended client. +
+
+
+
Example 4. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: TOKEN
+    token: 00000000-0000-0000-0000-000000000000
+
+
+
+
+
+
    +
  • +

    authentication setting this value to TOKEN selects the Token +authentication method

    +
    • +
  • +

    token sets the static token to use

    +
    • +
+
+
+

See also: Vault Documentation: Tokens

+
+
+
+

AppId authentication

+
+

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 Cloud Vault Config 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.

+
+
+
Example 5. bootstrap.yml using SHA256 IP-Address UserId’s
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: IP_ADDRESS
+
+
+
+
+
+
    +
  • +

    authentication setting this value to APPID selects the AppId +authentication method

    +
    • +
  • +

    app-id-path sets the path of the AppId mount to use

    +
    • +
  • +

    user-id sets the UserId method. Possible values are IP_ADDRESS, +MAC_ADDRESS or a class name implementing a custom AppIdUserIdMechanism

    +
    • +
+
+
+

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

+
+
+
+
$ echo -n 192.168.99.1 | sha256sum
+
+
+
+ + + + + +
+
Note
+		 +Including the line break of echo leads to a different hash value +so make sure to include the -n flag. +
+
+
+

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).

+
+
+
Example 6. bootstrap.yml using SHA256 Mac-Address UserId’s
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: MAC_ADDRESS
+        network-interface: eth0
+
+
+
+
+
+
    +
  • +

    network-interface sets network interface to obtain the physical address

    +
    • +
+
+
+

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

+
+
+
+
$ echo -n 0AFEDE1234AC | sha256sum
+
+
+
+ + + + + +
+
Note
+		 +The Mac address is specified uppercase and without colons. +Including the line break of echo leads to a different hash value +so make sure to include the -n flag. +
+
+
+

Custom UserId

+
+

The UserId generation is an open mechanism. You can set +spring.cloud.vault.app-id.user-id to any string and the configured +value will be used as static UserId.

+
+
+

A more advanced approach lets you set spring.cloud.vault.app-id.user-id to a +classname. This class must be on your classpath and must implement +the org.springframework.cloud.vault.AppIdUserIdMechanism interface +and the createUserId method. Spring Cloud Vault will obtain the UserId +by calling createUserId each time it authenticates using AppId to +obtain a token.

+
+
+
Example 7. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: com.examlple.MyUserIdMechanism
+
+
+
+
+
+
Example 8. MyUserIdMechanism.java
+
+
+
+
public class MyUserIdMechanism implements AppIdUserIdMechanism {
+
+  @Override
+  public String createUserId() {
+    String userId = ...
+    return userId;
+  }
+}
+
+
+
+
+
+

See also: Vault Documentation: Using the App ID auth backend

+
+
+
+
+

AppRole authentication

+
+

AppRole is intended for 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 (push or pull mode).

+
+
+

RoleId and optionally SecretId must be provided by configuration, +Spring Vault will not look up these or create a custom SecretId.

+
+
+
Example 9. bootstrap.yml with AppRole authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
+
+
+
+
+
+
    +
  • +

    role-id sets the RoleId.

    +
    • +
+
+
+
Example 10. bootstrap.yml with all AppRole authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
+        secret-id: 1696536f-1976-73b1-b241-0b4213908d39
+        app-auth-path: approle
+
+
+
+
+
+
    +
  • +

    role-id sets the RoleId.

    +
    • +
  • +

    secret-id sets the SecretId. SecretId can be omitted if AppRole is configured without requiring SecretId (See bind_secret_id)

    +
    • +
  • +

    approle-path sets the path of the approle authentication mount to use

    +
    • +
+
+
+

See also: Vault Documentation: Using the AppRole auth backend

+
+
+
+

AWS-EC2 authentication

+
+

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.

+
+
+
Example 11. bootstrap.yml using AWS-EC2 Authentication
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+
+
+
+
+
+

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 Cloud 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.

+
+
+
Example 12. bootstrap.yml with disabled nonce
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        use-nonce: false
+
+
+
+
+
+

AWS-EC2 authentication roles are optional and default to the AMI. +You can configure the authentication role by setting the +spring.cloud.vault.aws-ec2.role property.

+
+
+
Example 13. bootstrap.yml with configured role
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server
+
+
+
+
+
+
Example 14. bootstrap.yml with all AWS EC2 authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server
+        aws-ec2-path: aws-ec2
+        identity-document: http://...
+        use-nonce: false
+
+
+
+
+
+
    +
  • +

    authentication setting this value to AWS_EC2 selects the AWS EC2 +authentication method

    +
    • +
  • +

    role sets the role name of the AWS EC2 role definition

    +
    • +
  • +

    aws-ec2-path sets the path of the AWS EC2 mount to use

    +
    • +
  • +

    identity-document sets URL of the PKCS#7 AWS EC2 identity document

    +
    • +
  • +

    use-nonce setting this value to false will disable nonce usage

    +
    • +
+
+
+

See also: Vault Documentation: Using the aws-ec2 auth backend

+
+
+
+

TLS certificate authentication

+
+

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:

+
+
+
    +
  1. +

    Use SSL, see Vault Client SSL configuration

    +
    2. +
  2. +

    Configure a Java Keystore that contains the client +certificate and the private key

    +
    3. +
  3. +

    Set the spring.cloud.vault.authentication to CERT

    +
    4. +
+
+
+
Example 15. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: CERT
+    ssl:
+        key-store: classpath:keystore.jks
+        key-store-password: changeit
+        cert-auth-path: cert
+
+
+
+
+
+

See also: Vault Documentation: Using the Cert auth backend

+
+
+
+

Cubbyhole authentication

+
+

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 will be retrieved from a wrapped +response stored at /cubbyhole/response.

+
+
+

Creating a wrapped token

+
+
+ + + + + +
+
Note
+		 +Response Wrapping for token creation requires Vault 0.6.0 or higher. +
+
+
+
Example 16. Crating and storing tokens
+
+
+
+
$ vault token-create -wrap-ttl="10m"
+Key                            Value
+---                            -----
+wrapping_token:                397ccb93-ff6c-b17b-9389-380b01ca2645
+wrapping_token_ttl:            0h10m0s
+wrapping_token_creation_time:  2016-09-18 20:29:48.652957077 +0200 CEST
+wrapped_accessor:              46b6aebb-187f-932a-26d7-4f3d86a68319
+
+
+
+
+
+
Example 17. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: CUBBYHOLE
+    token: 397ccb93-ff6c-b17b-9389-380b01ca2645
+
+
+
+
+
+

See also:

+
+
+ +
+
+
+
+
+

Secret Backends

+
+
+

Generic Backend

+
+

Spring Cloud Vault supports at the basic level the generic secret +backend. The generic secret backend allows storage of arbitrary +values as key-value store. A single context can store one or many +key-value tuples. Contexts can be organized hierarchically. +Spring Cloud Vault allows using the Application name set in +spring.application.name and a default context name (application) +in combination with active profiles.

+
+
+
+
/secret/{application}/{profile}
+/secret/{application}
+/secret/{default-context}/{profile}
+/secret/{default-context}
+
+
+
+

Spring Cloud Vault adds all active profiles to the list of possible context paths. +No active profiles will skip accessing contexts with a profile name. Properties +are exposed like they are stored (i.e. without additional prefixes).

+
+
+
+
+
+
spring.cloud.vault:
+    generic:
+        enabled: true
+        backend: secret
+        profile-separator: ','
+        default-context: application
+
+
+
+
+
+
    +
  • +

    enabled setting this value to false disables the secret backend +config usage

    +
    • +
  • +

    backend sets the path of the secret mount to use

    +
    • +
  • +

    default-context sets the context name used by all applications

    +
    • +
  • +

    profile-separator sets the value of the separator used to separate the +profile name in property sources with profiles

    +
    • +
+
+
+

See also: Vault Documentation: Using the generic secret backend

+
+
+
+

Consul

+
+

Spring Cloud Vault can obtain credentials for HashiCorp Consul. +The Consul integration requires the spring-cloud-vault-config-consul +dependency.

+
+
+
Example 18. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-consul</artifactId>
+        <version>x.y.z</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.consul.enabled=true (default false) and +providing the role name with spring.cloud.vault.consul.role=….

+
+
+

The obtained token is stored in spring.cloud.consul.token +so using Spring Cloud Consul can pick up the generated +credentials without further configuration. You can configure +the property name by setting spring.cloud.vault.consul.token-property.

+
+
+
+
+
+
spring.cloud.vault:
+    consul:
+        enabled: true
+        role: readonly
+        backend: consul
+        token-property: spring.cloud.consul.token
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the Consul backend config usage

    +
    • +
  • +

    role sets the role name of the Consul role definition

    +
    • +
  • +

    backend sets the path of the Consul mount to use

    +
    • +
  • +

    token-property sets the property name in which the Consul ACL token is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up Consul with Vault

+
+
+
+

RabbitMQ

+
+

Spring Cloud Vault can obtain credentials for RabbitMQ.

+
+
+

The RabbitMQ integration requires the spring-cloud-vault-config-rabbitmq +dependency.

+
+
+
Example 19. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-rabbitmq</artifactId>
+        <version>x.y.z</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.rabbitmq.enabled=true (default false) +and providing the role name with spring.cloud.vault.rabbitmq.role=….

+
+
+

Username and password are stored in spring.rabbitmq.username +and spring.rabbitmq.password so using Spring Boot will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.rabbitmq.username-property and +spring.cloud.vault.rabbitmq.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    rabbitmq:
+        enabled: true
+        role: readonly
+        backend: rabbitmq
+        username-property: spring.rabbitmq.username
+        password-property: spring.rabbitmq.password
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the RabbitMQ backend config usage

    +
    • +
  • +

    role sets the role name of the RabbitMQ role definition

    +
    • +
  • +

    backend sets the path of the RabbitMQ mount to use

    +
    • +
  • +

    username-property sets the property name in which the RabbitMQ username is stored

    +
    • +
  • +

    password-property sets the property name in which the RabbitMQ password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up RabbitMQ with Vault

+
+
+
+

AWS

+
+

Spring Cloud Vault can obtain credentials for AWS.

+
+
+

The AWS integration requires the spring-cloud-vault-config-aws +dependency.

+
+
+
Example 20. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-aws</artifactId>
+        <version>x.y.z</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.aws=true (default false) +and providing the role name with spring.cloud.vault.aws.role=….

+
+
+

The access key and secret key are stored in cloud.aws.credentials.accessKey +and cloud.aws.credentials.secretKey so using Spring Cloud AWS will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.aws.access-key-property and +spring.cloud.vault.aws.secret-key-property.

+
+
+
+
+
+
spring.cloud.vault:
+    aws:
+        enabled: true
+        role: readonly
+        backend: aws
+        access-key-property: cloud.aws.credentials.accessKey
+        secret-key-property: cloud.aws.credentials.secretKey
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the AWS backend config usage

    +
    • +
  • +

    role sets the role name of the AWS role definition

    +
    • +
  • +

    backend sets the path of the AWS mount to use

    +
    • +
  • +

    access-key-property sets the property name in which the AWS access key is stored

    +
    • +
  • +

    secret-key-property sets the property name in which the AWS secret key is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up AWS with Vault

+
+
+
+
+
+

Database backends

+
+
+

Vault supports several database secret backends to generate database +credentials dynamically based on configured roles. This means +services that need to access a database no longer need to configure +credentials: they can request them from Vault, and use Vault’s leasing +mechanism to more easily roll keys.

+
+
+

Spring Cloud Vault integrates with these backends:

+
+
+ +
+
+

Using a database secret backend requires to enable the +backend in the configuration and the spring-cloud-vault-config-databases +dependency.

+
+
+
Example 21. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-databases</artifactId>
+        <version>x.y.z</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+ + + + + +
+
Note
+		 +Enabling multiple JDBC-compliant databases will generate credentials +and store them by default in the same property keys hence property names for +JDBC secrets need to be configured separately. +
+
+
+

Apache Cassandra

+
+

Spring Cloud Vault can obtain credentials for Apache Cassandra. +The integration can be enabled by setting +spring.cloud.vault.cassandra.enabled=true (default false) and +providing the role name with spring.cloud.vault.cassandra.role=….

+
+
+

Username and password are stored in spring.data.cassandra.username +and spring.data.cassandra.password so using Spring Boot will pick +up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.cassandra.username-property and +spring.cloud.vault.cassandra.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    cassandra:
+        enabled: true
+        role: readonly
+        backend: cassandra
+        username-property: spring.data.cassandra.username
+        password-property: spring.data.cassandra.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the Cassandra backend config usage

    +
    • +
  • +

    role sets the role name of the Cassandra role definition

    +
    • +
  • +

    backend sets the path of the Cassandra mount to use

    +
    • +
  • +

    username-property sets the property name in which the Cassandra username is stored

    +
    • +
  • +

    password-property sets the property name in which the Cassandra password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up Apache Cassandra with Vault

+
+
+
+

MongoDB

+
+

Spring Cloud Vault can obtain credentials for MongoDB. +The integration can be enabled by setting +spring.cloud.vault.mongodb.enabled=true (default false) and +providing the role name with spring.cloud.vault.mongodb.role=….

+
+
+

Username and password are stored in spring.data.mongodb.username +and spring.data.mongodb.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mongodb.username-property and +spring.cloud.vault.mongodb.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    mongodb:
+        enabled: true
+        role: readonly
+        backend: mongodb
+        username-property: spring.data.mongodb.username
+        password-property: spring.data.mongodb.password
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the MongodB backend config usage

    +
    • +
  • +

    role sets the role name of the MongoDB role definition

    +
    • +
  • +

    backend sets the path of the MongoDB mount to use

    +
    • +
  • +

    username-property sets the property name in which the MongoDB username is stored

    +
    • +
  • +

    password-property sets the property name in which the MongoDB password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up MongoDB with Vault

+
+
+
+

MySQL

+
+

Spring Cloud Vault can obtain credentials for MySQL. +The integration can be enabled by setting +spring.cloud.vault.mysql.enabled=true (default false) and +providing the role name with spring.cloud.vault.mysql.role=….

+
+
+

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mysql.username-property and +spring.cloud.vault.mysql.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    mysql:
+        enabled: true
+        role: readonly
+        backend: mysql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the MySQL backend config usage

    +
    • +
  • +

    role sets the role name of the MySQL role definition

    +
    • +
  • +

    backend sets the path of the MySQL mount to use

    +
    • +
  • +

    username-property sets the property name in which the MySQL username is stored

    +
    • +
  • +

    password-property sets the property name in which the MySQL password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up MySQL with Vault

+
+
+
+

PostgreSQL

+
+

Spring Cloud Vault can obtain credentials for PostgreSQL. +The integration can be enabled by setting +spring.cloud.vault.postgresql.enabled=true (default false) and +providing the role name with spring.cloud.vault.postgresql.role=….

+
+
+

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.postgresql.username-property and +spring.cloud.vault.postgresql.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    postgresql:
+        enabled: true
+        role: readonly
+        backend: postgresql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the PostgreSQL backend config usage

    +
    • +
  • +

    role sets the role name of the PostgreSQL role definition

    +
    • +
  • +

    backend sets the path of the PostgreSQL mount to use

    +
    • +
  • +

    username-property sets the property name in which the PostgreSQL username is stored

    +
    • +
  • +

    password-property sets the property name in which the PostgreSQL password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up PostgreSQL with Vault

+
+
+
+
+
+

Vault Client Fail Fast

+
+
+

In some cases, it may be desirable to fail startup of a service if +it cannot connect to the Vault Server. If this is the desired +behavior, set the bootstrap configuration property +spring.cloud.vault.fail-fast=true and the client will halt with +an Exception.

+
+
+
+
+
+
spring.cloud.vault:
+    fail-fast: true
+
+
+
+
+
+
+
+

Vault Client SSL configuration

+
+
+

SSL can be configured declaratively by setting various properties. +You can set either javax.net.ssl.trustStore to configure +JVM-wide SSL settings or spring.cloud.vault.ssl.trust-store +to set SSL settings only for Spring Cloud Vault Config.

+
+
+
+
+
+
spring.cloud.vault:
+    ssl:
+        trust-store: classpath:keystore.jks
+        trust-store-password: changeit
+
+
+
+
+
+
    +
  • +

    trust-store sets the resource for the trust-store. SSL-secured Vault +communication will validate the Vault SSL certificate with the specified +trust-store.

    +
    • +
  • +

    trust-store-password sets the trust-store password

    +
    • +
+
+
+

Please note that configuring spring.cloud.vault.ssl.* can be only +applied when either Apache Http Components or the OkHttp client +is on your class-path.

+
+
+
+
+

Lease lifecycle management (renewal and revocation)

+
+
+

With every secret, Vault creates a lease: +metadata containing information such as a time duration, +renewability, and more.

+
+
+

Vault promises that the data will be valid for the given duration, +or Time To Live (TTL). Once the lease is expired, Vault can +revoke the data, and the consumer of the secret can no longer +be certain that it is valid.

+
+
+

Spring Cloud Vault maintains a lease lifecycle beyond +the creation of login tokens and secrets. That said, +login tokens and secrets associated with a lease +are scheduled for renewal just before the lease expires +until terminal expiry. +Application shutdown revokes obtained login tokens and renewable +leases.

+
+
+

Secret service and database backends (such as MongoDB or MySQL) +usually generate a renewable lease so generated credentials will +be disabled on application shutdown.

+
+
+ + + + + +
+
Note
+		 +Static tokens are not renewed or revoked. +
+
+
+

Lease renewal and revocation is enabled by default and can +be disabled by setting spring.cloud.vault.config.lifecycle.enabled +to false. This is not recommended as leases can expire and +Spring Cloud Vault cannot longer access Vault or services +using generated credentials and valid credentials remain active +after application shutdown.

+
+
+
+
+
+
spring.cloud.vault:
+    config.lifecycle.enabled: true
+
+
+
+
+
+

See also: Vault Documentation: Lease, Renew, and Revoke

+
+
+
+
+ + diff --git a/spring-cloud-vault/1.0.0.RC1/index.html b/spring-cloud-vault/1.0.0.RC1/index.html new file mode 100644 index 00000000..5f936c50 --- /dev/null +++ b/spring-cloud-vault/1.0.0.RC1/index.html @@ -0,0 +1,2032 @@ + + + + + + + +Spring Cloud Vault + + + + + +
+
+
+
+

© 2016-2017 The original authors.

+
+
+ + + + + +
+
Note
+		 +Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically. +
+
+
+

Spring Cloud Vault Config provides client-side support for externalized configuration in a distributed system. With Hashicorp’s Vault you have a central place to manage external secret properties for applications across all environments. Vault can manage static and dynamic secrets such as username/password for remote applications/resources and provide credentials for external services such as MySQL, PostgreSQL, Apache Cassandra, MongoDB, Consul, AWS and more.

+
+
+
+
+

Quick Start

+
+
+

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 7 and a properly configured JAVA_HOME environment variable

    +
    • +
+
+
+

Install Vault

+
+
+
+
$ src/test/bash/install_vault.sh
+
+
+
+

Create SSL certificates for Vault

+
+
+
+
$ src/test/bash/create_certificates.sh
+
+
+
+ + + + + +
+
Note
+		 +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. +
+
+
+

Start Vault server

+
+
+
+
$ src/test/bash/local_run_vault.sh
+
+
+
+

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 +so you need to initialize it first.

+
+
+
+
$ export VAULT_ADDR="https://localhost:8200"
+$ export VAULT_SKIP_VERIFY=true # Don't do this for production
+$ vault init
+
+
+
+

You should see something like:

+
+
+
+
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.

+
+
+
+
$ vault unseal (Key 1)
+$ vault unseal (Key 2)
+$ vault unseal (Key 3)
+$ export VAULT_TOKEN=(Root token)
+
+
+
+

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

+
+
+

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:

+
+
+
Example 1. pom.xml
+
+
+
+
<parent>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-parent</artifactId>
+    <version>1.5.2.RELEASE</version>
+    <relativePath /> <!-- lookup parent from repository -->
+</parent>
+
+<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-starter-vault-config</artifactId>
+        <version>{spring-cloud-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:

+
+
+
+
+
+
@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 bootstrap.properties (like application.properties but for +the bootstrap phase of an application context), e.g.

+
+
+
Example 2. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    host: localhost
+    port: 8200
+    scheme: https
+    connection-timeout: 5000
+    read-timeout: 15000
+    config:
+        order: -10
+
+
+
+
+
+
    +
  • +

    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.

    +
    • +
  • +

    connection-timeout sets the connection timeout in milliseconds

    +
    • +
  • +

    read-timeout sets the read timeout in milliseconds

    +
    • +
  • +

    config.order sets the order for the property source

    +
    • +
+
+
+

Enabling further integrations requires additional dependencies and +configuration. Depending on how you have set up Vault you might need +additional configuration like +SSL and +authentication. Checkout these +chapters in the +reference guide.

+
+
+

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 health.vault.enabled (default true)

+
+
+

Authentication

+
+

Vault requires an authentication mechanism to authorize client requests.

+
+
+

Spring Cloud Vault Config supports multiple authentication mechanisms to authenticate applications with Vault.

+
+
+

For a quickstart, use the root token printed by the Vault initialization.

+
+
+
Example 3. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    token: 19aefa97-cccc-bbbb-aaaa-225940e63d76
+
+
+
+
+
+ + + + + +
+
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. +
+
+
+
+
+
+

Authentication methods

+
+
+

Different organizations have different requirements for security +and authentication. Vault reflects that need by shipping multiple authentication +methods. Spring Cloud Vault supports token and AppId authentication.

+
+
+

Token authentication

+
+

Tokens are the core method for authentication within Vault. +Token authentication requires a static token to be provided using the +Bootstrap Application Context.

+
+
+ + + + + +
+
Note
+		 +Token authentication is the default authentication method. +If a token is disclosed an unintended party gains access to Vault and +can access secrets for the intended client. +
+
+
+
Example 4. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: TOKEN
+    token: 00000000-0000-0000-0000-000000000000
+
+
+
+
+
+
    +
  • +

    authentication setting this value to TOKEN selects the Token +authentication method

    +
    • +
  • +

    token sets the static token to use

    +
    • +
+
+
+

See also: Vault Documentation: Tokens

+
+
+
+

AppId authentication

+
+

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 Cloud Vault Config 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.

+
+
+
Example 5. bootstrap.yml using SHA256 IP-Address UserId’s
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: IP_ADDRESS
+
+
+
+
+
+
    +
  • +

    authentication setting this value to APPID selects the AppId +authentication method

    +
    • +
  • +

    app-id-path sets the path of the AppId mount to use

    +
    • +
  • +

    user-id sets the UserId method. Possible values are IP_ADDRESS, +MAC_ADDRESS or a class name implementing a custom AppIdUserIdMechanism

    +
    • +
+
+
+

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

+
+
+
+
$ echo -n 192.168.99.1 | sha256sum
+
+
+
+ + + + + +
+
Note
+		 +Including the line break of echo leads to a different hash value +so make sure to include the -n flag. +
+
+
+

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).

+
+
+
Example 6. bootstrap.yml using SHA256 Mac-Address UserId’s
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: MAC_ADDRESS
+        network-interface: eth0
+
+
+
+
+
+
    +
  • +

    network-interface sets network interface to obtain the physical address

    +
    • +
+
+
+

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

+
+
+
+
$ echo -n 0AFEDE1234AC | sha256sum
+
+
+
+ + + + + +
+
Note
+		 +The Mac address is specified uppercase and without colons. +Including the line break of echo leads to a different hash value +so make sure to include the -n flag. +
+
+
+

Custom UserId

+
+

The UserId generation is an open mechanism. You can set +spring.cloud.vault.app-id.user-id to any string and the configured +value will be used as static UserId.

+
+
+

A more advanced approach lets you set spring.cloud.vault.app-id.user-id to a +classname. This class must be on your classpath and must implement +the org.springframework.cloud.vault.AppIdUserIdMechanism interface +and the createUserId method. Spring Cloud Vault will obtain the UserId +by calling createUserId each time it authenticates using AppId to +obtain a token.

+
+
+
Example 7. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: com.examlple.MyUserIdMechanism
+
+
+
+
+
+
Example 8. MyUserIdMechanism.java
+
+
+
+
public class MyUserIdMechanism implements AppIdUserIdMechanism {
+
+  @Override
+  public String createUserId() {
+    String userId = ...
+    return userId;
+  }
+}
+
+
+
+
+
+

See also: Vault Documentation: Using the App ID auth backend

+
+
+
+
+

AppRole authentication

+
+

AppRole is intended for 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 (push or pull mode).

+
+
+

RoleId and optionally SecretId must be provided by configuration, +Spring Vault will not look up these or create a custom SecretId.

+
+
+
Example 9. bootstrap.yml with AppRole authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
+
+
+
+
+
+
    +
  • +

    role-id sets the RoleId.

    +
    • +
+
+
+
Example 10. bootstrap.yml with all AppRole authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
+        secret-id: 1696536f-1976-73b1-b241-0b4213908d39
+        app-auth-path: approle
+
+
+
+
+
+
    +
  • +

    role-id sets the RoleId.

    +
    • +
  • +

    secret-id sets the SecretId. SecretId can be omitted if AppRole is configured without requiring SecretId (See bind_secret_id)

    +
    • +
  • +

    approle-path sets the path of the approle authentication mount to use

    +
    • +
+
+
+

See also: Vault Documentation: Using the AppRole auth backend

+
+
+
+

AWS-EC2 authentication

+
+

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.

+
+
+
Example 11. bootstrap.yml using AWS-EC2 Authentication
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+
+
+
+
+
+

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 Cloud 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.

+
+
+
Example 12. bootstrap.yml with disabled nonce
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        use-nonce: false
+
+
+
+
+
+

AWS-EC2 authentication roles are optional and default to the AMI. +You can configure the authentication role by setting the +spring.cloud.vault.aws-ec2.role property.

+
+
+
Example 13. bootstrap.yml with configured role
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server
+
+
+
+
+
+
Example 14. bootstrap.yml with all AWS EC2 authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server
+        aws-ec2-path: aws-ec2
+        identity-document: http://...
+        use-nonce: false
+
+
+
+
+
+
    +
  • +

    authentication setting this value to AWS_EC2 selects the AWS EC2 +authentication method

    +
    • +
  • +

    role sets the role name of the AWS EC2 role definition

    +
    • +
  • +

    aws-ec2-path sets the path of the AWS EC2 mount to use

    +
    • +
  • +

    identity-document sets URL of the PKCS#7 AWS EC2 identity document

    +
    • +
  • +

    use-nonce setting this value to false will disable nonce usage

    +
    • +
+
+
+

See also: Vault Documentation: Using the aws-ec2 auth backend

+
+
+
+

TLS certificate authentication

+
+

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:

+
+
+
    +
  1. +

    Use SSL, see Vault Client SSL configuration

    +
    2. +
  2. +

    Configure a Java Keystore that contains the client +certificate and the private key

    +
    3. +
  3. +

    Set the spring.cloud.vault.authentication to CERT

    +
    4. +
+
+
+
Example 15. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: CERT
+    ssl:
+        key-store: classpath:keystore.jks
+        key-store-password: changeit
+        cert-auth-path: cert
+
+
+
+
+
+

See also: Vault Documentation: Using the Cert auth backend

+
+
+
+

Cubbyhole authentication

+
+

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 will be retrieved from a wrapped +response stored at /cubbyhole/response.

+
+
+

Creating a wrapped token

+
+
+ + + + + +
+
Note
+		 +Response Wrapping for token creation requires Vault 0.6.0 or higher. +
+
+
+
Example 16. Crating and storing tokens
+
+
+
+
$ vault token-create -wrap-ttl="10m"
+Key                            Value
+---                            -----
+wrapping_token:                397ccb93-ff6c-b17b-9389-380b01ca2645
+wrapping_token_ttl:            0h10m0s
+wrapping_token_creation_time:  2016-09-18 20:29:48.652957077 +0200 CEST
+wrapped_accessor:              46b6aebb-187f-932a-26d7-4f3d86a68319
+
+
+
+
+
+
Example 17. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: CUBBYHOLE
+    token: 397ccb93-ff6c-b17b-9389-380b01ca2645
+
+
+
+
+
+

See also:

+
+
+ +
+
+
+
+
+

Secret Backends

+
+
+

Generic Backend

+
+

Spring Cloud Vault supports at the basic level the generic secret +backend. The generic secret backend allows storage of arbitrary +values as key-value store. A single context can store one or many +key-value tuples. Contexts can be organized hierarchically. +Spring Cloud Vault allows using the Application name +and a default context name (application) in combination with active +profiles.

+
+
+
+
/secret/{application}/{profile}
+/secret/{application}
+/secret/{default-context}/{profile}
+/secret/{default-context}
+
+
+
+

The application name is determined by the properties:

+
+
+
    +
  • +

    spring.cloud.vault.generic.application-name

    +
    • +
  • +

    spring.cloud.vault.application-name

    +
    • +
  • +

    spring.application.name

    +
    • +
+
+
+

Secrets can be obtained from other folders within the generic backend by adding their +paths to the application name, separated by commas. For example, given the application +name usefulapp,mysql1,projectx/aws, each of these folders will be used:

+
+
+
    +
  • +

    /secret/usefulapp

    +
    • +
  • +

    /secret/mysql1

    +
    • +
  • +

    /secret/projectx/aws

    +
    • +
+
+
+

Spring Cloud Vault adds all active profiles to the list of possible context paths. +No active profiles will skip accessing contexts with a profile name.

+
+
+

Properties are exposed like they are stored (i.e. without additional prefixes).

+
+
+
+
+
+
spring.cloud.vault:
+    generic:
+        enabled: true
+        backend: secret
+        profile-separator: '/'
+        default-context: application
+        application-name: my-app
+
+
+
+
+
+
    +
  • +

    enabled setting this value to false disables the secret backend +config usage

    +
    • +
  • +

    backend sets the path of the secret mount to use

    +
    • +
  • +

    default-context sets the context name used by all applications

    +
    • +
  • +

    application-name overrides the application name for use in the generic backend

    +
    • +
  • +

    profile-separator separates the profile name from the context in +property sources with profiles

    +
    • +
+
+
+

See also: Vault Documentation: Using the generic secret backend

+
+
+
+

Consul

+
+

Spring Cloud Vault can obtain credentials for HashiCorp Consul. +The Consul integration requires the spring-cloud-vault-config-consul +dependency.

+
+
+
Example 18. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-consul</artifactId>
+        <version>x.y.z</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.consul.enabled=true (default false) and +providing the role name with spring.cloud.vault.consul.role=….

+
+
+

The obtained token is stored in spring.cloud.consul.token +so using Spring Cloud Consul can pick up the generated +credentials without further configuration. You can configure +the property name by setting spring.cloud.vault.consul.token-property.

+
+
+
+
+
+
spring.cloud.vault:
+    consul:
+        enabled: true
+        role: readonly
+        backend: consul
+        token-property: spring.cloud.consul.token
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the Consul backend config usage

    +
    • +
  • +

    role sets the role name of the Consul role definition

    +
    • +
  • +

    backend sets the path of the Consul mount to use

    +
    • +
  • +

    token-property sets the property name in which the Consul ACL token is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up Consul with Vault

+
+
+
+

RabbitMQ

+
+

Spring Cloud Vault can obtain credentials for RabbitMQ.

+
+
+

The RabbitMQ integration requires the spring-cloud-vault-config-rabbitmq +dependency.

+
+
+
Example 19. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-rabbitmq</artifactId>
+        <version>x.y.z</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.rabbitmq.enabled=true (default false) +and providing the role name with spring.cloud.vault.rabbitmq.role=….

+
+
+

Username and password are stored in spring.rabbitmq.username +and spring.rabbitmq.password so using Spring Boot will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.rabbitmq.username-property and +spring.cloud.vault.rabbitmq.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    rabbitmq:
+        enabled: true
+        role: readonly
+        backend: rabbitmq
+        username-property: spring.rabbitmq.username
+        password-property: spring.rabbitmq.password
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the RabbitMQ backend config usage

    +
    • +
  • +

    role sets the role name of the RabbitMQ role definition

    +
    • +
  • +

    backend sets the path of the RabbitMQ mount to use

    +
    • +
  • +

    username-property sets the property name in which the RabbitMQ username is stored

    +
    • +
  • +

    password-property sets the property name in which the RabbitMQ password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up RabbitMQ with Vault

+
+
+
+

AWS

+
+

Spring Cloud Vault can obtain credentials for AWS.

+
+
+

The AWS integration requires the spring-cloud-vault-config-aws +dependency.

+
+
+
Example 20. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-aws</artifactId>
+        <version>x.y.z</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.aws=true (default false) +and providing the role name with spring.cloud.vault.aws.role=….

+
+
+

The access key and secret key are stored in cloud.aws.credentials.accessKey +and cloud.aws.credentials.secretKey so using Spring Cloud AWS will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.aws.access-key-property and +spring.cloud.vault.aws.secret-key-property.

+
+
+
+
+
+
spring.cloud.vault:
+    aws:
+        enabled: true
+        role: readonly
+        backend: aws
+        access-key-property: cloud.aws.credentials.accessKey
+        secret-key-property: cloud.aws.credentials.secretKey
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the AWS backend config usage

    +
    • +
  • +

    role sets the role name of the AWS role definition

    +
    • +
  • +

    backend sets the path of the AWS mount to use

    +
    • +
  • +

    access-key-property sets the property name in which the AWS access key is stored

    +
    • +
  • +

    secret-key-property sets the property name in which the AWS secret key is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up AWS with Vault

+
+
+
+
+
+

Database backends

+
+
+

Vault supports several database secret backends to generate database +credentials dynamically based on configured roles. This means +services that need to access a database no longer need to configure +credentials: they can request them from Vault, and use Vault’s leasing +mechanism to more easily roll keys.

+
+
+

Spring Cloud Vault integrates with these backends:

+
+
+ +
+
+

Using a database secret backend requires to enable the +backend in the configuration and the spring-cloud-vault-config-databases +dependency.

+
+
+
Example 21. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-databases</artifactId>
+        <version>x.y.z</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+ + + + + +
+
Note
+		 +Enabling multiple JDBC-compliant databases will generate credentials +and store them by default in the same property keys hence property names for +JDBC secrets need to be configured separately. +
+
+
+

Apache Cassandra

+
+

Spring Cloud Vault can obtain credentials for Apache Cassandra. +The integration can be enabled by setting +spring.cloud.vault.cassandra.enabled=true (default false) and +providing the role name with spring.cloud.vault.cassandra.role=….

+
+
+

Username and password are stored in spring.data.cassandra.username +and spring.data.cassandra.password so using Spring Boot will pick +up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.cassandra.username-property and +spring.cloud.vault.cassandra.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    cassandra:
+        enabled: true
+        role: readonly
+        backend: cassandra
+        username-property: spring.data.cassandra.username
+        password-property: spring.data.cassandra.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the Cassandra backend config usage

    +
    • +
  • +

    role sets the role name of the Cassandra role definition

    +
    • +
  • +

    backend sets the path of the Cassandra mount to use

    +
    • +
  • +

    username-property sets the property name in which the Cassandra username is stored

    +
    • +
  • +

    password-property sets the property name in which the Cassandra password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up Apache Cassandra with Vault

+
+
+
+

MongoDB

+
+

Spring Cloud Vault can obtain credentials for MongoDB. +The integration can be enabled by setting +spring.cloud.vault.mongodb.enabled=true (default false) and +providing the role name with spring.cloud.vault.mongodb.role=….

+
+
+

Username and password are stored in spring.data.mongodb.username +and spring.data.mongodb.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mongodb.username-property and +spring.cloud.vault.mongodb.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    mongodb:
+        enabled: true
+        role: readonly
+        backend: mongodb
+        username-property: spring.data.mongodb.username
+        password-property: spring.data.mongodb.password
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the MongodB backend config usage

    +
    • +
  • +

    role sets the role name of the MongoDB role definition

    +
    • +
  • +

    backend sets the path of the MongoDB mount to use

    +
    • +
  • +

    username-property sets the property name in which the MongoDB username is stored

    +
    • +
  • +

    password-property sets the property name in which the MongoDB password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up MongoDB with Vault

+
+
+
+

MySQL

+
+

Spring Cloud Vault can obtain credentials for MySQL. +The integration can be enabled by setting +spring.cloud.vault.mysql.enabled=true (default false) and +providing the role name with spring.cloud.vault.mysql.role=….

+
+
+

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mysql.username-property and +spring.cloud.vault.mysql.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    mysql:
+        enabled: true
+        role: readonly
+        backend: mysql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the MySQL backend config usage

    +
    • +
  • +

    role sets the role name of the MySQL role definition

    +
    • +
  • +

    backend sets the path of the MySQL mount to use

    +
    • +
  • +

    username-property sets the property name in which the MySQL username is stored

    +
    • +
  • +

    password-property sets the property name in which the MySQL password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up MySQL with Vault

+
+
+
+

PostgreSQL

+
+

Spring Cloud Vault can obtain credentials for PostgreSQL. +The integration can be enabled by setting +spring.cloud.vault.postgresql.enabled=true (default false) and +providing the role name with spring.cloud.vault.postgresql.role=….

+
+
+

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.postgresql.username-property and +spring.cloud.vault.postgresql.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    postgresql:
+        enabled: true
+        role: readonly
+        backend: postgresql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the PostgreSQL backend config usage

    +
    • +
  • +

    role sets the role name of the PostgreSQL role definition

    +
    • +
  • +

    backend sets the path of the PostgreSQL mount to use

    +
    • +
  • +

    username-property sets the property name in which the PostgreSQL username is stored

    +
    • +
  • +

    password-property sets the property name in which the PostgreSQL password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up PostgreSQL with Vault

+
+
+
+
+
+

Vault Client Fail Fast

+
+
+

In some cases, it may be desirable to fail startup of a service if +it cannot connect to the Vault Server. If this is the desired +behavior, set the bootstrap configuration property +spring.cloud.vault.fail-fast=true and the client will halt with +an Exception.

+
+
+
+
+
+
spring.cloud.vault:
+    fail-fast: true
+
+
+
+
+
+
+
+

Vault Client SSL configuration

+
+
+

SSL can be configured declaratively by setting various properties. +You can set either javax.net.ssl.trustStore to configure +JVM-wide SSL settings or spring.cloud.vault.ssl.trust-store +to set SSL settings only for Spring Cloud Vault Config.

+
+
+
+
+
+
spring.cloud.vault:
+    ssl:
+        trust-store: classpath:keystore.jks
+        trust-store-password: changeit
+
+
+
+
+
+
    +
  • +

    trust-store sets the resource for the trust-store. SSL-secured Vault +communication will validate the Vault SSL certificate with the specified +trust-store.

    +
    • +
  • +

    trust-store-password sets the trust-store password

    +
    • +
+
+
+

Please note that configuring spring.cloud.vault.ssl.* can be only +applied when either Apache Http Components or the OkHttp client +is on your class-path.

+
+
+
+
+

Lease lifecycle management (renewal and revocation)

+
+
+

With every secret, Vault creates a lease: +metadata containing information such as a time duration, +renewability, and more.

+
+
+

Vault promises that the data will be valid for the given duration, +or Time To Live (TTL). Once the lease is expired, Vault can +revoke the data, and the consumer of the secret can no longer +be certain that it is valid.

+
+
+

Spring Cloud Vault maintains a lease lifecycle beyond +the creation of login tokens and secrets. That said, +login tokens and secrets associated with a lease +are scheduled for renewal just before the lease expires +until terminal expiry. +Application shutdown revokes obtained login tokens and renewable +leases.

+
+
+

Secret service and database backends (such as MongoDB or MySQL) +usually generate a renewable lease so generated credentials will +be disabled on application shutdown.

+
+
+ + + + + +
+
Note
+		 +Static tokens are not renewed or revoked. +
+
+
+

Lease renewal and revocation is enabled by default and can +be disabled by setting spring.cloud.vault.config.lifecycle.enabled +to false. This is not recommended as leases can expire and +Spring Cloud Vault cannot longer access Vault or services +using generated credentials and valid credentials remain active +after application shutdown.

+
+
+
+
+
+
spring.cloud.vault:
+    config.lifecycle.enabled: true
+
+
+
+
+
+

See also: Vault Documentation: Lease, Renew, and Revoke

+
+
+
+
+ + diff --git a/spring-cloud-vault/1.0.0.RELEASE/index.html b/spring-cloud-vault/1.0.0.RELEASE/index.html new file mode 100644 index 00000000..de73ef4d --- /dev/null +++ b/spring-cloud-vault/1.0.0.RELEASE/index.html @@ -0,0 +1,2036 @@ + + + + + + + +Spring Cloud Vault + + + + + +
+
+
+
+

© 2016-2017 The original authors.

+
+
+ + + + + +
+
Note
+		 +Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically. +
+
+
+

Spring Cloud Vault Config provides client-side support for externalized configuration in a distributed system. With HashiCorp’s Vault you have a central place to manage external secret properties for applications across all environments. Vault can manage static and dynamic secrets such as username/password for remote applications/resources and provide credentials for external services such as MySQL, PostgreSQL, Apache Cassandra, MongoDB, Consul, AWS and more.

+
+
+
+
+

Quick Start

+
+
+

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 7 and a properly configured JAVA_HOME environment variable

    +
    • +
+
+
+

Install Vault

+
+
+
+
$ src/test/bash/install_vault.sh
+
+
+
+

Create SSL certificates for Vault

+
+
+
+
$ src/test/bash/create_certificates.sh
+
+
+
+ + + + + +
+
Note
+		 +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. +
+
+
+

Start Vault server

+
+
+
+
$ src/test/bash/local_run_vault.sh
+
+
+
+

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 +so you need to initialize it first.

+
+
+
+
$ export VAULT_ADDR="https://localhost:8200"
+$ export VAULT_SKIP_VERIFY=true # Don't do this for production
+$ vault init
+
+
+
+

You should see something like:

+
+
+
+
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.

+
+
+
+
$ vault unseal (Key 1)
+$ vault unseal (Key 2)
+$ vault unseal (Key 3)
+$ export VAULT_TOKEN=(Root token)
+
+
+
+

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

+
+
+

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:

+
+
+
Example 1. pom.xml
+
+
+
+
<parent>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-parent</artifactId>
+    <version>1.5.2.RELEASE</version>
+    <relativePath /> <!-- lookup parent from repository -->
+</parent>
+
+<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-starter-vault-config</artifactId>
+        <version>{spring-cloud-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:

+
+
+
+
+
+
@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 bootstrap.properties (like application.properties but for +the bootstrap phase of an application context), e.g.

+
+
+
Example 2. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    host: localhost
+    port: 8200
+    scheme: https
+    connection-timeout: 5000
+    read-timeout: 15000
+    config:
+        order: -10
+
+
+
+
+
+
    +
  • +

    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.

    +
    • +
  • +

    connection-timeout sets the connection timeout in milliseconds

    +
    • +
  • +

    read-timeout sets the read timeout in milliseconds

    +
    • +
  • +

    config.order sets the order for the property source

    +
    • +
+
+
+

Enabling further integrations requires additional dependencies and +configuration. Depending on how you have set up Vault you might need +additional configuration like +SSL and +authentication. Checkout these +chapters in the +reference guide.

+
+
+

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 health.vault.enabled (default true)

+
+
+

Authentication

+
+

Vault requires an authentication mechanism to authorize client requests.

+
+
+

Spring Cloud Vault Config supports multiple authentication mechanisms to authenticate applications with Vault.

+
+
+

For a quickstart, use the root token printed by the Vault initialization.

+
+
+
Example 3. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    token: 19aefa97-cccc-bbbb-aaaa-225940e63d76
+
+
+
+
+
+ + + + + +
+
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. +
+
+
+
+
+
+

Authentication methods

+
+
+

Different organizations have different requirements for security +and authentication. Vault reflects that need by shipping multiple authentication +methods. Spring Cloud Vault supports token and AppId authentication.

+
+
+

Token authentication

+
+

Tokens are the core method for authentication within Vault. +Token authentication requires a static token to be provided using the +Bootstrap Application Context.

+
+
+ + + + + +
+
Note
+		 +Token authentication is the default authentication method. +If a token is disclosed an unintended party gains access to Vault and +can access secrets for the intended client. +
+
+
+
Example 4. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: TOKEN
+    token: 00000000-0000-0000-0000-000000000000
+
+
+
+
+
+
    +
  • +

    authentication setting this value to TOKEN selects the Token +authentication method

    +
    • +
  • +

    token sets the static token to use

    +
    • +
+
+
+

See also: Vault Documentation: Tokens

+
+
+
+

AppId authentication

+
+

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 Cloud Vault Config 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.

+
+
+
Example 5. bootstrap.yml using SHA256 IP-Address UserId’s
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: IP_ADDRESS
+
+
+
+
+
+
    +
  • +

    authentication setting this value to APPID selects the AppId +authentication method

    +
    • +
  • +

    app-id-path sets the path of the AppId mount to use

    +
    • +
  • +

    user-id sets the UserId method. Possible values are IP_ADDRESS, +MAC_ADDRESS or a class name implementing a custom AppIdUserIdMechanism

    +
    • +
+
+
+

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

+
+
+
+
$ echo -n 192.168.99.1 | sha256sum
+
+
+
+ + + + + +
+
Note
+		 +Including the line break of echo leads to a different hash value +so make sure to include the -n flag. +
+
+
+

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).

+
+
+
Example 6. bootstrap.yml using SHA256 Mac-Address UserId’s
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: MAC_ADDRESS
+        network-interface: eth0
+
+
+
+
+
+
    +
  • +

    network-interface sets network interface to obtain the physical address

    +
    • +
+
+
+

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

+
+
+
+
$ echo -n 0AFEDE1234AC | sha256sum
+
+
+
+ + + + + +
+
Note
+		 +The Mac address is specified uppercase and without colons. +Including the line break of echo leads to a different hash value +so make sure to include the -n flag. +
+
+
+

Custom UserId

+
+

The UserId generation is an open mechanism. You can set +spring.cloud.vault.app-id.user-id to any string and the configured +value will be used as static UserId.

+
+
+

A more advanced approach lets you set spring.cloud.vault.app-id.user-id to a +classname. This class must be on your classpath and must implement +the org.springframework.cloud.vault.AppIdUserIdMechanism interface +and the createUserId method. Spring Cloud Vault will obtain the UserId +by calling createUserId each time it authenticates using AppId to +obtain a token.

+
+
+
Example 7. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: com.examlple.MyUserIdMechanism
+
+
+
+
+
+
Example 8. MyUserIdMechanism.java
+
+
+
+
public class MyUserIdMechanism implements AppIdUserIdMechanism {
+
+  @Override
+  public String createUserId() {
+    String userId = ...
+    return userId;
+  }
+}
+
+
+
+
+
+

See also: Vault Documentation: Using the App ID auth backend

+
+
+
+
+

AppRole authentication

+
+

AppRole is intended for 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 (push or pull mode).

+
+
+

RoleId and optionally SecretId must be provided by configuration, +Spring Vault will not look up these or create a custom SecretId.

+
+
+
Example 9. bootstrap.yml with AppRole authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
+
+
+
+
+
+
    +
  • +

    role-id sets the RoleId.

    +
    • +
+
+
+
Example 10. bootstrap.yml with all AppRole authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
+        secret-id: 1696536f-1976-73b1-b241-0b4213908d39
+        app-auth-path: approle
+
+
+
+
+
+
    +
  • +

    role-id sets the RoleId.

    +
    • +
  • +

    secret-id sets the SecretId. SecretId can be omitted if AppRole is configured without requiring SecretId (See bind_secret_id)

    +
    • +
  • +

    approle-path sets the path of the approle authentication mount to use

    +
    • +
+
+
+

See also: Vault Documentation: Using the AppRole auth backend

+
+
+
+

AWS-EC2 authentication

+
+

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.

+
+
+
Example 11. bootstrap.yml using AWS-EC2 Authentication
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+
+
+
+
+
+

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 Cloud 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.

+
+
+
Example 12. bootstrap.yml with disabled nonce
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        use-nonce: false
+
+
+
+
+
+

AWS-EC2 authentication roles are optional and default to the AMI. +You can configure the authentication role by setting the +spring.cloud.vault.aws-ec2.role property.

+
+
+
Example 13. bootstrap.yml with configured role
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server
+
+
+
+
+
+
Example 14. bootstrap.yml with all AWS EC2 authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server
+        aws-ec2-path: aws-ec2
+        identity-document: http://...
+        use-nonce: false
+
+
+
+
+
+
    +
  • +

    authentication setting this value to AWS_EC2 selects the AWS EC2 +authentication method

    +
    • +
  • +

    role sets the role name of the AWS EC2 role definition

    +
    • +
  • +

    aws-ec2-path sets the path of the AWS EC2 mount to use

    +
    • +
  • +

    identity-document sets URL of the PKCS#7 AWS EC2 identity document

    +
    • +
  • +

    use-nonce setting this value to false will disable nonce usage

    +
    • +
+
+
+

See also: Vault Documentation: Using the aws-ec2 auth backend

+
+
+
+

TLS certificate authentication

+
+

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:

+
+
+
    +
  1. +

    Use SSL, see Vault Client SSL configuration

    +
    2. +
  2. +

    Configure a Java Keystore that contains the client +certificate and the private key

    +
    3. +
  3. +

    Set the spring.cloud.vault.authentication to CERT

    +
    4. +
+
+
+
Example 15. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: CERT
+    ssl:
+        key-store: classpath:keystore.jks
+        key-store-password: changeit
+        cert-auth-path: cert
+
+
+
+
+
+

See also: Vault Documentation: Using the Cert auth backend

+
+
+
+

Cubbyhole authentication

+
+

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 will be retrieved from a wrapped +response stored at /cubbyhole/response.

+
+
+

Creating a wrapped token

+
+
+ + + + + +
+
Note
+		 +Response Wrapping for token creation requires Vault 0.6.0 or higher. +
+
+
+
Example 16. Crating and storing tokens
+
+
+
+
$ vault token-create -wrap-ttl="10m"
+Key                            Value
+---                            -----
+wrapping_token:                397ccb93-ff6c-b17b-9389-380b01ca2645
+wrapping_token_ttl:            0h10m0s
+wrapping_token_creation_time:  2016-09-18 20:29:48.652957077 +0200 CEST
+wrapped_accessor:              46b6aebb-187f-932a-26d7-4f3d86a68319
+
+
+
+
+
+
Example 17. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: CUBBYHOLE
+    token: 397ccb93-ff6c-b17b-9389-380b01ca2645
+
+
+
+
+
+

See also:

+
+
+ +
+
+
+
+
+

Secret Backends

+
+
+

Generic Backend

+
+

Spring Cloud Vault supports at the basic level the generic secret +backend. The generic secret backend allows storage of arbitrary +values as key-value store. A single context can store one or many +key-value tuples. Contexts can be organized hierarchically. +Spring Cloud Vault allows using the Application name +and a default context name (application) in combination with active +profiles.

+
+
+
+
/secret/{application}/{profile}
+/secret/{application}
+/secret/{default-context}/{profile}
+/secret/{default-context}
+
+
+
+

The application name is determined by the properties:

+
+
+
    +
  • +

    spring.cloud.vault.generic.application-name

    +
    • +
  • +

    spring.cloud.vault.application-name

    +
    • +
  • +

    spring.application.name

    +
    • +
+
+
+

Secrets can be obtained from other folders within the generic backend by adding their +paths to the application name, separated by commas. For example, given the application +name usefulapp,mysql1,projectx/aws, each of these folders will be used:

+
+
+
    +
  • +

    /secret/usefulapp

    +
    • +
  • +

    /secret/mysql1

    +
    • +
  • +

    /secret/projectx/aws

    +
    • +
+
+
+

Spring Cloud Vault adds all active profiles to the list of possible context paths. +No active profiles will skip accessing contexts with a profile name.

+
+
+

Properties are exposed like they are stored (i.e. without additional prefixes).

+
+
+
+
+
+
spring.cloud.vault:
+    generic:
+        enabled: true
+        backend: secret
+        profile-separator: '/'
+        default-context: application
+        application-name: my-app
+
+
+
+
+
+
    +
  • +

    enabled setting this value to false disables the secret backend +config usage

    +
    • +
  • +

    backend sets the path of the secret mount to use

    +
    • +
  • +

    default-context sets the context name used by all applications

    +
    • +
  • +

    application-name overrides the application name for use in the generic backend

    +
    • +
  • +

    profile-separator separates the profile name from the context in +property sources with profiles

    +
    • +
+
+
+

See also: Vault Documentation: Using the generic secret backend

+
+
+
+

Consul

+
+

Spring Cloud Vault can obtain credentials for HashiCorp Consul. +The Consul integration requires the spring-cloud-vault-config-consul +dependency.

+
+
+
Example 18. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-consul</artifactId>
+        <version>x.y.z</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.consul.enabled=true (default false) and +providing the role name with spring.cloud.vault.consul.role=….

+
+
+

The obtained token is stored in spring.cloud.consul.token +so using Spring Cloud Consul can pick up the generated +credentials without further configuration. You can configure +the property name by setting spring.cloud.vault.consul.token-property.

+
+
+
+
+
+
spring.cloud.vault:
+    consul:
+        enabled: true
+        role: readonly
+        backend: consul
+        token-property: spring.cloud.consul.token
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the Consul backend config usage

    +
    • +
  • +

    role sets the role name of the Consul role definition

    +
    • +
  • +

    backend sets the path of the Consul mount to use

    +
    • +
  • +

    token-property sets the property name in which the Consul ACL token is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up Consul with Vault

+
+
+
+

RabbitMQ

+
+

Spring Cloud Vault can obtain credentials for RabbitMQ.

+
+
+

The RabbitMQ integration requires the spring-cloud-vault-config-rabbitmq +dependency.

+
+
+
Example 19. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-rabbitmq</artifactId>
+        <version>x.y.z</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.rabbitmq.enabled=true (default false) +and providing the role name with spring.cloud.vault.rabbitmq.role=….

+
+
+

Username and password are stored in spring.rabbitmq.username +and spring.rabbitmq.password so using Spring Boot will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.rabbitmq.username-property and +spring.cloud.vault.rabbitmq.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    rabbitmq:
+        enabled: true
+        role: readonly
+        backend: rabbitmq
+        username-property: spring.rabbitmq.username
+        password-property: spring.rabbitmq.password
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the RabbitMQ backend config usage

    +
    • +
  • +

    role sets the role name of the RabbitMQ role definition

    +
    • +
  • +

    backend sets the path of the RabbitMQ mount to use

    +
    • +
  • +

    username-property sets the property name in which the RabbitMQ username is stored

    +
    • +
  • +

    password-property sets the property name in which the RabbitMQ password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up RabbitMQ with Vault

+
+
+
+

AWS

+
+

Spring Cloud Vault can obtain credentials for AWS.

+
+
+

The AWS integration requires the spring-cloud-vault-config-aws +dependency.

+
+
+
Example 20. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-aws</artifactId>
+        <version>x.y.z</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.aws=true (default false) +and providing the role name with spring.cloud.vault.aws.role=….

+
+
+

The access key and secret key are stored in cloud.aws.credentials.accessKey +and cloud.aws.credentials.secretKey so using Spring Cloud AWS will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.aws.access-key-property and +spring.cloud.vault.aws.secret-key-property.

+
+
+
+
+
+
spring.cloud.vault:
+    aws:
+        enabled: true
+        role: readonly
+        backend: aws
+        access-key-property: cloud.aws.credentials.accessKey
+        secret-key-property: cloud.aws.credentials.secretKey
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the AWS backend config usage

    +
    • +
  • +

    role sets the role name of the AWS role definition

    +
    • +
  • +

    backend sets the path of the AWS mount to use

    +
    • +
  • +

    access-key-property sets the property name in which the AWS access key is stored

    +
    • +
  • +

    secret-key-property sets the property name in which the AWS secret key is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up AWS with Vault

+
+
+
+
+
+

Database backends

+
+
+

Vault supports several database secret backends to generate database +credentials dynamically based on configured roles. This means +services that need to access a database no longer need to configure +credentials: they can request them from Vault, and use Vault’s leasing +mechanism to more easily roll keys.

+
+
+

Spring Cloud Vault integrates with these backends:

+
+
+ +
+
+

Using a database secret backend requires to enable the +backend in the configuration and the spring-cloud-vault-config-databases +dependency.

+
+
+
Example 21. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-databases</artifactId>
+        <version>x.y.z</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+ + + + + +
+
Note
+		 +Enabling multiple JDBC-compliant databases will generate credentials +and store them by default in the same property keys hence property names for +JDBC secrets need to be configured separately. +
+
+
+

Apache Cassandra

+
+

Spring Cloud Vault can obtain credentials for Apache Cassandra. +The integration can be enabled by setting +spring.cloud.vault.cassandra.enabled=true (default false) and +providing the role name with spring.cloud.vault.cassandra.role=….

+
+
+

Username and password are stored in spring.data.cassandra.username +and spring.data.cassandra.password so using Spring Boot will pick +up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.cassandra.username-property and +spring.cloud.vault.cassandra.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    cassandra:
+        enabled: true
+        role: readonly
+        backend: cassandra
+        username-property: spring.data.cassandra.username
+        password-property: spring.data.cassandra.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the Cassandra backend config usage

    +
    • +
  • +

    role sets the role name of the Cassandra role definition

    +
    • +
  • +

    backend sets the path of the Cassandra mount to use

    +
    • +
  • +

    username-property sets the property name in which the Cassandra username is stored

    +
    • +
  • +

    password-property sets the property name in which the Cassandra password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up Apache Cassandra with Vault

+
+
+
+

MongoDB

+
+

Spring Cloud Vault can obtain credentials for MongoDB. +The integration can be enabled by setting +spring.cloud.vault.mongodb.enabled=true (default false) and +providing the role name with spring.cloud.vault.mongodb.role=….

+
+
+

Username and password are stored in spring.data.mongodb.username +and spring.data.mongodb.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mongodb.username-property and +spring.cloud.vault.mongodb.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    mongodb:
+        enabled: true
+        role: readonly
+        backend: mongodb
+        username-property: spring.data.mongodb.username
+        password-property: spring.data.mongodb.password
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the MongodB backend config usage

    +
    • +
  • +

    role sets the role name of the MongoDB role definition

    +
    • +
  • +

    backend sets the path of the MongoDB mount to use

    +
    • +
  • +

    username-property sets the property name in which the MongoDB username is stored

    +
    • +
  • +

    password-property sets the property name in which the MongoDB password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up MongoDB with Vault

+
+
+
+

MySQL

+
+

Spring Cloud Vault can obtain credentials for MySQL. +The integration can be enabled by setting +spring.cloud.vault.mysql.enabled=true (default false) and +providing the role name with spring.cloud.vault.mysql.role=….

+
+
+

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mysql.username-property and +spring.cloud.vault.mysql.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    mysql:
+        enabled: true
+        role: readonly
+        backend: mysql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the MySQL backend config usage

    +
    • +
  • +

    role sets the role name of the MySQL role definition

    +
    • +
  • +

    backend sets the path of the MySQL mount to use

    +
    • +
  • +

    username-property sets the property name in which the MySQL username is stored

    +
    • +
  • +

    password-property sets the property name in which the MySQL password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up MySQL with Vault

+
+
+
+

PostgreSQL

+
+

Spring Cloud Vault can obtain credentials for PostgreSQL. +The integration can be enabled by setting +spring.cloud.vault.postgresql.enabled=true (default false) and +providing the role name with spring.cloud.vault.postgresql.role=….

+
+
+

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.postgresql.username-property and +spring.cloud.vault.postgresql.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    postgresql:
+        enabled: true
+        role: readonly
+        backend: postgresql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the PostgreSQL backend config usage

    +
    • +
  • +

    role sets the role name of the PostgreSQL role definition

    +
    • +
  • +

    backend sets the path of the PostgreSQL mount to use

    +
    • +
  • +

    username-property sets the property name in which the PostgreSQL username is stored

    +
    • +
  • +

    password-property sets the property name in which the PostgreSQL password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up PostgreSQL with Vault

+
+
+
+
+
+

Vault Client Fail Fast

+
+
+

In some cases, it may be desirable to fail startup of a service if +it cannot connect to the Vault Server. If this is the desired +behavior, set the bootstrap configuration property +spring.cloud.vault.fail-fast=true and the client will halt with +an Exception.

+
+
+
+
+
+
spring.cloud.vault:
+    fail-fast: true
+
+
+
+
+
+
+
+

Vault Client SSL configuration

+
+
+

SSL can be configured declaratively by setting various properties. +You can set either javax.net.ssl.trustStore to configure +JVM-wide SSL settings or spring.cloud.vault.ssl.trust-store +to set SSL settings only for Spring Cloud Vault Config.

+
+
+
+
+
+
spring.cloud.vault:
+    ssl:
+        trust-store: classpath:keystore.jks
+        trust-store-password: changeit
+
+
+
+
+
+
    +
  • +

    trust-store sets the resource for the trust-store. SSL-secured Vault +communication will validate the Vault SSL certificate with the specified +trust-store.

    +
    • +
  • +

    trust-store-password sets the trust-store password

    +
    • +
+
+
+

Please note that configuring spring.cloud.vault.ssl.* can be only +applied when either Apache Http Components or the OkHttp client +is on your class-path.

+
+
+
+
+

Lease lifecycle management (renewal and revocation)

+
+
+

With every secret, Vault creates a lease: +metadata containing information such as a time duration, +renewability, and more.

+
+
+

Vault promises that the data will be valid for the given duration, +or Time To Live (TTL). Once the lease is expired, Vault can +revoke the data, and the consumer of the secret can no longer +be certain that it is valid.

+
+
+

Spring Cloud Vault maintains a lease lifecycle beyond +the creation of login tokens and secrets. That said, +login tokens and secrets associated with a lease +are scheduled for renewal just before the lease expires +until terminal expiry. +Application shutdown revokes obtained login tokens and renewable +leases.

+
+
+

Secret service and database backends (such as MongoDB or MySQL) +usually generate a renewable lease so generated credentials will +be disabled on application shutdown.

+
+
+ + + + + +
+
Note
+		 +Static tokens are not renewed or revoked. +
+
+
+

Lease renewal and revocation is enabled by default and can +be disabled by setting spring.cloud.vault.config.lifecycle.enabled +to false. This is not recommended as leases can expire and +Spring Cloud Vault cannot longer access Vault or services +using generated credentials and valid credentials remain active +after application shutdown.

+
+
+
+
+
+
spring.cloud.vault:
+    config.lifecycle.enabled: true
+
+
+
+
+
+

See also: Vault Documentation: Lease, Renew, and Revoke

+
+
+
+
+ + \ No newline at end of file diff --git a/spring-cloud-vault/1.0.1.RELEASE/ghpages.sh b/spring-cloud-vault/1.0.1.RELEASE/ghpages.sh new file mode 100644 index 00000000..57c5da3a --- /dev/null +++ b/spring-cloud-vault/1.0.1.RELEASE/ghpages.sh @@ -0,0 +1,330 @@ +#!/bin/bash -x + +set -e + +# Set default props like MAVEN_PATH, ROOT_FOLDER etc. +function set_default_props() { + # The script should be executed from the root folder + ROOT_FOLDER=`pwd` + echo "Current folder is ${ROOT_FOLDER}" + + if [[ ! -e "${ROOT_FOLDER}/.git" ]]; then + echo "You're not in the root folder of the project!" + exit 1 + fi + + # Prop that will let commit the changes + COMMIT_CHANGES="no" + MAVEN_PATH=${MAVEN_PATH:-} + echo "Path to Maven is [${MAVEN_PATH}]" + REPO_NAME=${PWD##*/} + echo "Repo name is [${REPO_NAME}]" + SPRING_CLOUD_STATIC_REPO=${SPRING_CLOUD_STATIC_REPO:-git@github.com:spring-cloud/spring-cloud-static.git} + echo "Spring Cloud Static repo is [${SPRING_CLOUD_STATIC_REPO}" +} + +# Check if gh-pages exists and docs have been built +function check_if_anything_to_sync() { + git remote set-url --push origin `git config remote.origin.url | sed -e 's/^git:/https:/'` + + if ! (git remote set-branches --add origin gh-pages && git fetch -q); then + echo "No gh-pages, so not syncing" + exit 0 + fi + + if ! [ -d docs/target/generated-docs ] && ! [ "${BUILD}" == "yes" ]; then + echo "No gh-pages sources in docs/target/generated-docs, so not syncing" + exit 0 + fi +} + +function retrieve_current_branch() { + # Code getting the name of the current branch. For master we want to publish as we did until now + # http://stackoverflow.com/questions/1593051/how-to-programmatically-determine-the-current-checked-out-git-branch + # If there is a branch already passed will reuse it - otherwise will try to find it + CURRENT_BRANCH=${BRANCH} + if [[ -z "${CURRENT_BRANCH}" ]] ; then + CURRENT_BRANCH=$(git symbolic-ref -q HEAD) + CURRENT_BRANCH=${CURRENT_BRANCH##refs/heads/} + CURRENT_BRANCH=${CURRENT_BRANCH:-HEAD} + fi + echo "Current branch is [${CURRENT_BRANCH}]" + git checkout ${CURRENT_BRANCH} || echo "Failed to check the branch... continuing with the script" +} + +# Switches to the provided value of the release version. We always prefix it with `v` +function switch_to_tag() { + git checkout v${VERSION} +} + +# Build the docs if switch is on +function build_docs_if_applicable() { + if [[ "${BUILD}" == "yes" ]] ; then + ./mvnw clean install -P docs -pl docs -DskipTests + fi +} + +# Get the name of the `docs.main` property +# Get whitelisted branches - assumes that a `docs` module is available under `docs` profile +function retrieve_doc_properties() { + MAIN_ADOC_VALUE=$("${MAVEN_PATH}"mvn -q \ + -Dexec.executable="echo" \ + -Dexec.args='${docs.main}' \ + --non-recursive \ + org.codehaus.mojo:exec-maven-plugin:1.3.1:exec) + echo "Extracted 'main.adoc' from Maven build [${MAIN_ADOC_VALUE}]" + + + WHITELIST_PROPERTY=${WHITELIST_PROPERTY:-"docs.whitelisted.branches"} + WHITELISTED_BRANCHES_VALUE=$("${MAVEN_PATH}"mvn -q \ + -Dexec.executable="echo" \ + -Dexec.args="\${${WHITELIST_PROPERTY}}" \ + org.codehaus.mojo:exec-maven-plugin:1.3.1:exec \ + -P docs \ + -pl docs) + echo "Extracted '${WHITELIST_PROPERTY}' from Maven build [${WHITELISTED_BRANCHES_VALUE}]" +} + +# Stash any outstanding changes +function stash_changes() { + git diff-index --quiet HEAD && dirty=$? || (echo "Failed to check if the current repo is dirty. Assuming that it is." && dirty="1") + if [ "$dirty" != "0" ]; then git stash; fi +} + +# Switch to gh-pages branch to sync it with current branch +function add_docs_from_target() { + local DESTINATION_REPO_FOLDER + if [[ -z "${DESTINATION}" && -z "${CLONE}" ]] ; then + DESTINATION_REPO_FOLDER=${ROOT_FOLDER} + elif [[ "${CLONE}" == "yes" ]]; then + mkdir -p ${ROOT_FOLDER}/target + local clonedStatic=${ROOT_FOLDER}/target/spring-cloud-static + if [[ ! -e "${clonedStatic}/.git" ]]; then + echo "Cloning Spring Cloud Static to target" + git clone ${SPRING_CLOUD_STATIC_REPO} ${clonedStatic} && git checkout gh-pages + else + echo "Spring Cloud Static already cloned - will pull changes" + cd ${clonedStatic} && git checkout gh-pages && git pull origin gh-pages + fi + DESTINATION_REPO_FOLDER=${clonedStatic}/${REPO_NAME} + mkdir -p ${DESTINATION_REPO_FOLDER} + else + if [[ ! -e "${DESTINATION}/.git" ]]; then + echo "[${DESTINATION}] is not a git repository" + exit 1 + fi + DESTINATION_REPO_FOLDER=${DESTINATION}/${REPO_NAME} + mkdir -p ${DESTINATION_REPO_FOLDER} + echo "Destination was provided [${DESTINATION}]" + fi + cd ${DESTINATION_REPO_FOLDER} + git checkout gh-pages + git pull origin gh-pages + + # Add git branches + ################################################################### + if [[ -z "${VERSION}" ]] ; then + copy_docs_for_current_version + else + copy_docs_for_provided_version + fi + commit_changes_if_applicable +} + + +# Copies the docs by using the retrieved properties from Maven build +function copy_docs_for_current_version() { + if [[ "${CURRENT_BRANCH}" == "master" ]] ; then + echo -e "Current branch is master - will copy the current docs only to the root folder" + for f in docs/target/generated-docs/*; do + file=${f#docs/target/generated-docs/*} + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then + # Not ignored... + cp -rf $f ${ROOT_FOLDER}/ + git add -A ${ROOT_FOLDER}/$file + fi + done + COMMIT_CHANGES="yes" + else + echo -e "Current branch is [${CURRENT_BRANCH}]" + # http://stackoverflow.com/questions/29300806/a-bash-script-to-check-if-a-string-is-present-in-a-comma-separated-list-of-strin + if [[ ",${WHITELISTED_BRANCHES_VALUE}," = *",${CURRENT_BRANCH},"* ]] ; then + mkdir -p ${ROOT_FOLDER}/${CURRENT_BRANCH} + echo -e "Branch [${CURRENT_BRANCH}] is whitelisted! Will copy the current docs to the [${CURRENT_BRANCH}] folder" + for f in docs/target/generated-docs/*; do + file=${f#docs/target/generated-docs/*} + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then + # Not ignored... + # We want users to access 1.0.0.RELEASE/ instead of 1.0.0.RELEASE/spring-cloud.sleuth.html + if [[ "${file}" == "${MAIN_ADOC_VALUE}.html" ]] ; then + # We don't want to copy the spring-cloud-sleuth.html + # we want it to be converted to index.html + cp -rf $f ${ROOT_FOLDER}/${CURRENT_BRANCH}/index.html + git add -A ${ROOT_FOLDER}/${CURRENT_BRANCH}/index.html + else + cp -rf $f ${ROOT_FOLDER}/${CURRENT_BRANCH} + git add -A ${ROOT_FOLDER}/${CURRENT_BRANCH}/$file + fi + fi + done + COMMIT_CHANGES="yes" + else + echo -e "Branch [${CURRENT_BRANCH}] is not on the white list! Check out the Maven [${WHITELIST_PROPERTY}] property in + [docs] module available under [docs] profile. Won't commit any changes to gh-pages for this branch." + fi + fi +} + +# Copies the docs by using the explicitly provided version +function copy_docs_for_provided_version() { + local FOLDER=${DESTINATION_REPO_FOLDER}/${VERSION} + mkdir -p ${FOLDER} + echo -e "Current tag is [v${VERSION}] Will copy the current docs to the [${FOLDER}] folder" + for f in ${ROOT_FOLDER}/docs/target/generated-docs/*; do + file=${f#${ROOT_FOLDER}/docs/target/generated-docs/*} + copy_docs_for_branch ${file} ${FOLDER} + done + COMMIT_CHANGES="yes" + CURRENT_BRANCH="v${VERSION}" +} + +# Copies the docs from target to the provided destination +# Params: +# $1 - file from target +# $2 - destination to which copy the files +function copy_docs_for_branch() { + local file=$1 + local destination=$2 + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^${file}$; then + # Not ignored... + # We want users to access 1.0.0.RELEASE/ instead of 1.0.0.RELEASE/spring-cloud.sleuth.html + if [[ ("${file}" == "${MAIN_ADOC_VALUE}.html") || ("${file}" == "${REPO_NAME}.html") ]] ; then + # We don't want to copy the spring-cloud-sleuth.html + # we want it to be converted to index.html + cp -rf $f ${destination}/index.html + git add -A ${destination}/index.html + else + cp -rf $f ${destination} + git add -A ${destination}/$file + fi + fi +} + +function commit_changes_if_applicable() { + if [[ "${COMMIT_CHANGES}" == "yes" ]] ; then + COMMIT_SUCCESSFUL="no" + git commit -a -m "Sync docs from ${CURRENT_BRANCH} to gh-pages" && COMMIT_SUCCESSFUL="yes" || echo "Failed to commit changes" + + # Uncomment the following push if you want to auto push to + # the gh-pages branch whenever you commit to master locally. + # This is a little extreme. Use with care! + ################################################################### + if [[ "${COMMIT_SUCCESSFUL}" == "yes" ]] ; then + git push origin gh-pages + fi + fi +} + +# Switch back to the previous branch and exit block +function checkout_previous_branch() { + # If -version was provided we need to come back to root project + cd ${ROOT_FOLDER} + git checkout ${CURRENT_BRANCH} || echo "Failed to check the branch... continuing with the script" + if [ "$dirty" != "0" ]; then git stash pop; fi + exit 0 +} + +# Assert if properties have been properly passed +function assert_properties() { +echo "VERSION [${VERSION}], DESTINATION [${DESTINATION}], CLONE [${CLONE}]" +if [[ "${VERSION}" != "" && (-z "${DESTINATION}" && -z "${CLONE}") ]] ; then echo "Version was set but destination / clone was not!"; exit 1;fi +if [[ ("${DESTINATION}" != "" && "${CLONE}" != "") && -z "${VERSION}" ]] ; then echo "Destination / clone was set but version was not!"; exit 1;fi +if [[ "${DESTINATION}" != "" && "${CLONE}" == "yes" ]] ; then echo "Destination and clone was set. Pick one!"; exit 1;fi +} + +# Prints the usage +function print_usage() { +cat </` +- if the destination switch is passed (-d) then the script will check if the provided dir is a git repo and then will + switch to gh-pages of that repo and copy the generated docs to `docs//` + +USAGE: + +You can use the following options: + +-v|--version - the script will apply the whole procedure for a particular library version +-d|--destination - the root of destination folder where the docs should be copied. You have to use the full path. + E.g. point to spring-cloud-static folder. Can't be used with (-c) +-b|--build - will run the standard build process after checking out the branch +-c|--clone - will automatically clone the spring-cloud-static repo instead of providing the destination. + Obviously can't be used with (-d) + +EOF +} + + +# ========================================== +# ____ ____ _____ _____ _____ _______ +# / ____|/ ____| __ \|_ _| __ \__ __| +# | (___ | | | |__) | | | | |__) | | | +# \___ \| | | _ / | | | ___/ | | +# ____) | |____| | \ \ _| |_| | | | +# |_____/ \_____|_| \_\_____|_| |_| +# +# ========================================== + +while [[ $# > 0 ]] +do +key="$1" +case ${key} in + -v|--version) + VERSION="$2" + shift # past argument + ;; + -d|--destination) + DESTINATION="$2" + shift # past argument + ;; + -b|--build) + BUILD="yes" + ;; + -c|--clone) + CLONE="yes" + ;; + -h|--help) + print_usage + exit 0 + ;; + *) + echo "Invalid option: [$1]" + print_usage + exit 1 + ;; +esac +shift # past argument or value +done + +assert_properties +set_default_props +check_if_anything_to_sync +if [[ -z "${VERSION}" ]] ; then + retrieve_current_branch +else + switch_to_tag +fi +build_docs_if_applicable +retrieve_doc_properties +stash_changes +add_docs_from_target +checkout_previous_branch \ No newline at end of file diff --git a/spring-cloud-vault/1.0.1.RELEASE/index.html b/spring-cloud-vault/1.0.1.RELEASE/index.html new file mode 100644 index 00000000..e3c812d0 --- /dev/null +++ b/spring-cloud-vault/1.0.1.RELEASE/index.html @@ -0,0 +1,2015 @@ + + + + + + + +Spring Cloud Vault + + + + + +
+
+
+
+

© 2016-2017 The original authors.

+
+
+ + + + + +
+
Note
+		 +Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically. +
+
+
+

Spring Cloud Vault Config provides client-side support for externalized configuration in a distributed system. With HashiCorp’s Vault you have a central place to manage external secret properties for applications across all environments. Vault can manage static and dynamic secrets such as username/password for remote applications/resources and provide credentials for external services such as MySQL, PostgreSQL, Apache Cassandra, MongoDB, Consul, AWS and more.

+
+
+
+
+

Quick Start

+
+
+

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 7 and a properly configured JAVA_HOME environment variable

    +
    • +
+
+
+

Install Vault

+
+
+
+
$ src/test/bash/install_vault.sh
+
+
+
+

Create SSL certificates for Vault

+
+
+
+
$ src/test/bash/create_certificates.sh
+
+
+
+ + + + + +
+
Note
+		 +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. +
+
+
+

Start Vault server

+
+
+
+
$ src/test/bash/local_run_vault.sh
+
+
+
+

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 +so you need to initialize it first.

+
+
+
+
$ export VAULT_ADDR="https://localhost:8200"
+$ export VAULT_SKIP_VERIFY=true # Don't do this for production
+$ vault init
+
+
+
+

You should see something like:

+
+
+
+
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.

+
+
+
+
$ vault unseal (Key 1)
+$ vault unseal (Key 2)
+$ vault unseal (Key 3)
+$ export VAULT_TOKEN=(Root token)
+
+
+
+

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

+
+
+

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:

+
+
+
Example 1. pom.xml
+
+
+
+
<parent>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-parent</artifactId>
+    <version>1.5.2.RELEASE</version>
+    <relativePath /> <!-- lookup parent from repository -->
+</parent>
+
+<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-starter-vault-config</artifactId>
+        <version>1.0.1.RELEASE</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:

+
+
+
+
+
+
@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 bootstrap.properties (like application.properties but for +the bootstrap phase of an application context), e.g.

+
+
+
Example 2. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    host: localhost
+    port: 8200
+    scheme: https
+    connection-timeout: 5000
+    read-timeout: 15000
+    config:
+        order: -10
+
+
+
+
+
+
    +
  • +

    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.

    +
    • +
  • +

    connection-timeout sets the connection timeout in milliseconds

    +
    • +
  • +

    read-timeout sets the read timeout in milliseconds

    +
    • +
  • +

    config.order sets the order for the property source

    +
    • +
+
+
+

Enabling further integrations requires additional dependencies and +configuration. Depending on how you have set up Vault you might need +additional configuration like +SSL and +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 health.vault.enabled (default true).

+
+
+

Authentication

+
+

Vault requires an authentication mechanism to authorize client requests.

+
+
+

Spring Cloud Vault supports multiple authentication mechanisms to authenticate applications with Vault.

+
+
+

For a quickstart, use the root token printed by the Vault initialization.

+
+
+
Example 3. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    token: 19aefa97-cccc-bbbb-aaaa-225940e63d76
+
+
+
+
+
+ + + + + +
+
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. +
+
+
+
+
+
+

Authentication methods

+
+
+

Different organizations have different requirements for security +and authentication. Vault reflects that need by shipping multiple authentication +methods. Spring Cloud Vault supports token and AppId authentication.

+
+
+

Token authentication

+
+

Tokens are the core method for authentication within Vault. +Token authentication requires a static token to be provided using the +Bootstrap Application Context.

+
+
+ + + + + +
+
Note
+		 +Token authentication is the default authentication method. +If a token is disclosed an unintended party gains access to Vault and +can access secrets for the intended client. +
+
+
+
Example 4. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: TOKEN
+    token: 00000000-0000-0000-0000-000000000000
+
+
+
+
+
+
    +
  • +

    authentication setting this value to TOKEN selects the Token +authentication method

    +
    • +
  • +

    token sets the static token to use

    +
    • +
+
+
+

See also: Vault Documentation: Tokens

+
+
+
+

AppId authentication

+
+

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 Cloud Vault Config 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.

+
+
+
Example 5. bootstrap.yml using SHA256 IP-Address UserId’s
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: IP_ADDRESS
+
+
+
+
+
+
    +
  • +

    authentication setting this value to APPID selects the AppId +authentication method

    +
    • +
  • +

    app-id-path sets the path of the AppId mount to use

    +
    • +
  • +

    user-id sets the UserId method. Possible values are IP_ADDRESS, +MAC_ADDRESS or a class name implementing a custom AppIdUserIdMechanism

    +
    • +
+
+
+

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

+
+
+
+
$ echo -n 192.168.99.1 | sha256sum
+
+
+
+ + + + + +
+
Note
+		 +Including the line break of echo leads to a different hash value +so make sure to include the -n flag. +
+
+
+

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).

+
+
+
Example 6. bootstrap.yml using SHA256 Mac-Address UserId’s
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: MAC_ADDRESS
+        network-interface: eth0
+
+
+
+
+
+
    +
  • +

    network-interface sets network interface to obtain the physical address

    +
    • +
+
+
+

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

+
+
+
+
$ echo -n 0AFEDE1234AC | sha256sum
+
+
+
+ + + + + +
+
Note
+		 +The Mac address is specified uppercase and without colons. +Including the line break of echo leads to a different hash value +so make sure to include the -n flag. +
+
+
+

Custom UserId

+
+

The UserId generation is an open mechanism. You can set +spring.cloud.vault.app-id.user-id to any string and the configured +value will be used as static UserId.

+
+
+

A more advanced approach lets you set spring.cloud.vault.app-id.user-id to a +classname. This class must be on your classpath and must implement +the org.springframework.cloud.vault.AppIdUserIdMechanism interface +and the createUserId method. Spring Cloud Vault will obtain the UserId +by calling createUserId each time it authenticates using AppId to +obtain a token.

+
+
+
Example 7. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: com.examlple.MyUserIdMechanism
+
+
+
+
+
+
Example 8. MyUserIdMechanism.java
+
+
+
+
public class MyUserIdMechanism implements AppIdUserIdMechanism {
+
+  @Override
+  public String createUserId() {
+    String userId = ...
+    return userId;
+  }
+}
+
+
+
+
+
+

See also: Vault Documentation: Using the App ID auth backend

+
+
+
+
+

AppRole authentication

+
+

AppRole is intended for 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 (push or pull mode).

+
+
+

RoleId and optionally SecretId must be provided by configuration, +Spring Vault will not look up these or create a custom SecretId.

+
+
+
Example 9. bootstrap.yml with AppRole authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
+
+
+
+
+
+
    +
  • +

    role-id sets the RoleId.

    +
    • +
+
+
+
Example 10. bootstrap.yml with all AppRole authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
+        secret-id: 1696536f-1976-73b1-b241-0b4213908d39
+        app-auth-path: approle
+
+
+
+
+
+
    +
  • +

    role-id sets the RoleId.

    +
    • +
  • +

    secret-id sets the SecretId. SecretId can be omitted if AppRole is configured without requiring SecretId (See bind_secret_id)

    +
    • +
  • +

    approle-path sets the path of the approle authentication mount to use

    +
    • +
+
+
+

See also: Vault Documentation: Using the AppRole auth backend

+
+
+
+

AWS-EC2 authentication

+
+

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.

+
+
+
Example 11. bootstrap.yml using AWS-EC2 Authentication
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+
+
+
+
+
+

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 Cloud 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 the +spring.cloud.vault.aws-ec2.role property.

+
+
+
Example 12. bootstrap.yml with configured role
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server
+
+
+
+
+
+
Example 13. bootstrap.yml with all AWS EC2 authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server
+        aws-ec2-path: aws-ec2
+        identity-document: http://...
+
+
+
+
+
+
    +
  • +

    authentication setting this value to AWS_EC2 selects the AWS EC2 +authentication method

    +
    • +
  • +

    role sets the role name of the AWS EC2 role definition

    +
    • +
  • +

    aws-ec2-path sets the path of the AWS EC2 mount to use

    +
    • +
  • +

    identity-document sets URL of the PKCS#7 AWS EC2 identity document

    +
    • +
+
+
+

See also: Vault Documentation: Using the aws-ec2 auth backend

+
+
+
+

TLS certificate authentication

+
+

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:

+
+
+
    +
  1. +

    Use SSL, see Vault Client SSL configuration

    +
    2. +
  2. +

    Configure a Java Keystore that contains the client +certificate and the private key

    +
    3. +
  3. +

    Set the spring.cloud.vault.authentication to CERT

    +
    4. +
+
+
+
Example 14. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: CERT
+    ssl:
+        key-store: classpath:keystore.jks
+        key-store-password: changeit
+        cert-auth-path: cert
+
+
+
+
+
+

See also: Vault Documentation: Using the Cert auth backend

+
+
+
+

Cubbyhole authentication

+
+

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 will be retrieved from a wrapped +response stored at /cubbyhole/response.

+
+
+

Creating a wrapped token

+
+
+ + + + + +
+
Note
+		 +Response Wrapping for token creation requires Vault 0.6.0 or higher. +
+
+
+
Example 15. Crating and storing tokens
+
+
+
+
$ vault token-create -wrap-ttl="10m"
+Key                            Value
+---                            -----
+wrapping_token:                397ccb93-ff6c-b17b-9389-380b01ca2645
+wrapping_token_ttl:            0h10m0s
+wrapping_token_creation_time:  2016-09-18 20:29:48.652957077 +0200 CEST
+wrapped_accessor:              46b6aebb-187f-932a-26d7-4f3d86a68319
+
+
+
+
+
+
Example 16. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: CUBBYHOLE
+    token: 397ccb93-ff6c-b17b-9389-380b01ca2645
+
+
+
+
+
+

See also:

+
+
+ +
+
+
+
+
+

Secret Backends

+
+
+

Generic Backend

+
+

Spring Cloud Vault supports at the basic level the generic secret +backend. The generic secret backend allows storage of arbitrary +values as key-value store. A single context can store one or many +key-value tuples. Contexts can be organized hierarchically. +Spring Cloud Vault allows using the Application name +and a default context name (application) in combination with active +profiles.

+
+
+
+
/secret/{application}/{profile}
+/secret/{application}
+/secret/{default-context}/{profile}
+/secret/{default-context}
+
+
+
+

The application name is determined by the properties:

+
+
+
    +
  • +

    spring.cloud.vault.generic.application-name

    +
    • +
  • +

    spring.cloud.vault.application-name

    +
    • +
  • +

    spring.application.name

    +
    • +
+
+
+

Secrets can be obtained from other folders within the generic backend by adding their +paths to the application name, separated by commas. For example, given the application +name usefulapp,mysql1,projectx/aws, each of these folders will be used:

+
+
+
    +
  • +

    /secret/usefulapp

    +
    • +
  • +

    /secret/mysql1

    +
    • +
  • +

    /secret/projectx/aws

    +
    • +
+
+
+

Spring Cloud Vault adds all active profiles to the list of possible context paths. +No active profiles will skip accessing contexts with a profile name.

+
+
+

Properties are exposed like they are stored (i.e. without additional prefixes).

+
+
+
+
+
+
spring.cloud.vault:
+    generic:
+        enabled: true
+        backend: secret
+        profile-separator: '/'
+        default-context: application
+        application-name: my-app
+
+
+
+
+
+
    +
  • +

    enabled setting this value to false disables the secret backend +config usage

    +
    • +
  • +

    backend sets the path of the secret mount to use

    +
    • +
  • +

    default-context sets the context name used by all applications

    +
    • +
  • +

    application-name overrides the application name for use in the generic backend

    +
    • +
  • +

    profile-separator separates the profile name from the context in +property sources with profiles

    +
    • +
+
+
+

See also: Vault Documentation: Using the generic secret backend

+
+
+
+

Consul

+
+

Spring Cloud Vault can obtain credentials for HashiCorp Consul. +The Consul integration requires the spring-cloud-vault-config-consul +dependency.

+
+
+
Example 17. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-consul</artifactId>
+        <version>1.0.1.RELEASE</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.consul.enabled=true (default false) and +providing the role name with spring.cloud.vault.consul.role=….

+
+
+

The obtained token is stored in spring.cloud.consul.token +so using Spring Cloud Consul can pick up the generated +credentials without further configuration. You can configure +the property name by setting spring.cloud.vault.consul.token-property.

+
+
+
+
+
+
spring.cloud.vault:
+    consul:
+        enabled: true
+        role: readonly
+        backend: consul
+        token-property: spring.cloud.consul.token
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the Consul backend config usage

    +
    • +
  • +

    role sets the role name of the Consul role definition

    +
    • +
  • +

    backend sets the path of the Consul mount to use

    +
    • +
  • +

    token-property sets the property name in which the Consul ACL token is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up Consul with Vault

+
+
+
+

RabbitMQ

+
+

Spring Cloud Vault can obtain credentials for RabbitMQ.

+
+
+

The RabbitMQ integration requires the spring-cloud-vault-config-rabbitmq +dependency.

+
+
+
Example 18. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-rabbitmq</artifactId>
+        <version>1.0.1.RELEASE</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.rabbitmq.enabled=true (default false) +and providing the role name with spring.cloud.vault.rabbitmq.role=….

+
+
+

Username and password are stored in spring.rabbitmq.username +and spring.rabbitmq.password so using Spring Boot will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.rabbitmq.username-property and +spring.cloud.vault.rabbitmq.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    rabbitmq:
+        enabled: true
+        role: readonly
+        backend: rabbitmq
+        username-property: spring.rabbitmq.username
+        password-property: spring.rabbitmq.password
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the RabbitMQ backend config usage

    +
    • +
  • +

    role sets the role name of the RabbitMQ role definition

    +
    • +
  • +

    backend sets the path of the RabbitMQ mount to use

    +
    • +
  • +

    username-property sets the property name in which the RabbitMQ username is stored

    +
    • +
  • +

    password-property sets the property name in which the RabbitMQ password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up RabbitMQ with Vault

+
+
+
+

AWS

+
+

Spring Cloud Vault can obtain credentials for AWS.

+
+
+

The AWS integration requires the spring-cloud-vault-config-aws +dependency.

+
+
+
Example 19. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-aws</artifactId>
+        <version>1.0.1.RELEASE</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.aws=true (default false) +and providing the role name with spring.cloud.vault.aws.role=….

+
+
+

The access key and secret key are stored in cloud.aws.credentials.accessKey +and cloud.aws.credentials.secretKey so using Spring Cloud AWS will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.aws.access-key-property and +spring.cloud.vault.aws.secret-key-property.

+
+
+
+
+
+
spring.cloud.vault:
+    aws:
+        enabled: true
+        role: readonly
+        backend: aws
+        access-key-property: cloud.aws.credentials.accessKey
+        secret-key-property: cloud.aws.credentials.secretKey
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the AWS backend config usage

    +
    • +
  • +

    role sets the role name of the AWS role definition

    +
    • +
  • +

    backend sets the path of the AWS mount to use

    +
    • +
  • +

    access-key-property sets the property name in which the AWS access key is stored

    +
    • +
  • +

    secret-key-property sets the property name in which the AWS secret key is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up AWS with Vault

+
+
+
+
+
+

Database backends

+
+
+

Vault supports several database secret backends to generate database +credentials dynamically based on configured roles. This means +services that need to access a database no longer need to configure +credentials: they can request them from Vault, and use Vault’s leasing +mechanism to more easily roll keys.

+
+
+

Spring Cloud Vault integrates with these backends:

+
+
+ +
+
+

Using a database secret backend requires to enable the +backend in the configuration and the spring-cloud-vault-config-databases +dependency.

+
+
+
Example 20. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-databases</artifactId>
+        <version>1.0.1.RELEASE</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+ + + + + +
+
Note
+		 +Enabling multiple JDBC-compliant databases will generate credentials +and store them by default in the same property keys hence property names for +JDBC secrets need to be configured separately. +
+
+
+

Apache Cassandra

+
+

Spring Cloud Vault can obtain credentials for Apache Cassandra. +The integration can be enabled by setting +spring.cloud.vault.cassandra.enabled=true (default false) and +providing the role name with spring.cloud.vault.cassandra.role=….

+
+
+

Username and password are stored in spring.data.cassandra.username +and spring.data.cassandra.password so using Spring Boot will pick +up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.cassandra.username-property and +spring.cloud.vault.cassandra.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    cassandra:
+        enabled: true
+        role: readonly
+        backend: cassandra
+        username-property: spring.data.cassandra.username
+        password-property: spring.data.cassandra.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the Cassandra backend config usage

    +
    • +
  • +

    role sets the role name of the Cassandra role definition

    +
    • +
  • +

    backend sets the path of the Cassandra mount to use

    +
    • +
  • +

    username-property sets the property name in which the Cassandra username is stored

    +
    • +
  • +

    password-property sets the property name in which the Cassandra password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up Apache Cassandra with Vault

+
+
+
+

MongoDB

+
+

Spring Cloud Vault can obtain credentials for MongoDB. +The integration can be enabled by setting +spring.cloud.vault.mongodb.enabled=true (default false) and +providing the role name with spring.cloud.vault.mongodb.role=….

+
+
+

Username and password are stored in spring.data.mongodb.username +and spring.data.mongodb.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mongodb.username-property and +spring.cloud.vault.mongodb.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    mongodb:
+        enabled: true
+        role: readonly
+        backend: mongodb
+        username-property: spring.data.mongodb.username
+        password-property: spring.data.mongodb.password
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the MongodB backend config usage

    +
    • +
  • +

    role sets the role name of the MongoDB role definition

    +
    • +
  • +

    backend sets the path of the MongoDB mount to use

    +
    • +
  • +

    username-property sets the property name in which the MongoDB username is stored

    +
    • +
  • +

    password-property sets the property name in which the MongoDB password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up MongoDB with Vault

+
+
+
+

MySQL

+
+

Spring Cloud Vault can obtain credentials for MySQL. +The integration can be enabled by setting +spring.cloud.vault.mysql.enabled=true (default false) and +providing the role name with spring.cloud.vault.mysql.role=….

+
+
+

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mysql.username-property and +spring.cloud.vault.mysql.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    mysql:
+        enabled: true
+        role: readonly
+        backend: mysql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the MySQL backend config usage

    +
    • +
  • +

    role sets the role name of the MySQL role definition

    +
    • +
  • +

    backend sets the path of the MySQL mount to use

    +
    • +
  • +

    username-property sets the property name in which the MySQL username is stored

    +
    • +
  • +

    password-property sets the property name in which the MySQL password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up MySQL with Vault

+
+
+
+

PostgreSQL

+
+

Spring Cloud Vault can obtain credentials for PostgreSQL. +The integration can be enabled by setting +spring.cloud.vault.postgresql.enabled=true (default false) and +providing the role name with spring.cloud.vault.postgresql.role=….

+
+
+

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.postgresql.username-property and +spring.cloud.vault.postgresql.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    postgresql:
+        enabled: true
+        role: readonly
+        backend: postgresql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the PostgreSQL backend config usage

    +
    • +
  • +

    role sets the role name of the PostgreSQL role definition

    +
    • +
  • +

    backend sets the path of the PostgreSQL mount to use

    +
    • +
  • +

    username-property sets the property name in which the PostgreSQL username is stored

    +
    • +
  • +

    password-property sets the property name in which the PostgreSQL password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up PostgreSQL with Vault

+
+
+
+
+
+

Vault Client Fail Fast

+
+
+

In some cases, it may be desirable to fail startup of a service if +it cannot connect to the Vault Server. If this is the desired +behavior, set the bootstrap configuration property +spring.cloud.vault.fail-fast=true and the client will halt with +an Exception.

+
+
+
+
+
+
spring.cloud.vault:
+    fail-fast: true
+
+
+
+
+
+
+
+

Vault Client SSL configuration

+
+
+

SSL can be configured declaratively by setting various properties. +You can set either javax.net.ssl.trustStore to configure +JVM-wide SSL settings or spring.cloud.vault.ssl.trust-store +to set SSL settings only for Spring Cloud Vault Config.

+
+
+
+
+
+
spring.cloud.vault:
+    ssl:
+        trust-store: classpath:keystore.jks
+        trust-store-password: changeit
+
+
+
+
+
+
    +
  • +

    trust-store sets the resource for the trust-store. SSL-secured Vault +communication will validate the Vault SSL certificate with the specified +trust-store.

    +
    • +
  • +

    trust-store-password sets the trust-store password

    +
    • +
+
+
+

Please note that configuring spring.cloud.vault.ssl.* can be only +applied when either Apache Http Components or the OkHttp client +is on your class-path.

+
+
+
+
+

Lease lifecycle management (renewal and revocation)

+
+
+

With every secret, Vault creates a lease: +metadata containing information such as a time duration, +renewability, and more.

+
+
+

Vault promises that the data will be valid for the given duration, +or Time To Live (TTL). Once the lease is expired, Vault can +revoke the data, and the consumer of the secret can no longer +be certain that it is valid.

+
+
+

Spring Cloud Vault maintains a lease lifecycle beyond +the creation of login tokens and secrets. That said, +login tokens and secrets associated with a lease +are scheduled for renewal just before the lease expires +until terminal expiry. +Application shutdown revokes obtained login tokens and renewable +leases.

+
+
+

Secret service and database backends (such as MongoDB or MySQL) +usually generate a renewable lease so generated credentials will +be disabled on application shutdown.

+
+
+ + + + + +
+
Note
+		 +Static tokens are not renewed or revoked. +
+
+
+

Lease renewal and revocation is enabled by default and can +be disabled by setting spring.cloud.vault.config.lifecycle.enabled +to false. This is not recommended as leases can expire and +Spring Cloud Vault cannot longer access Vault or services +using generated credentials and valid credentials remain active +after application shutdown.

+
+
+
+
+
+
spring.cloud.vault:
+    config.lifecycle.enabled: true
+
+
+
+
+
+

See also: Vault Documentation: Lease, Renew, and Revoke

+
+
+
+
+ + \ No newline at end of file diff --git a/spring-cloud-vault/1.0.2.RELEASE/ghpages.sh b/spring-cloud-vault/1.0.2.RELEASE/ghpages.sh new file mode 100644 index 00000000..57c5da3a --- /dev/null +++ b/spring-cloud-vault/1.0.2.RELEASE/ghpages.sh @@ -0,0 +1,330 @@ +#!/bin/bash -x + +set -e + +# Set default props like MAVEN_PATH, ROOT_FOLDER etc. +function set_default_props() { + # The script should be executed from the root folder + ROOT_FOLDER=`pwd` + echo "Current folder is ${ROOT_FOLDER}" + + if [[ ! -e "${ROOT_FOLDER}/.git" ]]; then + echo "You're not in the root folder of the project!" + exit 1 + fi + + # Prop that will let commit the changes + COMMIT_CHANGES="no" + MAVEN_PATH=${MAVEN_PATH:-} + echo "Path to Maven is [${MAVEN_PATH}]" + REPO_NAME=${PWD##*/} + echo "Repo name is [${REPO_NAME}]" + SPRING_CLOUD_STATIC_REPO=${SPRING_CLOUD_STATIC_REPO:-git@github.com:spring-cloud/spring-cloud-static.git} + echo "Spring Cloud Static repo is [${SPRING_CLOUD_STATIC_REPO}" +} + +# Check if gh-pages exists and docs have been built +function check_if_anything_to_sync() { + git remote set-url --push origin `git config remote.origin.url | sed -e 's/^git:/https:/'` + + if ! (git remote set-branches --add origin gh-pages && git fetch -q); then + echo "No gh-pages, so not syncing" + exit 0 + fi + + if ! [ -d docs/target/generated-docs ] && ! [ "${BUILD}" == "yes" ]; then + echo "No gh-pages sources in docs/target/generated-docs, so not syncing" + exit 0 + fi +} + +function retrieve_current_branch() { + # Code getting the name of the current branch. For master we want to publish as we did until now + # http://stackoverflow.com/questions/1593051/how-to-programmatically-determine-the-current-checked-out-git-branch + # If there is a branch already passed will reuse it - otherwise will try to find it + CURRENT_BRANCH=${BRANCH} + if [[ -z "${CURRENT_BRANCH}" ]] ; then + CURRENT_BRANCH=$(git symbolic-ref -q HEAD) + CURRENT_BRANCH=${CURRENT_BRANCH##refs/heads/} + CURRENT_BRANCH=${CURRENT_BRANCH:-HEAD} + fi + echo "Current branch is [${CURRENT_BRANCH}]" + git checkout ${CURRENT_BRANCH} || echo "Failed to check the branch... continuing with the script" +} + +# Switches to the provided value of the release version. We always prefix it with `v` +function switch_to_tag() { + git checkout v${VERSION} +} + +# Build the docs if switch is on +function build_docs_if_applicable() { + if [[ "${BUILD}" == "yes" ]] ; then + ./mvnw clean install -P docs -pl docs -DskipTests + fi +} + +# Get the name of the `docs.main` property +# Get whitelisted branches - assumes that a `docs` module is available under `docs` profile +function retrieve_doc_properties() { + MAIN_ADOC_VALUE=$("${MAVEN_PATH}"mvn -q \ + -Dexec.executable="echo" \ + -Dexec.args='${docs.main}' \ + --non-recursive \ + org.codehaus.mojo:exec-maven-plugin:1.3.1:exec) + echo "Extracted 'main.adoc' from Maven build [${MAIN_ADOC_VALUE}]" + + + WHITELIST_PROPERTY=${WHITELIST_PROPERTY:-"docs.whitelisted.branches"} + WHITELISTED_BRANCHES_VALUE=$("${MAVEN_PATH}"mvn -q \ + -Dexec.executable="echo" \ + -Dexec.args="\${${WHITELIST_PROPERTY}}" \ + org.codehaus.mojo:exec-maven-plugin:1.3.1:exec \ + -P docs \ + -pl docs) + echo "Extracted '${WHITELIST_PROPERTY}' from Maven build [${WHITELISTED_BRANCHES_VALUE}]" +} + +# Stash any outstanding changes +function stash_changes() { + git diff-index --quiet HEAD && dirty=$? || (echo "Failed to check if the current repo is dirty. Assuming that it is." && dirty="1") + if [ "$dirty" != "0" ]; then git stash; fi +} + +# Switch to gh-pages branch to sync it with current branch +function add_docs_from_target() { + local DESTINATION_REPO_FOLDER + if [[ -z "${DESTINATION}" && -z "${CLONE}" ]] ; then + DESTINATION_REPO_FOLDER=${ROOT_FOLDER} + elif [[ "${CLONE}" == "yes" ]]; then + mkdir -p ${ROOT_FOLDER}/target + local clonedStatic=${ROOT_FOLDER}/target/spring-cloud-static + if [[ ! -e "${clonedStatic}/.git" ]]; then + echo "Cloning Spring Cloud Static to target" + git clone ${SPRING_CLOUD_STATIC_REPO} ${clonedStatic} && git checkout gh-pages + else + echo "Spring Cloud Static already cloned - will pull changes" + cd ${clonedStatic} && git checkout gh-pages && git pull origin gh-pages + fi + DESTINATION_REPO_FOLDER=${clonedStatic}/${REPO_NAME} + mkdir -p ${DESTINATION_REPO_FOLDER} + else + if [[ ! -e "${DESTINATION}/.git" ]]; then + echo "[${DESTINATION}] is not a git repository" + exit 1 + fi + DESTINATION_REPO_FOLDER=${DESTINATION}/${REPO_NAME} + mkdir -p ${DESTINATION_REPO_FOLDER} + echo "Destination was provided [${DESTINATION}]" + fi + cd ${DESTINATION_REPO_FOLDER} + git checkout gh-pages + git pull origin gh-pages + + # Add git branches + ################################################################### + if [[ -z "${VERSION}" ]] ; then + copy_docs_for_current_version + else + copy_docs_for_provided_version + fi + commit_changes_if_applicable +} + + +# Copies the docs by using the retrieved properties from Maven build +function copy_docs_for_current_version() { + if [[ "${CURRENT_BRANCH}" == "master" ]] ; then + echo -e "Current branch is master - will copy the current docs only to the root folder" + for f in docs/target/generated-docs/*; do + file=${f#docs/target/generated-docs/*} + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then + # Not ignored... + cp -rf $f ${ROOT_FOLDER}/ + git add -A ${ROOT_FOLDER}/$file + fi + done + COMMIT_CHANGES="yes" + else + echo -e "Current branch is [${CURRENT_BRANCH}]" + # http://stackoverflow.com/questions/29300806/a-bash-script-to-check-if-a-string-is-present-in-a-comma-separated-list-of-strin + if [[ ",${WHITELISTED_BRANCHES_VALUE}," = *",${CURRENT_BRANCH},"* ]] ; then + mkdir -p ${ROOT_FOLDER}/${CURRENT_BRANCH} + echo -e "Branch [${CURRENT_BRANCH}] is whitelisted! Will copy the current docs to the [${CURRENT_BRANCH}] folder" + for f in docs/target/generated-docs/*; do + file=${f#docs/target/generated-docs/*} + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then + # Not ignored... + # We want users to access 1.0.0.RELEASE/ instead of 1.0.0.RELEASE/spring-cloud.sleuth.html + if [[ "${file}" == "${MAIN_ADOC_VALUE}.html" ]] ; then + # We don't want to copy the spring-cloud-sleuth.html + # we want it to be converted to index.html + cp -rf $f ${ROOT_FOLDER}/${CURRENT_BRANCH}/index.html + git add -A ${ROOT_FOLDER}/${CURRENT_BRANCH}/index.html + else + cp -rf $f ${ROOT_FOLDER}/${CURRENT_BRANCH} + git add -A ${ROOT_FOLDER}/${CURRENT_BRANCH}/$file + fi + fi + done + COMMIT_CHANGES="yes" + else + echo -e "Branch [${CURRENT_BRANCH}] is not on the white list! Check out the Maven [${WHITELIST_PROPERTY}] property in + [docs] module available under [docs] profile. Won't commit any changes to gh-pages for this branch." + fi + fi +} + +# Copies the docs by using the explicitly provided version +function copy_docs_for_provided_version() { + local FOLDER=${DESTINATION_REPO_FOLDER}/${VERSION} + mkdir -p ${FOLDER} + echo -e "Current tag is [v${VERSION}] Will copy the current docs to the [${FOLDER}] folder" + for f in ${ROOT_FOLDER}/docs/target/generated-docs/*; do + file=${f#${ROOT_FOLDER}/docs/target/generated-docs/*} + copy_docs_for_branch ${file} ${FOLDER} + done + COMMIT_CHANGES="yes" + CURRENT_BRANCH="v${VERSION}" +} + +# Copies the docs from target to the provided destination +# Params: +# $1 - file from target +# $2 - destination to which copy the files +function copy_docs_for_branch() { + local file=$1 + local destination=$2 + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^${file}$; then + # Not ignored... + # We want users to access 1.0.0.RELEASE/ instead of 1.0.0.RELEASE/spring-cloud.sleuth.html + if [[ ("${file}" == "${MAIN_ADOC_VALUE}.html") || ("${file}" == "${REPO_NAME}.html") ]] ; then + # We don't want to copy the spring-cloud-sleuth.html + # we want it to be converted to index.html + cp -rf $f ${destination}/index.html + git add -A ${destination}/index.html + else + cp -rf $f ${destination} + git add -A ${destination}/$file + fi + fi +} + +function commit_changes_if_applicable() { + if [[ "${COMMIT_CHANGES}" == "yes" ]] ; then + COMMIT_SUCCESSFUL="no" + git commit -a -m "Sync docs from ${CURRENT_BRANCH} to gh-pages" && COMMIT_SUCCESSFUL="yes" || echo "Failed to commit changes" + + # Uncomment the following push if you want to auto push to + # the gh-pages branch whenever you commit to master locally. + # This is a little extreme. Use with care! + ################################################################### + if [[ "${COMMIT_SUCCESSFUL}" == "yes" ]] ; then + git push origin gh-pages + fi + fi +} + +# Switch back to the previous branch and exit block +function checkout_previous_branch() { + # If -version was provided we need to come back to root project + cd ${ROOT_FOLDER} + git checkout ${CURRENT_BRANCH} || echo "Failed to check the branch... continuing with the script" + if [ "$dirty" != "0" ]; then git stash pop; fi + exit 0 +} + +# Assert if properties have been properly passed +function assert_properties() { +echo "VERSION [${VERSION}], DESTINATION [${DESTINATION}], CLONE [${CLONE}]" +if [[ "${VERSION}" != "" && (-z "${DESTINATION}" && -z "${CLONE}") ]] ; then echo "Version was set but destination / clone was not!"; exit 1;fi +if [[ ("${DESTINATION}" != "" && "${CLONE}" != "") && -z "${VERSION}" ]] ; then echo "Destination / clone was set but version was not!"; exit 1;fi +if [[ "${DESTINATION}" != "" && "${CLONE}" == "yes" ]] ; then echo "Destination and clone was set. Pick one!"; exit 1;fi +} + +# Prints the usage +function print_usage() { +cat </` +- if the destination switch is passed (-d) then the script will check if the provided dir is a git repo and then will + switch to gh-pages of that repo and copy the generated docs to `docs//` + +USAGE: + +You can use the following options: + +-v|--version - the script will apply the whole procedure for a particular library version +-d|--destination - the root of destination folder where the docs should be copied. You have to use the full path. + E.g. point to spring-cloud-static folder. Can't be used with (-c) +-b|--build - will run the standard build process after checking out the branch +-c|--clone - will automatically clone the spring-cloud-static repo instead of providing the destination. + Obviously can't be used with (-d) + +EOF +} + + +# ========================================== +# ____ ____ _____ _____ _____ _______ +# / ____|/ ____| __ \|_ _| __ \__ __| +# | (___ | | | |__) | | | | |__) | | | +# \___ \| | | _ / | | | ___/ | | +# ____) | |____| | \ \ _| |_| | | | +# |_____/ \_____|_| \_\_____|_| |_| +# +# ========================================== + +while [[ $# > 0 ]] +do +key="$1" +case ${key} in + -v|--version) + VERSION="$2" + shift # past argument + ;; + -d|--destination) + DESTINATION="$2" + shift # past argument + ;; + -b|--build) + BUILD="yes" + ;; + -c|--clone) + CLONE="yes" + ;; + -h|--help) + print_usage + exit 0 + ;; + *) + echo "Invalid option: [$1]" + print_usage + exit 1 + ;; +esac +shift # past argument or value +done + +assert_properties +set_default_props +check_if_anything_to_sync +if [[ -z "${VERSION}" ]] ; then + retrieve_current_branch +else + switch_to_tag +fi +build_docs_if_applicable +retrieve_doc_properties +stash_changes +add_docs_from_target +checkout_previous_branch \ No newline at end of file diff --git a/spring-cloud-vault/1.0.2.RELEASE/index.html b/spring-cloud-vault/1.0.2.RELEASE/index.html new file mode 100644 index 00000000..5bd66d91 --- /dev/null +++ b/spring-cloud-vault/1.0.2.RELEASE/index.html @@ -0,0 +1,2035 @@ + + + + + + + +Spring Cloud Vault + + + + + +
+
+
+
+

© 2016-2017 The original authors.

+
+
+ + + + + +
+
Note
+		 +Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically. +
+
+
+

Spring Cloud Vault Config provides client-side support for externalized configuration in a distributed system. With HashiCorp’s Vault you have a central place to manage external secret properties for applications across all environments. Vault can manage static and dynamic secrets such as username/password for remote applications/resources and provide credentials for external services such as MySQL, PostgreSQL, Apache Cassandra, MongoDB, Consul, AWS and more.

+
+
+
+
+

Quick Start

+
+
+

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 7 and a properly configured JAVA_HOME environment variable

    +
    • +
+
+
+

Install Vault

+
+
+
+
$ src/test/bash/install_vault.sh
+
+
+
+

Create SSL certificates for Vault

+
+
+
+
$ src/test/bash/create_certificates.sh
+
+
+
+ + + + + +
+
Note
+		 +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. +
+
+
+

Start Vault server

+
+
+
+
$ src/test/bash/local_run_vault.sh
+
+
+
+

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.

+
+
+
+
$ export VAULT_ADDR="https://localhost:8200"
+$ export VAULT_SKIP_VERIFY=true # Don't do this for production
+$ vault init
+
+
+
+

You should see something like:

+
+
+
+
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.

+
+
+
+
$ vault unseal (Key 1)
+$ vault unseal (Key 2)
+$ vault 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

+
+
+

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:

+
+
+
Example 1. pom.xml
+
+
+
+
<parent>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-parent</artifactId>
+    <version>1.5.4.RELEASE</version>
+    <relativePath /> <!-- lookup parent from repository -->
+</parent>
+
+<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-starter-vault-config</artifactId>
+        <version>1.0.2.RELEASE</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:

+
+
+
+
+
+
@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 bootstrap.properties (like application.properties but for +the bootstrap phase of an application context), e.g.

+
+
+
Example 2. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    host: localhost
+    port: 8200
+    scheme: https
+    connection-timeout: 5000
+    read-timeout: 15000
+    config:
+        order: -10
+
+
+
+
+
+
    +
  • +

    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.

    +
    • +
  • +

    connection-timeout sets the connection timeout in milliseconds

    +
    • +
  • +

    read-timeout sets the read timeout in milliseconds

    +
    • +
  • +

    config.order sets the order for the property source

    +
    • +
+
+
+

Enabling further integrations requires additional dependencies and +configuration. Depending on how you have set up Vault you might need +additional configuration like +SSL and +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 health.vault.enabled (default true).

+
+
+

Authentication

+
+

Vault requires an authentication mechanism to authorize client requests.

+
+
+

Spring Cloud Vault supports multiple authentication mechanisms to authenticate applications with Vault.

+
+
+

For a quickstart, use the root token printed by the Vault initialization.

+
+
+
Example 3. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    token: 19aefa97-cccc-bbbb-aaaa-225940e63d76
+
+
+
+
+
+ + + + + +
+
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. +
+
+
+
+
+
+

Authentication methods

+
+
+

Different organizations have different requirements for security +and authentication. Vault reflects that need by shipping multiple authentication +methods. Spring Cloud Vault supports token and AppId authentication.

+
+
+

Token authentication

+
+

Tokens are the core method for authentication within Vault. +Token authentication requires a static token to be provided using the +Bootstrap Application Context.

+
+
+ + + + + +
+
Note
+		 +Token authentication is the default authentication method. +If a token is disclosed an unintended party gains access to Vault and +can access secrets for the intended client. +
+
+
+
Example 4. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: TOKEN
+    token: 00000000-0000-0000-0000-000000000000
+
+
+
+
+
+
    +
  • +

    authentication setting this value to TOKEN selects the Token +authentication method

    +
    • +
  • +

    token sets the static token to use

    +
    • +
+
+
+

See also: Vault Documentation: Tokens

+
+
+
+

AppId authentication

+
+

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 Cloud Vault Config 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.

+
+
+
Example 5. bootstrap.yml using SHA256 IP-Address UserId’s
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: IP_ADDRESS
+
+
+
+
+
+
    +
  • +

    authentication setting this value to APPID selects the AppId +authentication method

    +
    • +
  • +

    app-id-path sets the path of the AppId mount to use

    +
    • +
  • +

    user-id sets the UserId method. Possible values are IP_ADDRESS, +MAC_ADDRESS or a class name implementing a custom AppIdUserIdMechanism

    +
    • +
+
+
+

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

+
+
+
+
$ echo -n 192.168.99.1 | sha256sum
+
+
+
+ + + + + +
+
Note
+		 +Including the line break of echo leads to a different hash value +so make sure to include the -n flag. +
+
+
+

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).

+
+
+
Example 6. bootstrap.yml using SHA256 Mac-Address UserId’s
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: MAC_ADDRESS
+        network-interface: eth0
+
+
+
+
+
+
    +
  • +

    network-interface sets network interface to obtain the physical address

    +
    • +
+
+
+

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

+
+
+
+
$ echo -n 0AFEDE1234AC | sha256sum
+
+
+
+ + + + + +
+
Note
+		 +The Mac address is specified uppercase and without colons. +Including the line break of echo leads to a different hash value +so make sure to include the -n flag. +
+
+
+

Custom UserId

+
+

The UserId generation is an open mechanism. You can set +spring.cloud.vault.app-id.user-id to any string and the configured +value will be used as static UserId.

+
+
+

A more advanced approach lets you set spring.cloud.vault.app-id.user-id to a +classname. This class must be on your classpath and must implement +the org.springframework.cloud.vault.AppIdUserIdMechanism interface +and the createUserId method. Spring Cloud Vault will obtain the UserId +by calling createUserId each time it authenticates using AppId to +obtain a token.

+
+
+
Example 7. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: com.examlple.MyUserIdMechanism
+
+
+
+
+
+
Example 8. MyUserIdMechanism.java
+
+
+
+
public class MyUserIdMechanism implements AppIdUserIdMechanism {
+
+  @Override
+  public String createUserId() {
+    String userId = ...
+    return userId;
+  }
+}
+
+
+
+
+
+

See also: Vault Documentation: Using the App ID auth backend

+
+
+
+
+

AppRole authentication

+
+

AppRole is intended for 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 (push or pull mode).

+
+
+

RoleId and optionally SecretId must be provided by configuration, +Spring Vault will not look up these or create a custom SecretId.

+
+
+
Example 9. bootstrap.yml with AppRole authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
+
+
+
+
+
+
    +
  • +

    role-id sets the RoleId.

    +
    • +
+
+
+
Example 10. bootstrap.yml with all AppRole authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
+        secret-id: 1696536f-1976-73b1-b241-0b4213908d39
+        app-auth-path: approle
+
+
+
+
+
+
    +
  • +

    role-id sets the RoleId.

    +
    • +
  • +

    secret-id sets the SecretId. SecretId can be omitted if AppRole is configured without requiring SecretId (See bind_secret_id)

    +
    • +
  • +

    approle-path sets the path of the approle authentication mount to use

    +
    • +
+
+
+

See also: Vault Documentation: Using the AppRole auth backend

+
+
+
+

AWS-EC2 authentication

+
+

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.

+
+
+
Example 11. bootstrap.yml using AWS-EC2 Authentication
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+
+
+
+
+
+

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 Cloud 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 the +spring.cloud.vault.aws-ec2.role property.

+
+
+
Example 12. bootstrap.yml with configured role
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server
+
+
+
+
+
+
Example 13. bootstrap.yml with all AWS EC2 authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server
+        aws-ec2-path: aws-ec2
+        identity-document: http://...
+
+
+
+
+
+
    +
  • +

    authentication setting this value to AWS_EC2 selects the AWS EC2 +authentication method

    +
    • +
  • +

    role sets the role name of the AWS EC2 role definition

    +
    • +
  • +

    aws-ec2-path sets the path of the AWS EC2 mount to use

    +
    • +
  • +

    identity-document sets URL of the PKCS#7 AWS EC2 identity document

    +
    • +
+
+
+

See also: Vault Documentation: Using the aws-ec2 auth backend

+
+
+
+

TLS certificate authentication

+
+

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:

+
+
+
    +
  1. +

    Use SSL, see Vault Client SSL configuration

    +
    2. +
  2. +

    Configure a Java Keystore that contains the client +certificate and the private key

    +
    3. +
  3. +

    Set the spring.cloud.vault.authentication to CERT

    +
    4. +
+
+
+
Example 14. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: CERT
+    ssl:
+        key-store: classpath:keystore.jks
+        key-store-password: changeit
+        cert-auth-path: cert
+
+
+
+
+
+

See also: Vault Documentation: Using the Cert auth backend

+
+
+
+

Cubbyhole authentication

+
+

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 will be retrieved from a wrapped +response stored at /cubbyhole/response.

+
+
+

Creating a wrapped token

+
+
+ + + + + +
+
Note
+		 +Response Wrapping for token creation requires Vault 0.6.0 or higher. +
+
+
+
Example 15. Crating and storing tokens
+
+
+
+
$ vault token-create -wrap-ttl="10m"
+Key                            Value
+---                            -----
+wrapping_token:                397ccb93-ff6c-b17b-9389-380b01ca2645
+wrapping_token_ttl:            0h10m0s
+wrapping_token_creation_time:  2016-09-18 20:29:48.652957077 +0200 CEST
+wrapped_accessor:              46b6aebb-187f-932a-26d7-4f3d86a68319
+
+
+
+
+
+
Example 16. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: CUBBYHOLE
+    token: 397ccb93-ff6c-b17b-9389-380b01ca2645
+
+
+
+
+
+

See also:

+
+
+ +
+
+
+
+
+

Secret Backends

+
+
+

Generic Backend

+
+

Spring Cloud Vault supports at the basic level the generic secret +backend. The generic secret backend allows storage of arbitrary +values as key-value store. A single context can store one or many +key-value tuples. Contexts can be organized hierarchically. +Spring Cloud Vault allows using the Application name +and a default context name (application) in combination with active +profiles.

+
+
+
+
/secret/{application}/{profile}
+/secret/{application}
+/secret/{default-context}/{profile}
+/secret/{default-context}
+
+
+
+

The application name is determined by the properties:

+
+
+
    +
  • +

    spring.cloud.vault.generic.application-name

    +
    • +
  • +

    spring.cloud.vault.application-name

    +
    • +
  • +

    spring.application.name

    +
    • +
+
+
+

Secrets can be obtained from other folders within the generic backend by adding their +paths to the application name, separated by commas. For example, given the application +name usefulapp,mysql1,projectx/aws, each of these folders will be used:

+
+
+
    +
  • +

    /secret/usefulapp

    +
    • +
  • +

    /secret/mysql1

    +
    • +
  • +

    /secret/projectx/aws

    +
    • +
+
+
+

Spring Cloud Vault adds all active profiles to the list of possible context paths. +No active profiles will skip accessing contexts with a profile name.

+
+
+

Properties are exposed like they are stored (i.e. without additional prefixes).

+
+
+
+
+
+
spring.cloud.vault:
+    generic:
+        enabled: true
+        backend: secret
+        profile-separator: '/'
+        default-context: application
+        application-name: my-app
+
+
+
+
+
+
    +
  • +

    enabled setting this value to false disables the secret backend +config usage

    +
    • +
  • +

    backend sets the path of the secret mount to use

    +
    • +
  • +

    default-context sets the context name used by all applications

    +
    • +
  • +

    application-name overrides the application name for use in the generic backend

    +
    • +
  • +

    profile-separator separates the profile name from the context in +property sources with profiles

    +
    • +
+
+
+

See also: Vault Documentation: Using the generic secret backend

+
+
+
+

Consul

+
+

Spring Cloud Vault can obtain credentials for HashiCorp Consul. +The Consul integration requires the spring-cloud-vault-config-consul +dependency.

+
+
+
Example 17. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-consul</artifactId>
+        <version>1.0.2.RELEASE</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.consul.enabled=true (default false) and +providing the role name with spring.cloud.vault.consul.role=….

+
+
+

The obtained token is stored in spring.cloud.consul.token +so using Spring Cloud Consul can pick up the generated +credentials without further configuration. You can configure +the property name by setting spring.cloud.vault.consul.token-property.

+
+
+
+
+
+
spring.cloud.vault:
+    consul:
+        enabled: true
+        role: readonly
+        backend: consul
+        token-property: spring.cloud.consul.token
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the Consul backend config usage

    +
    • +
  • +

    role sets the role name of the Consul role definition

    +
    • +
  • +

    backend sets the path of the Consul mount to use

    +
    • +
  • +

    token-property sets the property name in which the Consul ACL token is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up Consul with Vault

+
+
+
+

RabbitMQ

+
+

Spring Cloud Vault can obtain credentials for RabbitMQ.

+
+
+

The RabbitMQ integration requires the spring-cloud-vault-config-rabbitmq +dependency.

+
+
+
Example 18. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-rabbitmq</artifactId>
+        <version>1.0.2.RELEASE</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.rabbitmq.enabled=true (default false) +and providing the role name with spring.cloud.vault.rabbitmq.role=….

+
+
+

Username and password are stored in spring.rabbitmq.username +and spring.rabbitmq.password so using Spring Boot will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.rabbitmq.username-property and +spring.cloud.vault.rabbitmq.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    rabbitmq:
+        enabled: true
+        role: readonly
+        backend: rabbitmq
+        username-property: spring.rabbitmq.username
+        password-property: spring.rabbitmq.password
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the RabbitMQ backend config usage

    +
    • +
  • +

    role sets the role name of the RabbitMQ role definition

    +
    • +
  • +

    backend sets the path of the RabbitMQ mount to use

    +
    • +
  • +

    username-property sets the property name in which the RabbitMQ username is stored

    +
    • +
  • +

    password-property sets the property name in which the RabbitMQ password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up RabbitMQ with Vault

+
+
+
+

AWS

+
+

Spring Cloud Vault can obtain credentials for AWS.

+
+
+

The AWS integration requires the spring-cloud-vault-config-aws +dependency.

+
+
+
Example 19. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-aws</artifactId>
+        <version>1.0.2.RELEASE</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.aws=true (default false) +and providing the role name with spring.cloud.vault.aws.role=….

+
+
+

The access key and secret key are stored in cloud.aws.credentials.accessKey +and cloud.aws.credentials.secretKey so using Spring Cloud AWS will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.aws.access-key-property and +spring.cloud.vault.aws.secret-key-property.

+
+
+
+
+
+
spring.cloud.vault:
+    aws:
+        enabled: true
+        role: readonly
+        backend: aws
+        access-key-property: cloud.aws.credentials.accessKey
+        secret-key-property: cloud.aws.credentials.secretKey
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the AWS backend config usage

    +
    • +
  • +

    role sets the role name of the AWS role definition

    +
    • +
  • +

    backend sets the path of the AWS mount to use

    +
    • +
  • +

    access-key-property sets the property name in which the AWS access key is stored

    +
    • +
  • +

    secret-key-property sets the property name in which the AWS secret key is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up AWS with Vault

+
+
+
+
+
+

Database backends

+
+
+

Vault supports several database secret backends to generate database +credentials dynamically based on configured roles. This means +services that need to access a database no longer need to configure +credentials: they can request them from Vault, and use Vault’s leasing +mechanism to more easily roll keys.

+
+
+

Spring Cloud Vault integrates with these backends:

+
+
+ +
+
+

Using a database secret backend requires to enable the +backend in the configuration and the spring-cloud-vault-config-databases +dependency.

+
+
+
Example 20. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-databases</artifactId>
+        <version>1.0.2.RELEASE</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+ + + + + +
+
Note
+		 +Enabling multiple JDBC-compliant databases will generate credentials +and store them by default in the same property keys hence property names for +JDBC secrets need to be configured separately. +
+
+
+

Apache Cassandra

+
+

Spring Cloud Vault can obtain credentials for Apache Cassandra. +The integration can be enabled by setting +spring.cloud.vault.cassandra.enabled=true (default false) and +providing the role name with spring.cloud.vault.cassandra.role=….

+
+
+

Username and password are stored in spring.data.cassandra.username +and spring.data.cassandra.password so using Spring Boot will pick +up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.cassandra.username-property and +spring.cloud.vault.cassandra.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    cassandra:
+        enabled: true
+        role: readonly
+        backend: cassandra
+        username-property: spring.data.cassandra.username
+        password-property: spring.data.cassandra.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the Cassandra backend config usage

    +
    • +
  • +

    role sets the role name of the Cassandra role definition

    +
    • +
  • +

    backend sets the path of the Cassandra mount to use

    +
    • +
  • +

    username-property sets the property name in which the Cassandra username is stored

    +
    • +
  • +

    password-property sets the property name in which the Cassandra password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up Apache Cassandra with Vault

+
+
+
+

MongoDB

+
+

Spring Cloud Vault can obtain credentials for MongoDB. +The integration can be enabled by setting +spring.cloud.vault.mongodb.enabled=true (default false) and +providing the role name with spring.cloud.vault.mongodb.role=….

+
+
+

Username and password are stored in spring.data.mongodb.username +and spring.data.mongodb.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mongodb.username-property and +spring.cloud.vault.mongodb.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    mongodb:
+        enabled: true
+        role: readonly
+        backend: mongodb
+        username-property: spring.data.mongodb.username
+        password-property: spring.data.mongodb.password
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the MongodB backend config usage

    +
    • +
  • +

    role sets the role name of the MongoDB role definition

    +
    • +
  • +

    backend sets the path of the MongoDB mount to use

    +
    • +
  • +

    username-property sets the property name in which the MongoDB username is stored

    +
    • +
  • +

    password-property sets the property name in which the MongoDB password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up MongoDB with Vault

+
+
+
+

MySQL

+
+

Spring Cloud Vault can obtain credentials for MySQL. +The integration can be enabled by setting +spring.cloud.vault.mysql.enabled=true (default false) and +providing the role name with spring.cloud.vault.mysql.role=….

+
+
+

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mysql.username-property and +spring.cloud.vault.mysql.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    mysql:
+        enabled: true
+        role: readonly
+        backend: mysql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the MySQL backend config usage

    +
    • +
  • +

    role sets the role name of the MySQL role definition

    +
    • +
  • +

    backend sets the path of the MySQL mount to use

    +
    • +
  • +

    username-property sets the property name in which the MySQL username is stored

    +
    • +
  • +

    password-property sets the property name in which the MySQL password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up MySQL with Vault

+
+
+
+

PostgreSQL

+
+

Spring Cloud Vault can obtain credentials for PostgreSQL. +The integration can be enabled by setting +spring.cloud.vault.postgresql.enabled=true (default false) and +providing the role name with spring.cloud.vault.postgresql.role=….

+
+
+

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.postgresql.username-property and +spring.cloud.vault.postgresql.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    postgresql:
+        enabled: true
+        role: readonly
+        backend: postgresql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the PostgreSQL backend config usage

    +
    • +
  • +

    role sets the role name of the PostgreSQL role definition

    +
    • +
  • +

    backend sets the path of the PostgreSQL mount to use

    +
    • +
  • +

    username-property sets the property name in which the PostgreSQL username is stored

    +
    • +
  • +

    password-property sets the property name in which the PostgreSQL password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up PostgreSQL with Vault

+
+
+
+
+
+

Vault Client Fail Fast

+
+
+

In some cases, it may be desirable to fail startup of a service if +it cannot connect to the Vault Server. If this is the desired +behavior, set the bootstrap configuration property +spring.cloud.vault.fail-fast=true and the client will halt with +an Exception.

+
+
+
+
+
+
spring.cloud.vault:
+    fail-fast: true
+
+
+
+
+
+
+
+

Vault Client SSL configuration

+
+
+

SSL can be configured declaratively by setting various properties. +You can set either javax.net.ssl.trustStore to configure +JVM-wide SSL settings or spring.cloud.vault.ssl.trust-store +to set SSL settings only for Spring Cloud Vault Config.

+
+
+
+
+
+
spring.cloud.vault:
+    ssl:
+        trust-store: classpath:keystore.jks
+        trust-store-password: changeit
+
+
+
+
+
+
    +
  • +

    trust-store sets the resource for the trust-store. SSL-secured Vault +communication will validate the Vault SSL certificate with the specified +trust-store.

    +
    • +
  • +

    trust-store-password sets the trust-store password

    +
    • +
+
+
+

Please note that configuring spring.cloud.vault.ssl.* can be only +applied when either Apache Http Components or the OkHttp client +is on your class-path.

+
+
+
+
+

Lease lifecycle management (renewal and revocation)

+
+
+

With every secret, Vault creates a lease: +metadata containing information such as a time duration, +renewability, and more.

+
+
+

Vault promises that the data will be valid for the given duration, +or Time To Live (TTL). Once the lease is expired, Vault can +revoke the data, and the consumer of the secret can no longer +be certain that it is valid.

+
+
+

Spring Cloud Vault maintains a lease lifecycle beyond +the creation of login tokens and secrets. That said, +login tokens and secrets associated with a lease +are scheduled for renewal just before the lease expires +until terminal expiry. +Application shutdown revokes obtained login tokens and renewable +leases.

+
+
+

Secret service and database backends (such as MongoDB or MySQL) +usually generate a renewable lease so generated credentials will +be disabled on application shutdown.

+
+
+ + + + + +
+
Note
+		 +Static tokens are not renewed or revoked. +
+
+
+

Lease renewal and revocation is enabled by default and can +be disabled by setting spring.cloud.vault.config.lifecycle.enabled +to false. This is not recommended as leases can expire and +Spring Cloud Vault cannot longer access Vault or services +using generated credentials and valid credentials remain active +after application shutdown.

+
+
+
+
+
+
spring.cloud.vault:
+    config.lifecycle.enabled: true
+
+
+
+
+
+

See also: Vault Documentation: Lease, Renew, and Revoke

+
+
+
+
+ + + + + \ No newline at end of file diff --git a/spring-cloud-vault/1.1.0.M1/ghpages.sh b/spring-cloud-vault/1.1.0.M1/ghpages.sh new file mode 100644 index 00000000..57c5da3a --- /dev/null +++ b/spring-cloud-vault/1.1.0.M1/ghpages.sh @@ -0,0 +1,330 @@ +#!/bin/bash -x + +set -e + +# Set default props like MAVEN_PATH, ROOT_FOLDER etc. +function set_default_props() { + # The script should be executed from the root folder + ROOT_FOLDER=`pwd` + echo "Current folder is ${ROOT_FOLDER}" + + if [[ ! -e "${ROOT_FOLDER}/.git" ]]; then + echo "You're not in the root folder of the project!" + exit 1 + fi + + # Prop that will let commit the changes + COMMIT_CHANGES="no" + MAVEN_PATH=${MAVEN_PATH:-} + echo "Path to Maven is [${MAVEN_PATH}]" + REPO_NAME=${PWD##*/} + echo "Repo name is [${REPO_NAME}]" + SPRING_CLOUD_STATIC_REPO=${SPRING_CLOUD_STATIC_REPO:-git@github.com:spring-cloud/spring-cloud-static.git} + echo "Spring Cloud Static repo is [${SPRING_CLOUD_STATIC_REPO}" +} + +# Check if gh-pages exists and docs have been built +function check_if_anything_to_sync() { + git remote set-url --push origin `git config remote.origin.url | sed -e 's/^git:/https:/'` + + if ! (git remote set-branches --add origin gh-pages && git fetch -q); then + echo "No gh-pages, so not syncing" + exit 0 + fi + + if ! [ -d docs/target/generated-docs ] && ! [ "${BUILD}" == "yes" ]; then + echo "No gh-pages sources in docs/target/generated-docs, so not syncing" + exit 0 + fi +} + +function retrieve_current_branch() { + # Code getting the name of the current branch. For master we want to publish as we did until now + # http://stackoverflow.com/questions/1593051/how-to-programmatically-determine-the-current-checked-out-git-branch + # If there is a branch already passed will reuse it - otherwise will try to find it + CURRENT_BRANCH=${BRANCH} + if [[ -z "${CURRENT_BRANCH}" ]] ; then + CURRENT_BRANCH=$(git symbolic-ref -q HEAD) + CURRENT_BRANCH=${CURRENT_BRANCH##refs/heads/} + CURRENT_BRANCH=${CURRENT_BRANCH:-HEAD} + fi + echo "Current branch is [${CURRENT_BRANCH}]" + git checkout ${CURRENT_BRANCH} || echo "Failed to check the branch... continuing with the script" +} + +# Switches to the provided value of the release version. We always prefix it with `v` +function switch_to_tag() { + git checkout v${VERSION} +} + +# Build the docs if switch is on +function build_docs_if_applicable() { + if [[ "${BUILD}" == "yes" ]] ; then + ./mvnw clean install -P docs -pl docs -DskipTests + fi +} + +# Get the name of the `docs.main` property +# Get whitelisted branches - assumes that a `docs` module is available under `docs` profile +function retrieve_doc_properties() { + MAIN_ADOC_VALUE=$("${MAVEN_PATH}"mvn -q \ + -Dexec.executable="echo" \ + -Dexec.args='${docs.main}' \ + --non-recursive \ + org.codehaus.mojo:exec-maven-plugin:1.3.1:exec) + echo "Extracted 'main.adoc' from Maven build [${MAIN_ADOC_VALUE}]" + + + WHITELIST_PROPERTY=${WHITELIST_PROPERTY:-"docs.whitelisted.branches"} + WHITELISTED_BRANCHES_VALUE=$("${MAVEN_PATH}"mvn -q \ + -Dexec.executable="echo" \ + -Dexec.args="\${${WHITELIST_PROPERTY}}" \ + org.codehaus.mojo:exec-maven-plugin:1.3.1:exec \ + -P docs \ + -pl docs) + echo "Extracted '${WHITELIST_PROPERTY}' from Maven build [${WHITELISTED_BRANCHES_VALUE}]" +} + +# Stash any outstanding changes +function stash_changes() { + git diff-index --quiet HEAD && dirty=$? || (echo "Failed to check if the current repo is dirty. Assuming that it is." && dirty="1") + if [ "$dirty" != "0" ]; then git stash; fi +} + +# Switch to gh-pages branch to sync it with current branch +function add_docs_from_target() { + local DESTINATION_REPO_FOLDER + if [[ -z "${DESTINATION}" && -z "${CLONE}" ]] ; then + DESTINATION_REPO_FOLDER=${ROOT_FOLDER} + elif [[ "${CLONE}" == "yes" ]]; then + mkdir -p ${ROOT_FOLDER}/target + local clonedStatic=${ROOT_FOLDER}/target/spring-cloud-static + if [[ ! -e "${clonedStatic}/.git" ]]; then + echo "Cloning Spring Cloud Static to target" + git clone ${SPRING_CLOUD_STATIC_REPO} ${clonedStatic} && git checkout gh-pages + else + echo "Spring Cloud Static already cloned - will pull changes" + cd ${clonedStatic} && git checkout gh-pages && git pull origin gh-pages + fi + DESTINATION_REPO_FOLDER=${clonedStatic}/${REPO_NAME} + mkdir -p ${DESTINATION_REPO_FOLDER} + else + if [[ ! -e "${DESTINATION}/.git" ]]; then + echo "[${DESTINATION}] is not a git repository" + exit 1 + fi + DESTINATION_REPO_FOLDER=${DESTINATION}/${REPO_NAME} + mkdir -p ${DESTINATION_REPO_FOLDER} + echo "Destination was provided [${DESTINATION}]" + fi + cd ${DESTINATION_REPO_FOLDER} + git checkout gh-pages + git pull origin gh-pages + + # Add git branches + ################################################################### + if [[ -z "${VERSION}" ]] ; then + copy_docs_for_current_version + else + copy_docs_for_provided_version + fi + commit_changes_if_applicable +} + + +# Copies the docs by using the retrieved properties from Maven build +function copy_docs_for_current_version() { + if [[ "${CURRENT_BRANCH}" == "master" ]] ; then + echo -e "Current branch is master - will copy the current docs only to the root folder" + for f in docs/target/generated-docs/*; do + file=${f#docs/target/generated-docs/*} + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then + # Not ignored... + cp -rf $f ${ROOT_FOLDER}/ + git add -A ${ROOT_FOLDER}/$file + fi + done + COMMIT_CHANGES="yes" + else + echo -e "Current branch is [${CURRENT_BRANCH}]" + # http://stackoverflow.com/questions/29300806/a-bash-script-to-check-if-a-string-is-present-in-a-comma-separated-list-of-strin + if [[ ",${WHITELISTED_BRANCHES_VALUE}," = *",${CURRENT_BRANCH},"* ]] ; then + mkdir -p ${ROOT_FOLDER}/${CURRENT_BRANCH} + echo -e "Branch [${CURRENT_BRANCH}] is whitelisted! Will copy the current docs to the [${CURRENT_BRANCH}] folder" + for f in docs/target/generated-docs/*; do + file=${f#docs/target/generated-docs/*} + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then + # Not ignored... + # We want users to access 1.0.0.RELEASE/ instead of 1.0.0.RELEASE/spring-cloud.sleuth.html + if [[ "${file}" == "${MAIN_ADOC_VALUE}.html" ]] ; then + # We don't want to copy the spring-cloud-sleuth.html + # we want it to be converted to index.html + cp -rf $f ${ROOT_FOLDER}/${CURRENT_BRANCH}/index.html + git add -A ${ROOT_FOLDER}/${CURRENT_BRANCH}/index.html + else + cp -rf $f ${ROOT_FOLDER}/${CURRENT_BRANCH} + git add -A ${ROOT_FOLDER}/${CURRENT_BRANCH}/$file + fi + fi + done + COMMIT_CHANGES="yes" + else + echo -e "Branch [${CURRENT_BRANCH}] is not on the white list! Check out the Maven [${WHITELIST_PROPERTY}] property in + [docs] module available under [docs] profile. Won't commit any changes to gh-pages for this branch." + fi + fi +} + +# Copies the docs by using the explicitly provided version +function copy_docs_for_provided_version() { + local FOLDER=${DESTINATION_REPO_FOLDER}/${VERSION} + mkdir -p ${FOLDER} + echo -e "Current tag is [v${VERSION}] Will copy the current docs to the [${FOLDER}] folder" + for f in ${ROOT_FOLDER}/docs/target/generated-docs/*; do + file=${f#${ROOT_FOLDER}/docs/target/generated-docs/*} + copy_docs_for_branch ${file} ${FOLDER} + done + COMMIT_CHANGES="yes" + CURRENT_BRANCH="v${VERSION}" +} + +# Copies the docs from target to the provided destination +# Params: +# $1 - file from target +# $2 - destination to which copy the files +function copy_docs_for_branch() { + local file=$1 + local destination=$2 + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^${file}$; then + # Not ignored... + # We want users to access 1.0.0.RELEASE/ instead of 1.0.0.RELEASE/spring-cloud.sleuth.html + if [[ ("${file}" == "${MAIN_ADOC_VALUE}.html") || ("${file}" == "${REPO_NAME}.html") ]] ; then + # We don't want to copy the spring-cloud-sleuth.html + # we want it to be converted to index.html + cp -rf $f ${destination}/index.html + git add -A ${destination}/index.html + else + cp -rf $f ${destination} + git add -A ${destination}/$file + fi + fi +} + +function commit_changes_if_applicable() { + if [[ "${COMMIT_CHANGES}" == "yes" ]] ; then + COMMIT_SUCCESSFUL="no" + git commit -a -m "Sync docs from ${CURRENT_BRANCH} to gh-pages" && COMMIT_SUCCESSFUL="yes" || echo "Failed to commit changes" + + # Uncomment the following push if you want to auto push to + # the gh-pages branch whenever you commit to master locally. + # This is a little extreme. Use with care! + ################################################################### + if [[ "${COMMIT_SUCCESSFUL}" == "yes" ]] ; then + git push origin gh-pages + fi + fi +} + +# Switch back to the previous branch and exit block +function checkout_previous_branch() { + # If -version was provided we need to come back to root project + cd ${ROOT_FOLDER} + git checkout ${CURRENT_BRANCH} || echo "Failed to check the branch... continuing with the script" + if [ "$dirty" != "0" ]; then git stash pop; fi + exit 0 +} + +# Assert if properties have been properly passed +function assert_properties() { +echo "VERSION [${VERSION}], DESTINATION [${DESTINATION}], CLONE [${CLONE}]" +if [[ "${VERSION}" != "" && (-z "${DESTINATION}" && -z "${CLONE}") ]] ; then echo "Version was set but destination / clone was not!"; exit 1;fi +if [[ ("${DESTINATION}" != "" && "${CLONE}" != "") && -z "${VERSION}" ]] ; then echo "Destination / clone was set but version was not!"; exit 1;fi +if [[ "${DESTINATION}" != "" && "${CLONE}" == "yes" ]] ; then echo "Destination and clone was set. Pick one!"; exit 1;fi +} + +# Prints the usage +function print_usage() { +cat </` +- if the destination switch is passed (-d) then the script will check if the provided dir is a git repo and then will + switch to gh-pages of that repo and copy the generated docs to `docs//` + +USAGE: + +You can use the following options: + +-v|--version - the script will apply the whole procedure for a particular library version +-d|--destination - the root of destination folder where the docs should be copied. You have to use the full path. + E.g. point to spring-cloud-static folder. Can't be used with (-c) +-b|--build - will run the standard build process after checking out the branch +-c|--clone - will automatically clone the spring-cloud-static repo instead of providing the destination. + Obviously can't be used with (-d) + +EOF +} + + +# ========================================== +# ____ ____ _____ _____ _____ _______ +# / ____|/ ____| __ \|_ _| __ \__ __| +# | (___ | | | |__) | | | | |__) | | | +# \___ \| | | _ / | | | ___/ | | +# ____) | |____| | \ \ _| |_| | | | +# |_____/ \_____|_| \_\_____|_| |_| +# +# ========================================== + +while [[ $# > 0 ]] +do +key="$1" +case ${key} in + -v|--version) + VERSION="$2" + shift # past argument + ;; + -d|--destination) + DESTINATION="$2" + shift # past argument + ;; + -b|--build) + BUILD="yes" + ;; + -c|--clone) + CLONE="yes" + ;; + -h|--help) + print_usage + exit 0 + ;; + *) + echo "Invalid option: [$1]" + print_usage + exit 1 + ;; +esac +shift # past argument or value +done + +assert_properties +set_default_props +check_if_anything_to_sync +if [[ -z "${VERSION}" ]] ; then + retrieve_current_branch +else + switch_to_tag +fi +build_docs_if_applicable +retrieve_doc_properties +stash_changes +add_docs_from_target +checkout_previous_branch \ No newline at end of file diff --git a/spring-cloud-vault/1.1.0.M1/index.html b/spring-cloud-vault/1.1.0.M1/index.html new file mode 100644 index 00000000..a94fcf3b --- /dev/null +++ b/spring-cloud-vault/1.1.0.M1/index.html @@ -0,0 +1,2137 @@ + + + + + + + +Spring Cloud Vault + + + + + +
+
+
+
+

© 2016-2017 The original authors.

+
+
+ + + + + +
+
Note
+		 +Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically. +
+
+
+

Spring Cloud Vault Config provides client-side support for externalized configuration in a distributed system. With HashiCorp’s Vault you have a central place to manage external secret properties for applications across all environments. Vault can manage static and dynamic secrets such as username/password for remote applications/resources and provide credentials for external services such as MySQL, PostgreSQL, Apache Cassandra, MongoDB, Consul, AWS and more.

+
+
+
+
+

Quick Start

+
+
+

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 7 and a properly configured JAVA_HOME environment variable

    +
    • +
+
+
+

Install Vault

+
+
+
+
$ src/test/bash/install_vault.sh
+
+
+
+

Create SSL certificates for Vault

+
+
+
+
$ src/test/bash/create_certificates.sh
+
+
+
+ + + + + +
+
Note
+		 +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. +
+
+
+

Start Vault server

+
+
+
+
$ src/test/bash/local_run_vault.sh
+
+
+
+

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.

+
+
+
+
$ export VAULT_ADDR="https://localhost:8200"
+$ export VAULT_SKIP_VERIFY=true # Don't do this for production
+$ vault init
+
+
+
+

You should see something like:

+
+
+
+
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.

+
+
+
+
$ vault unseal (Key 1)
+$ vault unseal (Key 2)
+$ vault 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

+
+
+

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:

+
+
+
Example 1. pom.xml
+
+
+
+
<parent>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-parent</artifactId>
+    <version>1.5.4.RELEASE</version>
+    <relativePath /> <!-- lookup parent from repository -->
+</parent>
+
+<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-starter-vault-config</artifactId>
+        <version>1.1.0.M1</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:

+
+
+
+
+
+
@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 bootstrap.properties (like application.properties but for +the bootstrap phase of an application context), e.g.

+
+
+
Example 2. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    host: localhost
+    port: 8200
+    scheme: https
+    uri: https://localhost:8200
+    connection-timeout: 5000
+    read-timeout: 15000
+    config:
+        order: -10
+
+
+
+
+
+
    +
  • +

    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

    +
    • +
  • +

    config.order sets the order for the property source

    +
    • +
+
+
+

Enabling further integrations requires additional dependencies and +configuration. Depending on how you have set up Vault you might need +additional configuration like +SSL and +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 health.vault.enabled (default true).

+
+
+

Authentication

+
+

Vault requires an authentication mechanism to authorize client requests.

+
+
+

Spring Cloud Vault supports multiple authentication mechanisms to authenticate applications with Vault.

+
+
+

For a quickstart, use the root token printed by the Vault initialization.

+
+
+
Example 3. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    token: 19aefa97-cccc-bbbb-aaaa-225940e63d76
+
+
+
+
+
+ + + + + +
+
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. +
+
+
+
+
+
+

Authentication methods

+
+
+

Different organizations have different requirements for security +and authentication. Vault reflects that need by shipping multiple authentication +methods. Spring Cloud Vault supports token and AppId authentication.

+
+
+

Token authentication

+
+

Tokens are the core method for authentication within Vault. +Token authentication requires a static token to be provided using the +Bootstrap Application Context.

+
+
+ + + + + +
+
Note
+		 +Token authentication is the default authentication method. +If a token is disclosed an unintended party gains access to Vault and +can access secrets for the intended client. +
+
+
+
Example 4. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: TOKEN
+    token: 00000000-0000-0000-0000-000000000000
+
+
+
+
+
+
    +
  • +

    authentication setting this value to TOKEN selects the Token +authentication method

    +
    • +
  • +

    token sets the static token to use

    +
    • +
+
+
+

See also: Vault Documentation: Tokens

+
+
+
+

AppId authentication

+
+

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 Cloud Vault Config 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.

+
+
+
Example 5. bootstrap.yml using SHA256 IP-Address UserId’s
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: IP_ADDRESS
+
+
+
+
+
+
    +
  • +

    authentication setting this value to APPID selects the AppId +authentication method

    +
    • +
  • +

    app-id-path sets the path of the AppId mount to use

    +
    • +
  • +

    user-id sets the UserId method. Possible values are IP_ADDRESS, +MAC_ADDRESS or a class name implementing a custom AppIdUserIdMechanism

    +
    • +
+
+
+

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

+
+
+
+
$ echo -n 192.168.99.1 | sha256sum
+
+
+
+ + + + + +
+
Note
+		 +Including the line break of echo leads to a different hash value +so make sure to include the -n flag. +
+
+
+

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).

+
+
+
Example 6. bootstrap.yml using SHA256 Mac-Address UserId’s
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: MAC_ADDRESS
+        network-interface: eth0
+
+
+
+
+
+
    +
  • +

    network-interface sets network interface to obtain the physical address

    +
    • +
+
+
+

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

+
+
+
+
$ echo -n 0AFEDE1234AC | sha256sum
+
+
+
+ + + + + +
+
Note
+		 +The Mac address is specified uppercase and without colons. +Including the line break of echo leads to a different hash value +so make sure to include the -n flag. +
+
+
+

Custom UserId

+
+

The UserId generation is an open mechanism. You can set +spring.cloud.vault.app-id.user-id to any string and the configured +value will be used as static UserId.

+
+
+

A more advanced approach lets you set spring.cloud.vault.app-id.user-id to a +classname. This class must be on your classpath and must implement +the org.springframework.cloud.vault.AppIdUserIdMechanism interface +and the createUserId method. Spring Cloud Vault will obtain the UserId +by calling createUserId each time it authenticates using AppId to +obtain a token.

+
+
+
Example 7. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: com.examlple.MyUserIdMechanism
+
+
+
+
+
+
Example 8. MyUserIdMechanism.java
+
+
+
+
public class MyUserIdMechanism implements AppIdUserIdMechanism {
+
+  @Override
+  public String createUserId() {
+    String userId = ...
+    return userId;
+  }
+}
+
+
+
+
+
+

See also: Vault Documentation: Using the App ID auth backend

+
+
+
+
+

AppRole authentication

+
+

AppRole is intended for 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 (push or pull mode).

+
+
+

RoleId and optionally SecretId must be provided by configuration, +Spring Vault will not look up these or create a custom SecretId.

+
+
+
Example 9. bootstrap.yml with AppRole authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
+
+
+
+
+
+
    +
  • +

    role-id sets the RoleId.

    +
    • +
+
+
+
Example 10. bootstrap.yml with all AppRole authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
+        secret-id: 1696536f-1976-73b1-b241-0b4213908d39
+        app-auth-path: approle
+
+
+
+
+
+
    +
  • +

    role-id sets the RoleId.

    +
    • +
  • +

    secret-id sets the SecretId. SecretId can be omitted if AppRole is configured without requiring SecretId (See bind_secret_id)

    +
    • +
  • +

    approle-path sets the path of the approle authentication mount to use

    +
    • +
+
+
+

See also: Vault Documentation: Using the AppRole auth backend

+
+
+
+

AWS-EC2 authentication

+
+

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.

+
+
+
Example 11. bootstrap.yml using AWS-EC2 Authentication
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+
+
+
+
+
+

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 Cloud 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. +You can configure a static nonce with spring.cloud.vault.aws-ec2.nonce.

+
+
+

AWS-EC2 authentication roles are optional and default to the AMI. +You can configure the authentication role by setting the +spring.cloud.vault.aws-ec2.role property.

+
+
+
Example 12. bootstrap.yml with configured role
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server
+
+
+
+
+
+
Example 13. bootstrap.yml with all AWS EC2 authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server
+        aws-ec2-path: aws-ec2
+        identity-document: http://...
+        nonce: my-static-nonce
+
+
+
+
+
+
    +
  • +

    authentication setting this value to AWS_EC2 selects the AWS EC2 +authentication method

    +
    • +
  • +

    role sets the role name of the AWS EC2 role definition

    +
    • +
  • +

    aws-ec2-path sets the path of the AWS EC2 mount to use

    +
    • +
  • +

    identity-document sets URL of the PKCS#7 AWS EC2 identity document

    +
    • +
  • +

    nonce used for AWS-EC2 authentication. An empty nonce defaults to nonce generation

    +
    • +
+
+
+

See also: Vault Documentation: Using the aws-ec2 auth backend

+
+
+
+

TLS certificate authentication

+
+

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:

+
+
+
    +
  1. +

    Use SSL, see Vault Client SSL configuration

    +
    2. +
  2. +

    Configure a Java Keystore that contains the client +certificate and the private key

    +
    3. +
  3. +

    Set the spring.cloud.vault.authentication to CERT

    +
    4. +
+
+
+
Example 14. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: CERT
+    ssl:
+        key-store: classpath:keystore.jks
+        key-store-password: changeit
+        cert-auth-path: cert
+
+
+
+
+
+

See also: Vault Documentation: Using the Cert auth backend

+
+
+
+

Cubbyhole authentication

+
+

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 will be retrieved from a wrapped +response stored at /cubbyhole/response.

+
+
+

Creating a wrapped token

+
+
+ + + + + +
+
Note
+		 +Response Wrapping for token creation requires Vault 0.6.0 or higher. +
+
+
+
Example 15. Crating and storing tokens
+
+
+
+
$ vault token-create -wrap-ttl="10m"
+Key                            Value
+---                            -----
+wrapping_token:                397ccb93-ff6c-b17b-9389-380b01ca2645
+wrapping_token_ttl:            0h10m0s
+wrapping_token_creation_time:  2016-09-18 20:29:48.652957077 +0200 CEST
+wrapped_accessor:              46b6aebb-187f-932a-26d7-4f3d86a68319
+
+
+
+
+
+
Example 16. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: CUBBYHOLE
+    token: 397ccb93-ff6c-b17b-9389-380b01ca2645
+
+
+
+
+
+

See also:

+
+
+ +
+
+
+
+
+

Secret Backends

+
+
+

Generic Backend

+
+

Spring Cloud Vault supports at the basic level the generic secret +backend. The generic secret backend allows storage of arbitrary +values as key-value store. A single context can store one or many +key-value tuples. Contexts can be organized hierarchically. +Spring Cloud Vault allows using the Application name +and a default context name (application) in combination with active +profiles.

+
+
+
+
/secret/{application}/{profile}
+/secret/{application}
+/secret/{default-context}/{profile}
+/secret/{default-context}
+
+
+
+

The application name is determined by the properties:

+
+
+
    +
  • +

    spring.cloud.vault.generic.application-name

    +
    • +
  • +

    spring.cloud.vault.application-name

    +
    • +
  • +

    spring.application.name

    +
    • +
+
+
+

Secrets can be obtained from other folders within the generic backend by adding their +paths to the application name, separated by commas. For example, given the application +name usefulapp,mysql1,projectx/aws, each of these folders will be used:

+
+
+
    +
  • +

    /secret/usefulapp

    +
    • +
  • +

    /secret/mysql1

    +
    • +
  • +

    /secret/projectx/aws

    +
    • +
+
+
+

Spring Cloud Vault adds all active profiles to the list of possible context paths. +No active profiles will skip accessing contexts with a profile name.

+
+
+

Properties are exposed like they are stored (i.e. without additional prefixes).

+
+
+
+
+
+
spring.cloud.vault:
+    generic:
+        enabled: true
+        backend: secret
+        profile-separator: '/'
+        default-context: application
+        application-name: my-app
+
+
+
+
+
+
    +
  • +

    enabled setting this value to false disables the secret backend +config usage

    +
    • +
  • +

    backend sets the path of the secret mount to use

    +
    • +
  • +

    default-context sets the context name used by all applications

    +
    • +
  • +

    application-name overrides the application name for use in the generic backend

    +
    • +
  • +

    profile-separator separates the profile name from the context in +property sources with profiles

    +
    • +
+
+
+

See also: Vault Documentation: Using the generic secret backend

+
+
+
+

Consul

+
+

Spring Cloud Vault can obtain credentials for HashiCorp Consul. +The Consul integration requires the spring-cloud-vault-config-consul +dependency.

+
+
+
Example 17. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-consul</artifactId>
+        <version>1.1.0.M1</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.consul.enabled=true (default false) and +providing the role name with spring.cloud.vault.consul.role=….

+
+
+

The obtained token is stored in spring.cloud.consul.token +so using Spring Cloud Consul can pick up the generated +credentials without further configuration. You can configure +the property name by setting spring.cloud.vault.consul.token-property.

+
+
+
+
+
+
spring.cloud.vault:
+    consul:
+        enabled: true
+        role: readonly
+        backend: consul
+        token-property: spring.cloud.consul.token
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the Consul backend config usage

    +
    • +
  • +

    role sets the role name of the Consul role definition

    +
    • +
  • +

    backend sets the path of the Consul mount to use

    +
    • +
  • +

    token-property sets the property name in which the Consul ACL token is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up Consul with Vault

+
+
+
+

RabbitMQ

+
+

Spring Cloud Vault can obtain credentials for RabbitMQ.

+
+
+

The RabbitMQ integration requires the spring-cloud-vault-config-rabbitmq +dependency.

+
+
+
Example 18. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-rabbitmq</artifactId>
+        <version>1.1.0.M1</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.rabbitmq.enabled=true (default false) +and providing the role name with spring.cloud.vault.rabbitmq.role=….

+
+
+

Username and password are stored in spring.rabbitmq.username +and spring.rabbitmq.password so using Spring Boot will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.rabbitmq.username-property and +spring.cloud.vault.rabbitmq.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    rabbitmq:
+        enabled: true
+        role: readonly
+        backend: rabbitmq
+        username-property: spring.rabbitmq.username
+        password-property: spring.rabbitmq.password
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the RabbitMQ backend config usage

    +
    • +
  • +

    role sets the role name of the RabbitMQ role definition

    +
    • +
  • +

    backend sets the path of the RabbitMQ mount to use

    +
    • +
  • +

    username-property sets the property name in which the RabbitMQ username is stored

    +
    • +
  • +

    password-property sets the property name in which the RabbitMQ password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up RabbitMQ with Vault

+
+
+
+

AWS

+
+

Spring Cloud Vault can obtain credentials for AWS.

+
+
+

The AWS integration requires the spring-cloud-vault-config-aws +dependency.

+
+
+
Example 19. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-aws</artifactId>
+        <version>1.1.0.M1</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.aws=true (default false) +and providing the role name with spring.cloud.vault.aws.role=….

+
+
+

The access key and secret key are stored in cloud.aws.credentials.accessKey +and cloud.aws.credentials.secretKey so using Spring Cloud AWS will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.aws.access-key-property and +spring.cloud.vault.aws.secret-key-property.

+
+
+
+
+
+
spring.cloud.vault:
+    aws:
+        enabled: true
+        role: readonly
+        backend: aws
+        access-key-property: cloud.aws.credentials.accessKey
+        secret-key-property: cloud.aws.credentials.secretKey
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the AWS backend config usage

    +
    • +
  • +

    role sets the role name of the AWS role definition

    +
    • +
  • +

    backend sets the path of the AWS mount to use

    +
    • +
  • +

    access-key-property sets the property name in which the AWS access key is stored

    +
    • +
  • +

    secret-key-property sets the property name in which the AWS secret key is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up AWS with Vault

+
+
+
+
+
+

Database backends

+
+
+

Vault supports several database secret backends to generate database +credentials dynamically based on configured roles. This means +services that need to access a database no longer need to configure +credentials: they can request them from Vault, and use Vault’s leasing +mechanism to more easily roll keys.

+
+
+

Spring Cloud Vault integrates with these backends:

+
+
+ +
+
+

Using a database secret backend requires to enable the +backend in the configuration and the spring-cloud-vault-config-databases +dependency.

+
+
+
Example 20. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-databases</artifactId>
+        <version>1.1.0.M1</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+ + + + + +
+
Note
+		 +Enabling multiple JDBC-compliant databases will generate credentials +and store them by default in the same property keys hence property names for +JDBC secrets need to be configured separately. +
+
+
+

Apache Cassandra

+
+

Spring Cloud Vault can obtain credentials for Apache Cassandra. +The integration can be enabled by setting +spring.cloud.vault.cassandra.enabled=true (default false) and +providing the role name with spring.cloud.vault.cassandra.role=….

+
+
+

Username and password are stored in spring.data.cassandra.username +and spring.data.cassandra.password so using Spring Boot will pick +up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.cassandra.username-property and +spring.cloud.vault.cassandra.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    cassandra:
+        enabled: true
+        role: readonly
+        backend: cassandra
+        username-property: spring.data.cassandra.username
+        password-property: spring.data.cassandra.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the Cassandra backend config usage

    +
    • +
  • +

    role sets the role name of the Cassandra role definition

    +
    • +
  • +

    backend sets the path of the Cassandra mount to use

    +
    • +
  • +

    username-property sets the property name in which the Cassandra username is stored

    +
    • +
  • +

    password-property sets the property name in which the Cassandra password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up Apache Cassandra with Vault

+
+
+
+

MongoDB

+
+

Spring Cloud Vault can obtain credentials for MongoDB. +The integration can be enabled by setting +spring.cloud.vault.mongodb.enabled=true (default false) and +providing the role name with spring.cloud.vault.mongodb.role=….

+
+
+

Username and password are stored in spring.data.mongodb.username +and spring.data.mongodb.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mongodb.username-property and +spring.cloud.vault.mongodb.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    mongodb:
+        enabled: true
+        role: readonly
+        backend: mongodb
+        username-property: spring.data.mongodb.username
+        password-property: spring.data.mongodb.password
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the MongodB backend config usage

    +
    • +
  • +

    role sets the role name of the MongoDB role definition

    +
    • +
  • +

    backend sets the path of the MongoDB mount to use

    +
    • +
  • +

    username-property sets the property name in which the MongoDB username is stored

    +
    • +
  • +

    password-property sets the property name in which the MongoDB password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up MongoDB with Vault

+
+
+
+

MySQL

+
+

Spring Cloud Vault can obtain credentials for MySQL. +The integration can be enabled by setting +spring.cloud.vault.mysql.enabled=true (default false) and +providing the role name with spring.cloud.vault.mysql.role=….

+
+
+

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mysql.username-property and +spring.cloud.vault.mysql.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    mysql:
+        enabled: true
+        role: readonly
+        backend: mysql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the MySQL backend config usage

    +
    • +
  • +

    role sets the role name of the MySQL role definition

    +
    • +
  • +

    backend sets the path of the MySQL mount to use

    +
    • +
  • +

    username-property sets the property name in which the MySQL username is stored

    +
    • +
  • +

    password-property sets the property name in which the MySQL password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up MySQL with Vault

+
+
+
+

PostgreSQL

+
+

Spring Cloud Vault can obtain credentials for PostgreSQL. +The integration can be enabled by setting +spring.cloud.vault.postgresql.enabled=true (default false) and +providing the role name with spring.cloud.vault.postgresql.role=….

+
+
+

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.postgresql.username-property and +spring.cloud.vault.postgresql.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    postgresql:
+        enabled: true
+        role: readonly
+        backend: postgresql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the PostgreSQL backend config usage

    +
    • +
  • +

    role sets the role name of the PostgreSQL role definition

    +
    • +
  • +

    backend sets the path of the PostgreSQL mount to use

    +
    • +
  • +

    username-property sets the property name in which the PostgreSQL username is stored

    +
    • +
  • +

    password-property sets the property name in which the PostgreSQL password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up PostgreSQL with Vault

+
+
+
+
+
+

Configure PropertySourceLocator behavior

+
+
+

Spring Cloud Vault uses property-based configuration to create PropertySources +for generic and discovered secret backends.

+
+
+

Discovered backends provide VaultSecretBackendDescriptor beans to describe the configuration +state to use secret backend as PropertySource. A SecretBackendMetadataFactory is required +to create a SecretBackendMetadata object which contains path, name and property transformation +configuration.

+
+
+

SecretBackendMetadata is used to back a particular PropertySource.

+
+
+

You can register an arbitrary number of beans implementing VaultConfigurer for customization. +Default generic and discovered backend registration is disabled if Spring Cloud Vault discovers +at least one VaultConfigurer bean. You can however enable default registration with +SecretBackendConfigurer.registerDefaultGenericSecretBackends() and SecretBackendConfigurer.registerDefaultDiscoveredSecretBackends().

+
+
+
+
+
+
public class CustomizationBean implements VaultConfigurer {
+
+    @Override
+    public void addSecretBackends(SecretBackendConfigurer configurer) {
+
+        configurer.add("secret/my-application");
+
+        configurer.registerDefaultGenericSecretBackends(false);
+        configurer.registerDefaultDiscoveredSecretBackends(true);
+    }
+}
+
+
+
+
+
+ + + + + +
+
Note
+		 +All customization is required to happen in the bootstrap context. Add your configuration +classes to META-INF/spring.factories at org.springframework.cloud.bootstrap.BootstrapConfiguration +in your application. +
+
+
+
+
+

Service Registry Configuration

+
+
+

You can use a DiscoveryClient (such as from Spring Cloud Consul) to locate +a Vault server by setting spring.cloud.vault.discovery.enabled=true (default false). +The net result of that is that your apps need a bootstrap.yml (or an environment variable) +with the appropriate discovery configuration. +The benefit is that the Vault can change its co-ordinates, as long as the discovery service +is a fixed point. The default service id is vault but you can change that on the client with +spring.cloud.vault.discovery.serviceId.

+
+
+

The discovery client implementations all support some kind of metadata map +(e.g. for Eureka we have eureka.instance.metadataMap). Some additional properties of the service +may need to be configured in its service registration metadata so that clients can connect +correctly. Service registries that do not provide details about transport layer security +need to provide a scheme metadata entry to be set either to https or http. +If no scheme is configured and the service is not exposed as secure service, then +configuration defaults to spring.cloud.vault.scheme which is https when it’s not set.

+
+
+
+
+
+
spring.cloud.vault.discovery:
+    enabled: true
+    service-id: my-vault-service
+
+
+
+
+
+
+
+

Vault Client Fail Fast

+
+
+

In some cases, it may be desirable to fail startup of a service if +it cannot connect to the Vault Server. If this is the desired +behavior, set the bootstrap configuration property +spring.cloud.vault.fail-fast=true and the client will halt with +an Exception.

+
+
+
+
+
+
spring.cloud.vault:
+    fail-fast: true
+
+
+
+
+
+
+
+

Vault Client SSL configuration

+
+
+

SSL can be configured declaratively by setting various properties. +You can set either javax.net.ssl.trustStore to configure +JVM-wide SSL settings or spring.cloud.vault.ssl.trust-store +to set SSL settings only for Spring Cloud Vault Config.

+
+
+
+
+
+
spring.cloud.vault:
+    ssl:
+        trust-store: classpath:keystore.jks
+        trust-store-password: changeit
+
+
+
+
+
+
    +
  • +

    trust-store sets the resource for the trust-store. SSL-secured Vault +communication will validate the Vault SSL certificate with the specified +trust-store.

    +
    • +
  • +

    trust-store-password sets the trust-store password

    +
    • +
+
+
+

Please note that configuring spring.cloud.vault.ssl.* can be only +applied when either Apache Http Components or the OkHttp client +is on your class-path.

+
+
+
+
+

Lease lifecycle management (renewal and revocation)

+
+
+

With every secret, Vault creates a lease: +metadata containing information such as a time duration, +renewability, and more.

+
+
+

Vault promises that the data will be valid for the given duration, +or Time To Live (TTL). Once the lease is expired, Vault can +revoke the data, and the consumer of the secret can no longer +be certain that it is valid.

+
+
+

Spring Cloud Vault maintains a lease lifecycle beyond +the creation of login tokens and secrets. That said, +login tokens and secrets associated with a lease +are scheduled for renewal just before the lease expires +until terminal expiry. +Application shutdown revokes obtained login tokens and renewable +leases.

+
+
+

Secret service and database backends (such as MongoDB or MySQL) +usually generate a renewable lease so generated credentials will +be disabled on application shutdown.

+
+
+ + + + + +
+
Note
+		 +Static tokens are not renewed or revoked. +
+
+
+

Lease renewal and revocation is enabled by default and can +be disabled by setting spring.cloud.vault.config.lifecycle.enabled +to false. This is not recommended as leases can expire and +Spring Cloud Vault cannot longer access Vault or services +using generated credentials and valid credentials remain active +after application shutdown.

+
+
+
+
+
+
spring.cloud.vault:
+    config.lifecycle.enabled: true
+
+
+
+
+
+

See also: Vault Documentation: Lease, Renew, and Revoke

+
+
+
+
+ + + + + \ No newline at end of file diff --git a/spring-cloud-vault/1.1.0.RC1/css/highlight.css b/spring-cloud-vault/1.1.0.RC1/css/highlight.css new file mode 100644 index 00000000..ffefef72 --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/css/highlight.css @@ -0,0 +1,35 @@ +/* + code highlight CSS resemblign the Eclipse IDE default color schema + @author Costin Leau +*/ + +.hl-keyword { + color: #7F0055; + font-weight: bold; +} + +.hl-comment { + color: #3F5F5F; + font-style: italic; +} + +.hl-multiline-comment { + color: #3F5FBF; + font-style: italic; +} + +.hl-tag { + color: #3F7F7F; +} + +.hl-attribute { + color: #7F007F; +} + +.hl-value { + color: #2A00FF; +} + +.hl-string { + color: #2A00FF; +} \ No newline at end of file diff --git a/spring-cloud-vault/1.1.0.RC1/css/manual-multipage.css b/spring-cloud-vault/1.1.0.RC1/css/manual-multipage.css new file mode 100644 index 00000000..0c484531 --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/css/manual-multipage.css @@ -0,0 +1,9 @@ +@IMPORT url("manual.css"); + +body.firstpage { + background: url("../images/background.png") no-repeat center top; +} + +div.part h1 { + border-top: none; +} diff --git a/spring-cloud-vault/1.1.0.RC1/css/manual-singlepage.css b/spring-cloud-vault/1.1.0.RC1/css/manual-singlepage.css new file mode 100644 index 00000000..4a7fd140 --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/css/manual-singlepage.css @@ -0,0 +1,6 @@ +@IMPORT url("manual.css"); + +body { + background: url("../images/background.png") no-repeat center top; +} + diff --git a/spring-cloud-vault/1.1.0.RC1/css/manual.css b/spring-cloud-vault/1.1.0.RC1/css/manual.css new file mode 100644 index 00000000..0ecbe2e8 --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/css/manual.css @@ -0,0 +1,344 @@ +@IMPORT url("highlight.css"); + +html { + padding: 0pt; + margin: 0pt; +} + +body { + color: #333333; + margin: 15px 30px; + font-family: Helvetica, Arial, Freesans, Clean, Sans-serif; + line-height: 1.6; + -webkit-font-smoothing: antialiased; +} + +code { + font-size: 16px; + font-family: Consolas, "Liberation Mono", Courier, monospace; +} + +:not(a)>code { + color: #6D180B; +} + +:not(pre)>code { + background-color: #F2F2F2; + border: 1px solid #CCCCCC; + border-radius: 4px; + padding: 1px 3px 0; + text-shadow: none; + white-space: nowrap; +} + +body>*:first-child { + margin-top: 0 !important; +} + +div { + margin: 0pt; +} + +hr { + border: 1px solid #CCCCCC; + background: #CCCCCC; +} + +h1,h2,h3,h4,h5,h6 { + color: #000000; + cursor: text; + font-weight: bold; + margin: 30px 0 10px; + padding: 0; +} + +h1,h2,h3 { + margin: 40px 0 10px; +} + +h1 { + margin: 70px 0 30px; + padding-top: 20px; +} + +div.part h1 { + border-top: 1px dotted #CCCCCC; +} + +h1,h1 code { + font-size: 32px; +} + +h2,h2 code { + font-size: 24px; +} + +h3,h3 code { + font-size: 20px; +} + +h4,h1 code,h5,h5 code,h6,h6 code { + font-size: 18px; +} + +div.book,div.chapter,div.appendix,div.part,div.preface { + min-width: 300px; + max-width: 1200px; + margin: 0 auto; +} + +p.releaseinfo { + font-weight: bold; + margin-bottom: 40px; + margin-top: 40px; +} + +div.authorgroup { + line-height: 1; +} + +p.copyright { + line-height: 1; + margin-bottom: -5px; +} + +.legalnotice p { + font-style: italic; + font-size: 14px; + line-height: 1; +} + +div.titlepage+p,div.titlepage+p { + margin-top: 0; +} + +pre { + line-height: 1.0; + color: black; +} + +a { + color: #4183C4; + text-decoration: none; +} + +p { + margin: 15px 0; + text-align: left; +} + +ul,ol { + padding-left: 30px; +} + +li p { + margin: 0; +} + +div.table { + margin: 1em; + padding: 0.5em; + text-align: center; +} + +div.table table,div.informaltable table { + display: table; + width: 100%; +} + +div.table td { + padding-left: 7px; + padding-right: 7px; +} + +.sidebar { + line-height: 1.4; + padding: 0 20px; + background-color: #F8F8F8; + border: 1px solid #CCCCCC; + border-radius: 3px 3px 3px 3px; +} + +.sidebar p.title { + color: #6D180B; +} + +pre.programlisting,pre.screen { + font-size: 15px; + padding: 6px 10px; + background-color: #F8F8F8; + border: 1px solid #CCCCCC; + border-radius: 3px 3px 3px 3px; + clear: both; + overflow: auto; + line-height: 1.4; + font-family: Consolas, "Liberation Mono", Courier, monospace; +} + +table { + border-collapse: collapse; + border-spacing: 0; + border: 1px solid #DDDDDD !important; + border-radius: 4px !important; + border-collapse: separate !important; + line-height: 1.6; +} + +table thead { + background: #F5F5F5; +} + +table tr { + border: none; + border-bottom: none; +} + +table th { + font-weight: bold; +} + +table th,table td { + border: none !important; + padding: 6px 13px; +} + +table tr:nth-child(2n) { + background-color: #F8F8F8; +} + +td p { + margin: 0 0 15px 0; +} + +div.table-contents td p { + margin: 0; +} + +div.important *,div.note *,div.tip *,div.warning *,div.navheader *,div.navfooter *,div.calloutlist * + { + border: none !important; + background: none !important; + margin: 0; +} + +div.important p,div.note p,div.tip p,div.warning p { + color: #6F6F6F; + line-height: 1.6; +} + +div.important code,div.note code,div.tip code,div.warning code { + background-color: #F2F2F2 !important; + border: 1px solid #CCCCCC !important; + border-radius: 4px !important; + padding: 1px 3px 0 !important; + text-shadow: none !important; + white-space: nowrap !important; +} + +.note th,.tip th,.warning th { + display: none; +} + +.note tr:first-child td,.tip tr:first-child td,.warning tr:first-child td + { + border-right: 1px solid #CCCCCC !important; + padding-top: 10px; +} + +div.calloutlist p,div.calloutlist td { + padding: 0; + margin: 0; +} + +div.calloutlist>table>tbody>tr>td:first-child { + padding-left: 10px; + width: 30px !important; +} + +div.important,div.note,div.tip,div.warning { + margin-left: 0px !important; + margin-right: 20px !important; + margin-top: 20px; + margin-bottom: 20px; + padding-top: 10px; + padding-bottom: 10px; +} + +div.toc { + line-height: 1.2; +} + +dl,dt { + margin-top: 1px; + margin-bottom: 0; +} + +div.toc>dl>dt { + font-size: 32px; + font-weight: bold; + margin: 30px 0 10px 0; + display: block; +} + +div.toc>dl>dd>dl>dt { + font-size: 24px; + font-weight: bold; + margin: 20px 0 10px 0; + display: block; +} + +div.toc>dl>dd>dl>dd>dl>dt { + font-weight: bold; + font-size: 20px; + margin: 10px 0 0 0; +} + +tbody.footnotes * { + border: none !important; +} + +div.footnote p { + margin: 0; + line-height: 1; +} + +div.footnote p sup { + margin-right: 6px; + vertical-align: middle; +} + +div.navheader { + border-bottom: 1px solid #CCCCCC; +} + +div.navfooter { + border-top: 1px solid #CCCCCC; +} + +.title { + margin-left: -1em; + padding-left: 1em; +} + +.title>a { + position: absolute; + visibility: hidden; + display: block; + font-size: 0.85em; + margin-top: 0.05em; + margin-left: -1em; + vertical-align: text-top; + color: black; +} + +.title>a:before { + content: "\00A7"; +} + +.title:hover>a,.title>a:hover,.title:hover>a:hover { + visibility: visible; +} + +.title:focus>a,.title>a:focus,.title:focus>a:focus { + outline: 0; +} diff --git a/spring-cloud-vault/1.1.0.RC1/ghpages.sh b/spring-cloud-vault/1.1.0.RC1/ghpages.sh new file mode 100644 index 00000000..57c5da3a --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/ghpages.sh @@ -0,0 +1,330 @@ +#!/bin/bash -x + +set -e + +# Set default props like MAVEN_PATH, ROOT_FOLDER etc. +function set_default_props() { + # The script should be executed from the root folder + ROOT_FOLDER=`pwd` + echo "Current folder is ${ROOT_FOLDER}" + + if [[ ! -e "${ROOT_FOLDER}/.git" ]]; then + echo "You're not in the root folder of the project!" + exit 1 + fi + + # Prop that will let commit the changes + COMMIT_CHANGES="no" + MAVEN_PATH=${MAVEN_PATH:-} + echo "Path to Maven is [${MAVEN_PATH}]" + REPO_NAME=${PWD##*/} + echo "Repo name is [${REPO_NAME}]" + SPRING_CLOUD_STATIC_REPO=${SPRING_CLOUD_STATIC_REPO:-git@github.com:spring-cloud/spring-cloud-static.git} + echo "Spring Cloud Static repo is [${SPRING_CLOUD_STATIC_REPO}" +} + +# Check if gh-pages exists and docs have been built +function check_if_anything_to_sync() { + git remote set-url --push origin `git config remote.origin.url | sed -e 's/^git:/https:/'` + + if ! (git remote set-branches --add origin gh-pages && git fetch -q); then + echo "No gh-pages, so not syncing" + exit 0 + fi + + if ! [ -d docs/target/generated-docs ] && ! [ "${BUILD}" == "yes" ]; then + echo "No gh-pages sources in docs/target/generated-docs, so not syncing" + exit 0 + fi +} + +function retrieve_current_branch() { + # Code getting the name of the current branch. For master we want to publish as we did until now + # http://stackoverflow.com/questions/1593051/how-to-programmatically-determine-the-current-checked-out-git-branch + # If there is a branch already passed will reuse it - otherwise will try to find it + CURRENT_BRANCH=${BRANCH} + if [[ -z "${CURRENT_BRANCH}" ]] ; then + CURRENT_BRANCH=$(git symbolic-ref -q HEAD) + CURRENT_BRANCH=${CURRENT_BRANCH##refs/heads/} + CURRENT_BRANCH=${CURRENT_BRANCH:-HEAD} + fi + echo "Current branch is [${CURRENT_BRANCH}]" + git checkout ${CURRENT_BRANCH} || echo "Failed to check the branch... continuing with the script" +} + +# Switches to the provided value of the release version. We always prefix it with `v` +function switch_to_tag() { + git checkout v${VERSION} +} + +# Build the docs if switch is on +function build_docs_if_applicable() { + if [[ "${BUILD}" == "yes" ]] ; then + ./mvnw clean install -P docs -pl docs -DskipTests + fi +} + +# Get the name of the `docs.main` property +# Get whitelisted branches - assumes that a `docs` module is available under `docs` profile +function retrieve_doc_properties() { + MAIN_ADOC_VALUE=$("${MAVEN_PATH}"mvn -q \ + -Dexec.executable="echo" \ + -Dexec.args='${docs.main}' \ + --non-recursive \ + org.codehaus.mojo:exec-maven-plugin:1.3.1:exec) + echo "Extracted 'main.adoc' from Maven build [${MAIN_ADOC_VALUE}]" + + + WHITELIST_PROPERTY=${WHITELIST_PROPERTY:-"docs.whitelisted.branches"} + WHITELISTED_BRANCHES_VALUE=$("${MAVEN_PATH}"mvn -q \ + -Dexec.executable="echo" \ + -Dexec.args="\${${WHITELIST_PROPERTY}}" \ + org.codehaus.mojo:exec-maven-plugin:1.3.1:exec \ + -P docs \ + -pl docs) + echo "Extracted '${WHITELIST_PROPERTY}' from Maven build [${WHITELISTED_BRANCHES_VALUE}]" +} + +# Stash any outstanding changes +function stash_changes() { + git diff-index --quiet HEAD && dirty=$? || (echo "Failed to check if the current repo is dirty. Assuming that it is." && dirty="1") + if [ "$dirty" != "0" ]; then git stash; fi +} + +# Switch to gh-pages branch to sync it with current branch +function add_docs_from_target() { + local DESTINATION_REPO_FOLDER + if [[ -z "${DESTINATION}" && -z "${CLONE}" ]] ; then + DESTINATION_REPO_FOLDER=${ROOT_FOLDER} + elif [[ "${CLONE}" == "yes" ]]; then + mkdir -p ${ROOT_FOLDER}/target + local clonedStatic=${ROOT_FOLDER}/target/spring-cloud-static + if [[ ! -e "${clonedStatic}/.git" ]]; then + echo "Cloning Spring Cloud Static to target" + git clone ${SPRING_CLOUD_STATIC_REPO} ${clonedStatic} && git checkout gh-pages + else + echo "Spring Cloud Static already cloned - will pull changes" + cd ${clonedStatic} && git checkout gh-pages && git pull origin gh-pages + fi + DESTINATION_REPO_FOLDER=${clonedStatic}/${REPO_NAME} + mkdir -p ${DESTINATION_REPO_FOLDER} + else + if [[ ! -e "${DESTINATION}/.git" ]]; then + echo "[${DESTINATION}] is not a git repository" + exit 1 + fi + DESTINATION_REPO_FOLDER=${DESTINATION}/${REPO_NAME} + mkdir -p ${DESTINATION_REPO_FOLDER} + echo "Destination was provided [${DESTINATION}]" + fi + cd ${DESTINATION_REPO_FOLDER} + git checkout gh-pages + git pull origin gh-pages + + # Add git branches + ################################################################### + if [[ -z "${VERSION}" ]] ; then + copy_docs_for_current_version + else + copy_docs_for_provided_version + fi + commit_changes_if_applicable +} + + +# Copies the docs by using the retrieved properties from Maven build +function copy_docs_for_current_version() { + if [[ "${CURRENT_BRANCH}" == "master" ]] ; then + echo -e "Current branch is master - will copy the current docs only to the root folder" + for f in docs/target/generated-docs/*; do + file=${f#docs/target/generated-docs/*} + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then + # Not ignored... + cp -rf $f ${ROOT_FOLDER}/ + git add -A ${ROOT_FOLDER}/$file + fi + done + COMMIT_CHANGES="yes" + else + echo -e "Current branch is [${CURRENT_BRANCH}]" + # http://stackoverflow.com/questions/29300806/a-bash-script-to-check-if-a-string-is-present-in-a-comma-separated-list-of-strin + if [[ ",${WHITELISTED_BRANCHES_VALUE}," = *",${CURRENT_BRANCH},"* ]] ; then + mkdir -p ${ROOT_FOLDER}/${CURRENT_BRANCH} + echo -e "Branch [${CURRENT_BRANCH}] is whitelisted! Will copy the current docs to the [${CURRENT_BRANCH}] folder" + for f in docs/target/generated-docs/*; do + file=${f#docs/target/generated-docs/*} + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then + # Not ignored... + # We want users to access 1.0.0.RELEASE/ instead of 1.0.0.RELEASE/spring-cloud.sleuth.html + if [[ "${file}" == "${MAIN_ADOC_VALUE}.html" ]] ; then + # We don't want to copy the spring-cloud-sleuth.html + # we want it to be converted to index.html + cp -rf $f ${ROOT_FOLDER}/${CURRENT_BRANCH}/index.html + git add -A ${ROOT_FOLDER}/${CURRENT_BRANCH}/index.html + else + cp -rf $f ${ROOT_FOLDER}/${CURRENT_BRANCH} + git add -A ${ROOT_FOLDER}/${CURRENT_BRANCH}/$file + fi + fi + done + COMMIT_CHANGES="yes" + else + echo -e "Branch [${CURRENT_BRANCH}] is not on the white list! Check out the Maven [${WHITELIST_PROPERTY}] property in + [docs] module available under [docs] profile. Won't commit any changes to gh-pages for this branch." + fi + fi +} + +# Copies the docs by using the explicitly provided version +function copy_docs_for_provided_version() { + local FOLDER=${DESTINATION_REPO_FOLDER}/${VERSION} + mkdir -p ${FOLDER} + echo -e "Current tag is [v${VERSION}] Will copy the current docs to the [${FOLDER}] folder" + for f in ${ROOT_FOLDER}/docs/target/generated-docs/*; do + file=${f#${ROOT_FOLDER}/docs/target/generated-docs/*} + copy_docs_for_branch ${file} ${FOLDER} + done + COMMIT_CHANGES="yes" + CURRENT_BRANCH="v${VERSION}" +} + +# Copies the docs from target to the provided destination +# Params: +# $1 - file from target +# $2 - destination to which copy the files +function copy_docs_for_branch() { + local file=$1 + local destination=$2 + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^${file}$; then + # Not ignored... + # We want users to access 1.0.0.RELEASE/ instead of 1.0.0.RELEASE/spring-cloud.sleuth.html + if [[ ("${file}" == "${MAIN_ADOC_VALUE}.html") || ("${file}" == "${REPO_NAME}.html") ]] ; then + # We don't want to copy the spring-cloud-sleuth.html + # we want it to be converted to index.html + cp -rf $f ${destination}/index.html + git add -A ${destination}/index.html + else + cp -rf $f ${destination} + git add -A ${destination}/$file + fi + fi +} + +function commit_changes_if_applicable() { + if [[ "${COMMIT_CHANGES}" == "yes" ]] ; then + COMMIT_SUCCESSFUL="no" + git commit -a -m "Sync docs from ${CURRENT_BRANCH} to gh-pages" && COMMIT_SUCCESSFUL="yes" || echo "Failed to commit changes" + + # Uncomment the following push if you want to auto push to + # the gh-pages branch whenever you commit to master locally. + # This is a little extreme. Use with care! + ################################################################### + if [[ "${COMMIT_SUCCESSFUL}" == "yes" ]] ; then + git push origin gh-pages + fi + fi +} + +# Switch back to the previous branch and exit block +function checkout_previous_branch() { + # If -version was provided we need to come back to root project + cd ${ROOT_FOLDER} + git checkout ${CURRENT_BRANCH} || echo "Failed to check the branch... continuing with the script" + if [ "$dirty" != "0" ]; then git stash pop; fi + exit 0 +} + +# Assert if properties have been properly passed +function assert_properties() { +echo "VERSION [${VERSION}], DESTINATION [${DESTINATION}], CLONE [${CLONE}]" +if [[ "${VERSION}" != "" && (-z "${DESTINATION}" && -z "${CLONE}") ]] ; then echo "Version was set but destination / clone was not!"; exit 1;fi +if [[ ("${DESTINATION}" != "" && "${CLONE}" != "") && -z "${VERSION}" ]] ; then echo "Destination / clone was set but version was not!"; exit 1;fi +if [[ "${DESTINATION}" != "" && "${CLONE}" == "yes" ]] ; then echo "Destination and clone was set. Pick one!"; exit 1;fi +} + +# Prints the usage +function print_usage() { +cat </` +- if the destination switch is passed (-d) then the script will check if the provided dir is a git repo and then will + switch to gh-pages of that repo and copy the generated docs to `docs//` + +USAGE: + +You can use the following options: + +-v|--version - the script will apply the whole procedure for a particular library version +-d|--destination - the root of destination folder where the docs should be copied. You have to use the full path. + E.g. point to spring-cloud-static folder. Can't be used with (-c) +-b|--build - will run the standard build process after checking out the branch +-c|--clone - will automatically clone the spring-cloud-static repo instead of providing the destination. + Obviously can't be used with (-d) + +EOF +} + + +# ========================================== +# ____ ____ _____ _____ _____ _______ +# / ____|/ ____| __ \|_ _| __ \__ __| +# | (___ | | | |__) | | | | |__) | | | +# \___ \| | | _ / | | | ___/ | | +# ____) | |____| | \ \ _| |_| | | | +# |_____/ \_____|_| \_\_____|_| |_| +# +# ========================================== + +while [[ $# > 0 ]] +do +key="$1" +case ${key} in + -v|--version) + VERSION="$2" + shift # past argument + ;; + -d|--destination) + DESTINATION="$2" + shift # past argument + ;; + -b|--build) + BUILD="yes" + ;; + -c|--clone) + CLONE="yes" + ;; + -h|--help) + print_usage + exit 0 + ;; + *) + echo "Invalid option: [$1]" + print_usage + exit 1 + ;; +esac +shift # past argument or value +done + +assert_properties +set_default_props +check_if_anything_to_sync +if [[ -z "${VERSION}" ]] ; then + retrieve_current_branch +else + switch_to_tag +fi +build_docs_if_applicable +retrieve_doc_properties +stash_changes +add_docs_from_target +checkout_previous_branch \ No newline at end of file diff --git a/spring-cloud-vault/1.1.0.RC1/images/background.png b/spring-cloud-vault/1.1.0.RC1/images/background.png new file mode 100644 index 00000000..15dca6fb Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/images/background.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/images/caution.png b/spring-cloud-vault/1.1.0.RC1/images/caution.png new file mode 100644 index 00000000..8a5e4fca Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/images/caution.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/images/important.png b/spring-cloud-vault/1.1.0.RC1/images/important.png new file mode 100644 index 00000000..ec54df65 Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/images/important.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/images/logo.png b/spring-cloud-vault/1.1.0.RC1/images/logo.png new file mode 100644 index 00000000..ade2ce6e Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/images/logo.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/images/note.png b/spring-cloud-vault/1.1.0.RC1/images/note.png new file mode 100644 index 00000000..88d997b1 Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/images/note.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/images/sts_exception.png b/spring-cloud-vault/1.1.0.RC1/images/sts_exception.png new file mode 100644 index 00000000..8607c38a Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/images/sts_exception.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/images/tip.png b/spring-cloud-vault/1.1.0.RC1/images/tip.png new file mode 100644 index 00000000..6530abb4 Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/images/tip.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/images/warning.png b/spring-cloud-vault/1.1.0.RC1/images/warning.png new file mode 100644 index 00000000..0d5b5244 Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/images/warning.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/images/web-selected.png b/spring-cloud-vault/1.1.0.RC1/images/web-selected.png new file mode 100644 index 00000000..aa6b2da6 Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/images/web-selected.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/index.html b/spring-cloud-vault/1.1.0.RC1/index.html new file mode 100644 index 00000000..4a737bb3 --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/index.html @@ -0,0 +1,117 @@ + + + + + + + +spring-cloud-vault + + + + + + + + +
+
+
+
+

1.1.0.RC1

+
+
+
+
+

Pick The Documentation Option

+
+
+ +
+
+
+
+ + + + + \ No newline at end of file diff --git a/spring-cloud-vault/1.1.0.RC1/multi/css/highlight.css b/spring-cloud-vault/1.1.0.RC1/multi/css/highlight.css new file mode 100644 index 00000000..ffefef72 --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/multi/css/highlight.css @@ -0,0 +1,35 @@ +/* + code highlight CSS resemblign the Eclipse IDE default color schema + @author Costin Leau +*/ + +.hl-keyword { + color: #7F0055; + font-weight: bold; +} + +.hl-comment { + color: #3F5F5F; + font-style: italic; +} + +.hl-multiline-comment { + color: #3F5FBF; + font-style: italic; +} + +.hl-tag { + color: #3F7F7F; +} + +.hl-attribute { + color: #7F007F; +} + +.hl-value { + color: #2A00FF; +} + +.hl-string { + color: #2A00FF; +} \ No newline at end of file diff --git a/spring-cloud-vault/1.1.0.RC1/multi/css/manual-multipage.css b/spring-cloud-vault/1.1.0.RC1/multi/css/manual-multipage.css new file mode 100644 index 00000000..0c484531 --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/multi/css/manual-multipage.css @@ -0,0 +1,9 @@ +@IMPORT url("manual.css"); + +body.firstpage { + background: url("../images/background.png") no-repeat center top; +} + +div.part h1 { + border-top: none; +} diff --git a/spring-cloud-vault/1.1.0.RC1/multi/css/manual-singlepage.css b/spring-cloud-vault/1.1.0.RC1/multi/css/manual-singlepage.css new file mode 100644 index 00000000..4a7fd140 --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/multi/css/manual-singlepage.css @@ -0,0 +1,6 @@ +@IMPORT url("manual.css"); + +body { + background: url("../images/background.png") no-repeat center top; +} + diff --git a/spring-cloud-vault/1.1.0.RC1/multi/css/manual.css b/spring-cloud-vault/1.1.0.RC1/multi/css/manual.css new file mode 100644 index 00000000..0ecbe2e8 --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/multi/css/manual.css @@ -0,0 +1,344 @@ +@IMPORT url("highlight.css"); + +html { + padding: 0pt; + margin: 0pt; +} + +body { + color: #333333; + margin: 15px 30px; + font-family: Helvetica, Arial, Freesans, Clean, Sans-serif; + line-height: 1.6; + -webkit-font-smoothing: antialiased; +} + +code { + font-size: 16px; + font-family: Consolas, "Liberation Mono", Courier, monospace; +} + +:not(a)>code { + color: #6D180B; +} + +:not(pre)>code { + background-color: #F2F2F2; + border: 1px solid #CCCCCC; + border-radius: 4px; + padding: 1px 3px 0; + text-shadow: none; + white-space: nowrap; +} + +body>*:first-child { + margin-top: 0 !important; +} + +div { + margin: 0pt; +} + +hr { + border: 1px solid #CCCCCC; + background: #CCCCCC; +} + +h1,h2,h3,h4,h5,h6 { + color: #000000; + cursor: text; + font-weight: bold; + margin: 30px 0 10px; + padding: 0; +} + +h1,h2,h3 { + margin: 40px 0 10px; +} + +h1 { + margin: 70px 0 30px; + padding-top: 20px; +} + +div.part h1 { + border-top: 1px dotted #CCCCCC; +} + +h1,h1 code { + font-size: 32px; +} + +h2,h2 code { + font-size: 24px; +} + +h3,h3 code { + font-size: 20px; +} + +h4,h1 code,h5,h5 code,h6,h6 code { + font-size: 18px; +} + +div.book,div.chapter,div.appendix,div.part,div.preface { + min-width: 300px; + max-width: 1200px; + margin: 0 auto; +} + +p.releaseinfo { + font-weight: bold; + margin-bottom: 40px; + margin-top: 40px; +} + +div.authorgroup { + line-height: 1; +} + +p.copyright { + line-height: 1; + margin-bottom: -5px; +} + +.legalnotice p { + font-style: italic; + font-size: 14px; + line-height: 1; +} + +div.titlepage+p,div.titlepage+p { + margin-top: 0; +} + +pre { + line-height: 1.0; + color: black; +} + +a { + color: #4183C4; + text-decoration: none; +} + +p { + margin: 15px 0; + text-align: left; +} + +ul,ol { + padding-left: 30px; +} + +li p { + margin: 0; +} + +div.table { + margin: 1em; + padding: 0.5em; + text-align: center; +} + +div.table table,div.informaltable table { + display: table; + width: 100%; +} + +div.table td { + padding-left: 7px; + padding-right: 7px; +} + +.sidebar { + line-height: 1.4; + padding: 0 20px; + background-color: #F8F8F8; + border: 1px solid #CCCCCC; + border-radius: 3px 3px 3px 3px; +} + +.sidebar p.title { + color: #6D180B; +} + +pre.programlisting,pre.screen { + font-size: 15px; + padding: 6px 10px; + background-color: #F8F8F8; + border: 1px solid #CCCCCC; + border-radius: 3px 3px 3px 3px; + clear: both; + overflow: auto; + line-height: 1.4; + font-family: Consolas, "Liberation Mono", Courier, monospace; +} + +table { + border-collapse: collapse; + border-spacing: 0; + border: 1px solid #DDDDDD !important; + border-radius: 4px !important; + border-collapse: separate !important; + line-height: 1.6; +} + +table thead { + background: #F5F5F5; +} + +table tr { + border: none; + border-bottom: none; +} + +table th { + font-weight: bold; +} + +table th,table td { + border: none !important; + padding: 6px 13px; +} + +table tr:nth-child(2n) { + background-color: #F8F8F8; +} + +td p { + margin: 0 0 15px 0; +} + +div.table-contents td p { + margin: 0; +} + +div.important *,div.note *,div.tip *,div.warning *,div.navheader *,div.navfooter *,div.calloutlist * + { + border: none !important; + background: none !important; + margin: 0; +} + +div.important p,div.note p,div.tip p,div.warning p { + color: #6F6F6F; + line-height: 1.6; +} + +div.important code,div.note code,div.tip code,div.warning code { + background-color: #F2F2F2 !important; + border: 1px solid #CCCCCC !important; + border-radius: 4px !important; + padding: 1px 3px 0 !important; + text-shadow: none !important; + white-space: nowrap !important; +} + +.note th,.tip th,.warning th { + display: none; +} + +.note tr:first-child td,.tip tr:first-child td,.warning tr:first-child td + { + border-right: 1px solid #CCCCCC !important; + padding-top: 10px; +} + +div.calloutlist p,div.calloutlist td { + padding: 0; + margin: 0; +} + +div.calloutlist>table>tbody>tr>td:first-child { + padding-left: 10px; + width: 30px !important; +} + +div.important,div.note,div.tip,div.warning { + margin-left: 0px !important; + margin-right: 20px !important; + margin-top: 20px; + margin-bottom: 20px; + padding-top: 10px; + padding-bottom: 10px; +} + +div.toc { + line-height: 1.2; +} + +dl,dt { + margin-top: 1px; + margin-bottom: 0; +} + +div.toc>dl>dt { + font-size: 32px; + font-weight: bold; + margin: 30px 0 10px 0; + display: block; +} + +div.toc>dl>dd>dl>dt { + font-size: 24px; + font-weight: bold; + margin: 20px 0 10px 0; + display: block; +} + +div.toc>dl>dd>dl>dd>dl>dt { + font-weight: bold; + font-size: 20px; + margin: 10px 0 0 0; +} + +tbody.footnotes * { + border: none !important; +} + +div.footnote p { + margin: 0; + line-height: 1; +} + +div.footnote p sup { + margin-right: 6px; + vertical-align: middle; +} + +div.navheader { + border-bottom: 1px solid #CCCCCC; +} + +div.navfooter { + border-top: 1px solid #CCCCCC; +} + +.title { + margin-left: -1em; + padding-left: 1em; +} + +.title>a { + position: absolute; + visibility: hidden; + display: block; + font-size: 0.85em; + margin-top: 0.05em; + margin-left: -1em; + vertical-align: text-top; + color: black; +} + +.title>a:before { + content: "\00A7"; +} + +.title:hover>a,.title>a:hover,.title:hover>a:hover { + visibility: visible; +} + +.title:focus>a,.title>a:focus,.title:focus>a:focus { + outline: 0; +} diff --git a/spring-cloud-vault/1.1.0.RC1/multi/images/background.png b/spring-cloud-vault/1.1.0.RC1/multi/images/background.png new file mode 100644 index 00000000..15dca6fb Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/multi/images/background.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/multi/images/caution.png b/spring-cloud-vault/1.1.0.RC1/multi/images/caution.png new file mode 100644 index 00000000..8a5e4fca Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/multi/images/caution.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/multi/images/important.png b/spring-cloud-vault/1.1.0.RC1/multi/images/important.png new file mode 100644 index 00000000..ec54df65 Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/multi/images/important.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/multi/images/logo.png b/spring-cloud-vault/1.1.0.RC1/multi/images/logo.png new file mode 100644 index 00000000..ade2ce6e Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/multi/images/logo.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/multi/images/note.png b/spring-cloud-vault/1.1.0.RC1/multi/images/note.png new file mode 100644 index 00000000..88d997b1 Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/multi/images/note.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/multi/images/sts_exception.png b/spring-cloud-vault/1.1.0.RC1/multi/images/sts_exception.png new file mode 100644 index 00000000..8607c38a Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/multi/images/sts_exception.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/multi/images/tip.png b/spring-cloud-vault/1.1.0.RC1/multi/images/tip.png new file mode 100644 index 00000000..6530abb4 Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/multi/images/tip.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/multi/images/warning.png b/spring-cloud-vault/1.1.0.RC1/multi/images/warning.png new file mode 100644 index 00000000..0d5b5244 Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/multi/images/warning.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/multi/images/web-selected.png b/spring-cloud-vault/1.1.0.RC1/multi/images/web-selected.png new file mode 100644 index 00000000..aa6b2da6 Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/multi/images/web-selected.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/multi/multi__client_side_usage.html b/spring-cloud-vault/1.1.0.RC1/multi/multi__client_side_usage.html new file mode 100644 index 00000000..600cbfba --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/multi/multi__client_side_usage.html @@ -0,0 +1,67 @@ + + + 2. Client Side Usage
2. Client Side Usage
Prev   Next

2. 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:

Example 2.1. pom.xml

<parent>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-parent</artifactId>
+    <version>1.5.4.RELEASE</version>
+    <relativePath /> <!-- lookup parent from repository -->
+</parent>
+
+<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-starter-vault-config</artifactId>
+        <version>1.1.0.RC1</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:

@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 bootstrap.properties (like application.properties but for +the bootstrap phase of an application context), e.g.

Example 2.2. bootstrap.yml

spring.cloud.vault:
+    host: localhost
+    port: 8200
+    scheme: https
+    uri: https://localhost:8200
+    connection-timeout: 5000
+    read-timeout: 15000
+    config:
+        order: -10

  • 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
  • config.order sets the order for the property source

Enabling further integrations requires additional dependencies and +configuration. Depending on how you have set up Vault you might need +additional configuration like +SSL and +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 health.vault.enabled (default true).

2.1 Authentication

Vault requires an authentication mechanism to authorize client requests.

Spring Cloud Vault supports multiple authentication mechanisms to authenticate applications with Vault.

For a quickstart, use the root token printed by the Vault initialization.

Example 2.3. bootstrap.yml

spring.cloud.vault:
+    token: 19aefa97-cccc-bbbb-aaaa-225940e63d76

[Warning]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.

Prev   Next
1. Quick Start Home 3. Authentication methods
\ No newline at end of file diff --git a/spring-cloud-vault/1.1.0.RC1/multi/multi__quick_start.html b/spring-cloud-vault/1.1.0.RC1/multi/multi__quick_start.html new file mode 100644 index 00000000..bac5384d --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/multi/multi__quick_start.html @@ -0,0 +1,37 @@ + + + 1. Quick Start
1. Quick Start
Prev   Next

1. Quick Start

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 7 and a properly configured JAVA_HOME environment variable

Install Vault

$ src/test/bash/install_vault.sh

Create SSL certificates for Vault

$ src/test/bash/create_certificates.sh
[Note]Note

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.

Start Vault server

$ src/test/bash/local_run_vault.sh

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]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.

$ export VAULT_ADDR="https://localhost:8200"
+$ export VAULT_SKIP_VERIFY=true # Don't do this for production
+$ vault init

You should see something like:

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.

$ vault unseal (Key 1)
+$ vault unseal (Key 2)
+$ vault 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.

Prev   Next
 Home 2. Client Side Usage
\ No newline at end of file diff --git a/spring-cloud-vault/1.1.0.RC1/multi/multi__service_registry_configuration.html b/spring-cloud-vault/1.1.0.RC1/multi/multi__service_registry_configuration.html new file mode 100644 index 00000000..0631a3f7 --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/multi/multi__service_registry_configuration.html @@ -0,0 +1,17 @@ + + + 7. Service Registry Configuration
7. Service Registry Configuration
Prev   Next

7. Service Registry Configuration

You can use a DiscoveryClient (such as from Spring Cloud Consul) to locate +a Vault server by setting spring.cloud.vault.discovery.enabled=true (default false). +The net result of that is that your apps need a bootstrap.yml (or an environment variable) +with the appropriate discovery configuration. +The benefit is that the Vault can change its co-ordinates, as long as the discovery service +is a fixed point. The default service id is vault but you can change that on the client with +spring.cloud.vault.discovery.serviceId.

The discovery client implementations all support some kind of metadata map +(e.g. for Eureka we have eureka.instance.metadataMap). Some additional properties of the service +may need to be configured in its service registration metadata so that clients can connect +correctly. Service registries that do not provide details about transport layer security +need to provide a scheme metadata entry to be set either to https or http. +If no scheme is configured and the service is not exposed as secure service, then +configuration defaults to spring.cloud.vault.scheme which is https when it’s not set.

spring.cloud.vault.discovery:
+    enabled: true
+    service-id: my-vault-service
Prev   Next
6. Configure PropertySourceLocator behavior Home 8. Vault Client Fail Fast
\ No newline at end of file diff --git a/spring-cloud-vault/1.1.0.RC1/multi/multi_pr01.html b/spring-cloud-vault/1.1.0.RC1/multi/multi_pr01.html new file mode 100644 index 00000000..7fad193c --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/multi/multi_pr01.html @@ -0,0 +1,3 @@ + + +
Prev   Next

© 2016-2017 The original authors.

[Note]Note

Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

Spring Cloud Vault Config provides client-side support for externalized configuration in a distributed system. With HashiCorp’s Vault you have a central place to manage external secret properties for applications across all environments. Vault can manage static and dynamic secrets such as username/password for remote applications/resources and provide credentials for external services such as MySQL, PostgreSQL, Apache Cassandra, MongoDB, Consul, AWS and more.

Prev   Next
Spring Cloud Vault Home 1. Quick Start
\ No newline at end of file diff --git a/spring-cloud-vault/1.1.0.RC1/multi/multi_spring-cloud-vault.html b/spring-cloud-vault/1.1.0.RC1/multi/multi_spring-cloud-vault.html new file mode 100644 index 00000000..a6a2b6ad --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/multi/multi_spring-cloud-vault.html @@ -0,0 +1,3 @@ + + + Spring Cloud Vault
Spring Cloud Vault
   Next

Spring Cloud Vault

Table of Contents

1. Quick Start
2. Client Side Usage
2.1. Authentication
3. Authentication methods
3.1. Token authentication
3.2. AppId authentication
3.2.1. Custom UserId
3.3. AppRole authentication
3.4. AWS-EC2 authentication
3.5. TLS certificate authentication
3.6. Cubbyhole authentication
4. Secret Backends
4.1. Generic Backend
4.2. Consul
4.3. RabbitMQ
4.4. AWS
5. Database backends
5.1. Apache Cassandra
5.2. MongoDB
5.3. MySQL
5.4. PostgreSQL
6. Configure PropertySourceLocator behavior
7. Service Registry Configuration
8. Vault Client Fail Fast
9. Vault Client SSL configuration
10. Lease lifecycle management (renewal and revocation)
   Next
   
\ No newline at end of file diff --git a/spring-cloud-vault/1.1.0.RC1/multi/multi_vault-lease-renewal.html b/spring-cloud-vault/1.1.0.RC1/multi/multi_vault-lease-renewal.html new file mode 100644 index 00000000..e5fcbbb8 --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/multi/multi_vault-lease-renewal.html @@ -0,0 +1,22 @@ + + + 10. Lease lifecycle management (renewal and revocation)
10. Lease lifecycle management (renewal and revocation)
Prev   

10. Lease lifecycle management (renewal and revocation)

With every secret, Vault creates a lease: +metadata containing information such as a time duration, +renewability, and more.

Vault promises that the data will be valid for the given duration, +or Time To Live (TTL). Once the lease is expired, Vault can +revoke the data, and the consumer of the secret can no longer +be certain that it is valid.

Spring Cloud Vault maintains a lease lifecycle beyond +the creation of login tokens and secrets. That said, +login tokens and secrets associated with a lease +are scheduled for renewal just before the lease expires +until terminal expiry. +Application shutdown revokes obtained login tokens and renewable +leases.

Secret service and database backends (such as MongoDB or MySQL) +usually generate a renewable lease so generated credentials will +be disabled on application shutdown.

[Note]Note

Static tokens are not renewed or revoked.

Lease renewal and revocation is enabled by default and can +be disabled by setting spring.cloud.vault.config.lifecycle.enabled +to false. This is not recommended as leases can expire and +Spring Cloud Vault cannot longer access Vault or services +using generated credentials and valid credentials remain active +after application shutdown.

spring.cloud.vault:
+    config.lifecycle.enabled: true

See also: Vault Documentation: Lease, Renew, and Revoke

Prev   
9. Vault Client SSL configuration Home 
\ No newline at end of file diff --git a/spring-cloud-vault/1.1.0.RC1/multi/multi_vault.config.authentication.html b/spring-cloud-vault/1.1.0.RC1/multi/multi_vault.config.authentication.html new file mode 100644 index 00000000..eb38c56a --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/multi/multi_vault.config.authentication.html @@ -0,0 +1,113 @@ + + + 3. Authentication methods
3. Authentication methods
Prev   Next

3. Authentication methods

Different organizations have different requirements for security +and authentication. Vault reflects that need by shipping multiple authentication +methods. Spring Cloud Vault supports token and AppId authentication.

3.1 Token authentication

Tokens are the core method for authentication within Vault. +Token authentication requires a static token to be provided using the +Bootstrap Application Context.

[Note]Note

Token authentication is the default authentication method. +If a token is disclosed an unintended party gains access to Vault and +can access secrets for the intended client.

Example 3.1. bootstrap.yml

spring.cloud.vault:
+    authentication: TOKEN
+    token: 00000000-0000-0000-0000-000000000000

  • authentication setting this value to TOKEN selects the Token +authentication method
  • token sets the static token to use

See also: Vault Documentation: Tokens

3.2 AppId authentication

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 Cloud Vault Config 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.

Example 3.2. bootstrap.yml using SHA256 IP-Address UserId’s

spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: IP_ADDRESS

  • authentication setting this value to APPID selects the AppId +authentication method
  • app-id-path sets the path of the AppId mount to use
  • user-id sets the UserId method. Possible values are IP_ADDRESS, +MAC_ADDRESS or a class name implementing a custom AppIdUserIdMechanism

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

$ echo -n 192.168.99.1 | sha256sum
[Note]Note

Including the line break of echo leads to a different hash value +so make sure to include the -n flag.

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).

Example 3.3. bootstrap.yml using SHA256 Mac-Address UserId’s

spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: MAC_ADDRESS
+        network-interface: eth0

  • network-interface sets network interface to obtain the physical address

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

$ echo -n 0AFEDE1234AC | sha256sum
[Note]Note

The Mac address is specified uppercase and without colons. +Including the line break of echo leads to a different hash value +so make sure to include the -n flag.

3.2.1 Custom UserId

The UserId generation is an open mechanism. You can set +spring.cloud.vault.app-id.user-id to any string and the configured +value will be used as static UserId.

A more advanced approach lets you set spring.cloud.vault.app-id.user-id to a +classname. This class must be on your classpath and must implement +the org.springframework.cloud.vault.AppIdUserIdMechanism interface +and the createUserId method. Spring Cloud Vault will obtain the UserId +by calling createUserId each time it authenticates using AppId to +obtain a token.

Example 3.4. bootstrap.yml

spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: com.examlple.MyUserIdMechanism

Example 3.5. MyUserIdMechanism.java

public class MyUserIdMechanism implements AppIdUserIdMechanism {
+
+  @Override
+  public String createUserId() {
+    String userId = ...
+    return userId;
+  }
+}

See also: Vault Documentation: Using the App ID auth backend

3.3 AppRole authentication

AppRole is intended for machine +authentication, like the deprecated (since Vault 0.6.1) Section 3.2, “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 (push or pull mode).

RoleId and optionally SecretId must be provided by configuration, +Spring Vault will not look up these or create a custom SecretId.

Example 3.6. bootstrap.yml with AppRole authentication properties

spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52

  • role-id sets the RoleId.

Example 3.7. bootstrap.yml with all AppRole authentication properties

spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
+        secret-id: 1696536f-1976-73b1-b241-0b4213908d39
+        app-auth-path: approle

  • role-id sets the RoleId.
  • secret-id sets the SecretId. SecretId can be omitted if AppRole is configured without requiring SecretId (See bind_secret_id)
  • approle-path sets the path of the approle authentication mount to use

See also: Vault Documentation: Using the AppRole auth backend

3.4 AWS-EC2 authentication

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.

Example 3.8. bootstrap.yml using AWS-EC2 Authentication

spring.cloud.vault:
+    authentication: AWS_EC2

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 Cloud 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. +You can configure a static nonce with spring.cloud.vault.aws-ec2.nonce.

AWS-EC2 authentication roles are optional and default to the AMI. +You can configure the authentication role by setting the +spring.cloud.vault.aws-ec2.role property.

Example 3.9. bootstrap.yml with configured role

spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server

Example 3.10. bootstrap.yml with all AWS EC2 authentication properties

spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server
+        aws-ec2-path: aws-ec2
+        identity-document: http://...
+        nonce: my-static-nonce

  • authentication setting this value to AWS_EC2 selects the AWS EC2 +authentication method
  • role sets the role name of the AWS EC2 role definition
  • aws-ec2-path sets the path of the AWS EC2 mount to use
  • identity-document sets URL of the PKCS#7 AWS EC2 identity document
  • nonce used for AWS-EC2 authentication. An empty nonce defaults to nonce generation

See also: Vault Documentation: Using the aws-ec2 auth backend

3.5 TLS certificate authentication

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:

  1. Use SSL, see Chapter 9, Vault Client SSL configuration
  2. Configure a Java Keystore that contains the client +certificate and the private key
  3. Set the spring.cloud.vault.authentication to CERT

Example 3.11. bootstrap.yml

spring.cloud.vault:
+    authentication: CERT
+    ssl:
+        key-store: classpath:keystore.jks
+        key-store-password: changeit
+        cert-auth-path: cert

See also: Vault Documentation: Using the Cert auth backend

3.6 Cubbyhole authentication

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 will be retrieved from a wrapped +response stored at /cubbyhole/response.

Creating a wrapped token

[Note]Note

Response Wrapping for token creation requires Vault 0.6.0 or higher.

Example 3.12. Crating and storing tokens

$ vault token-create -wrap-ttl="10m"
+Key                            Value
+---                            -----
+wrapping_token:                397ccb93-ff6c-b17b-9389-380b01ca2645
+wrapping_token_ttl:            0h10m0s
+wrapping_token_creation_time:  2016-09-18 20:29:48.652957077 +0200 CEST
+wrapped_accessor:              46b6aebb-187f-932a-26d7-4f3d86a68319

Example 3.13. bootstrap.yml

spring.cloud.vault:
+    authentication: CUBBYHOLE
+    token: 397ccb93-ff6c-b17b-9389-380b01ca2645

See also:

Prev   Next
2. Client Side Usage Home 4. Secret Backends
\ No newline at end of file diff --git a/spring-cloud-vault/1.1.0.RC1/multi/multi_vault.config.backends.configurer.html b/spring-cloud-vault/1.1.0.RC1/multi/multi_vault.config.backends.configurer.html new file mode 100644 index 00000000..feecb534 --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/multi/multi_vault.config.backends.configurer.html @@ -0,0 +1,22 @@ + + + 6. Configure PropertySourceLocator behavior
6. Configure PropertySourceLocator behavior
Prev   Next

6. Configure PropertySourceLocator behavior

Spring Cloud Vault uses property-based configuration to create PropertySources +for generic and discovered secret backends.

Discovered backends provide VaultSecretBackendDescriptor beans to describe the configuration +state to use secret backend as PropertySource. A SecretBackendMetadataFactory is required +to create a SecretBackendMetadata object which contains path, name and property transformation +configuration.

SecretBackendMetadata is used to back a particular PropertySource.

You can register an arbitrary number of beans implementing VaultConfigurer for customization. +Default generic and discovered backend registration is disabled if Spring Cloud Vault discovers +at least one VaultConfigurer bean. You can however enable default registration with +SecretBackendConfigurer.registerDefaultGenericSecretBackends() and SecretBackendConfigurer.registerDefaultDiscoveredSecretBackends().

public class CustomizationBean implements VaultConfigurer {
+
+    @Override
+    public void addSecretBackends(SecretBackendConfigurer configurer) {
+
+        configurer.add("secret/my-application");
+
+        configurer.registerDefaultGenericSecretBackends(false);
+        configurer.registerDefaultDiscoveredSecretBackends(true);
+    }
+}
[Note]Note

All customization is required to happen in the bootstrap context. Add your configuration +classes to META-INF/spring.factories at org.springframework.cloud.bootstrap.BootstrapConfiguration +in your application.

Prev   Next
5. Database backends Home 7. Service Registry Configuration
\ No newline at end of file diff --git a/spring-cloud-vault/1.1.0.RC1/multi/multi_vault.config.backends.database-backends.html b/spring-cloud-vault/1.1.0.RC1/multi/multi_vault.config.backends.database-backends.html new file mode 100644 index 00000000..1c85ebc8 --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/multi/multi_vault.config.backends.database-backends.html @@ -0,0 +1,76 @@ + + + 5. Database backends
5. Database backends
Prev   Next

5. Database backends

Vault supports several database secret backends to generate database +credentials dynamically based on configured roles. This means +services that need to access a database no longer need to configure +credentials: they can request them from Vault, and use Vault’s leasing +mechanism to more easily roll keys.

Spring Cloud Vault integrates with these backends:

Using a database secret backend requires to enable the +backend in the configuration and the spring-cloud-vault-config-databases +dependency.

Vault ships since 0.7.1 with a dedicated database secret backend that allows +database integration via plugins. You can use that specific backend by adapting +one of the JDBC database properties above. Make sure to specify the appropriate +backend path, e.g. spring.cloud.vault.mysql.role.backend=database.

Example 5.1. pom.xml

<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-databases</artifactId>
+        <version>1.1.0.RC1</version>
+    </dependency>
+</dependencies>

[Note]Note

Enabling multiple JDBC-compliant databases will generate credentials +and store them by default in the same property keys hence property names for +JDBC secrets need to be configured separately.

5.1 Apache Cassandra

Spring Cloud Vault can obtain credentials for Apache Cassandra. +The integration can be enabled by setting +spring.cloud.vault.cassandra.enabled=true (default false) and +providing the role name with spring.cloud.vault.cassandra.role=….

Username and password are stored in spring.data.cassandra.username +and spring.data.cassandra.password so using Spring Boot will pick +up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.cassandra.username-property and +spring.cloud.vault.cassandra.password-property.

spring.cloud.vault:
+    cassandra:
+        enabled: true
+        role: readonly
+        backend: cassandra
+        username-property: spring.data.cassandra.username
+        password-property: spring.data.cassandra.username
  • enabled setting this value to true enables the Cassandra backend config usage
  • role sets the role name of the Cassandra role definition
  • backend sets the path of the Cassandra mount to use
  • username-property sets the property name in which the Cassandra username is stored
  • password-property sets the property name in which the Cassandra password is stored

See also: Vault Documentation: Setting up Apache Cassandra with Vault

5.2 MongoDB

Spring Cloud Vault can obtain credentials for MongoDB. +The integration can be enabled by setting +spring.cloud.vault.mongodb.enabled=true (default false) and +providing the role name with spring.cloud.vault.mongodb.role=….

Username and password are stored in spring.data.mongodb.username +and spring.data.mongodb.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mongodb.username-property and +spring.cloud.vault.mongodb.password-property.

spring.cloud.vault:
+    mongodb:
+        enabled: true
+        role: readonly
+        backend: mongodb
+        username-property: spring.data.mongodb.username
+        password-property: spring.data.mongodb.password
  • enabled setting this value to true enables the MongodB backend config usage
  • role sets the role name of the MongoDB role definition
  • backend sets the path of the MongoDB mount to use
  • username-property sets the property name in which the MongoDB username is stored
  • password-property sets the property name in which the MongoDB password is stored

See also: Vault Documentation: Setting up MongoDB with Vault

5.3 MySQL

Spring Cloud Vault can obtain credentials for MySQL. +The integration can be enabled by setting +spring.cloud.vault.mysql.enabled=true (default false) and +providing the role name with spring.cloud.vault.mysql.role=….

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mysql.username-property and +spring.cloud.vault.mysql.password-property.

spring.cloud.vault:
+    mysql:
+        enabled: true
+        role: readonly
+        backend: mysql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
  • enabled setting this value to true enables the MySQL backend config usage
  • role sets the role name of the MySQL role definition
  • backend sets the path of the MySQL mount to use
  • username-property sets the property name in which the MySQL username is stored
  • password-property sets the property name in which the MySQL password is stored

See also: Vault Documentation: Setting up MySQL with Vault

5.4 PostgreSQL

Spring Cloud Vault can obtain credentials for PostgreSQL. +The integration can be enabled by setting +spring.cloud.vault.postgresql.enabled=true (default false) and +providing the role name with spring.cloud.vault.postgresql.role=….

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.postgresql.username-property and +spring.cloud.vault.postgresql.password-property.

spring.cloud.vault:
+    postgresql:
+        enabled: true
+        role: readonly
+        backend: postgresql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
  • enabled setting this value to true enables the PostgreSQL backend config usage
  • role sets the role name of the PostgreSQL role definition
  • backend sets the path of the PostgreSQL mount to use
  • username-property sets the property name in which the PostgreSQL username is stored
  • password-property sets the property name in which the PostgreSQL password is stored

See also: Vault Documentation: Setting up PostgreSQL with Vault

Prev   Next
4. Secret Backends Home 6. Configure PropertySourceLocator behavior
\ No newline at end of file diff --git a/spring-cloud-vault/1.1.0.RC1/multi/multi_vault.config.backends.html b/spring-cloud-vault/1.1.0.RC1/multi/multi_vault.config.backends.html new file mode 100644 index 00000000..c70c74c7 --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/multi/multi_vault.config.backends.html @@ -0,0 +1,79 @@ + + + 4. Secret Backends
4. Secret Backends
Prev   Next

4. Secret Backends

4.1 Generic Backend

Spring Cloud Vault supports at the basic level the generic secret +backend. The generic secret backend allows storage of arbitrary +values as key-value store. A single context can store one or many +key-value tuples. Contexts can be organized hierarchically. +Spring Cloud Vault allows using the Application name +and a default context name (application) in combination with active +profiles.

/secret/{application}/{profile}
+/secret/{application}
+/secret/{default-context}/{profile}
+/secret/{default-context}

The application name is determined by the properties:

  • spring.cloud.vault.generic.application-name
  • spring.cloud.vault.application-name
  • spring.application.name

Secrets can be obtained from other folders within the generic backend by adding their +paths to the application name, separated by commas. For example, given the application +name usefulapp,mysql1,projectx/aws, each of these folders will be used:

  • /secret/usefulapp
  • /secret/mysql1
  • /secret/projectx/aws

Spring Cloud Vault adds all active profiles to the list of possible context paths. +No active profiles will skip accessing contexts with a profile name.

Properties are exposed like they are stored (i.e. without additional prefixes).

spring.cloud.vault:
+    generic:
+        enabled: true
+        backend: secret
+        profile-separator: '/'
+        default-context: application
+        application-name: my-app
  • enabled setting this value to false disables the secret backend +config usage
  • backend sets the path of the secret mount to use
  • default-context sets the context name used by all applications
  • application-name overrides the application name for use in the generic backend
  • profile-separator separates the profile name from the context in +property sources with profiles

See also: Vault Documentation: Using the generic secret backend

4.2 Consul

Spring Cloud Vault can obtain credentials for HashiCorp Consul. +The Consul integration requires the spring-cloud-vault-config-consul +dependency.

Example 4.1. pom.xml

<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-consul</artifactId>
+        <version>1.1.0.RC1</version>
+    </dependency>
+</dependencies>

The integration can be enabled by setting +spring.cloud.vault.consul.enabled=true (default false) and +providing the role name with spring.cloud.vault.consul.role=….

The obtained token is stored in spring.cloud.consul.token +so using Spring Cloud Consul can pick up the generated +credentials without further configuration. You can configure +the property name by setting spring.cloud.vault.consul.token-property.

spring.cloud.vault:
+    consul:
+        enabled: true
+        role: readonly
+        backend: consul
+        token-property: spring.cloud.consul.token
  • enabled setting this value to true enables the Consul backend config usage
  • role sets the role name of the Consul role definition
  • backend sets the path of the Consul mount to use
  • token-property sets the property name in which the Consul ACL token is stored

See also: Vault Documentation: Setting up Consul with Vault

4.3 RabbitMQ

Spring Cloud Vault can obtain credentials for RabbitMQ.

The RabbitMQ integration requires the spring-cloud-vault-config-rabbitmq +dependency.

Example 4.2. pom.xml

<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-rabbitmq</artifactId>
+        <version>1.1.0.RC1</version>
+    </dependency>
+</dependencies>

The integration can be enabled by setting +spring.cloud.vault.rabbitmq.enabled=true (default false) +and providing the role name with spring.cloud.vault.rabbitmq.role=….

Username and password are stored in spring.rabbitmq.username +and spring.rabbitmq.password so using Spring Boot will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.rabbitmq.username-property and +spring.cloud.vault.rabbitmq.password-property.

spring.cloud.vault:
+    rabbitmq:
+        enabled: true
+        role: readonly
+        backend: rabbitmq
+        username-property: spring.rabbitmq.username
+        password-property: spring.rabbitmq.password
  • enabled setting this value to true enables the RabbitMQ backend config usage
  • role sets the role name of the RabbitMQ role definition
  • backend sets the path of the RabbitMQ mount to use
  • username-property sets the property name in which the RabbitMQ username is stored
  • password-property sets the property name in which the RabbitMQ password is stored

See also: Vault Documentation: Setting up RabbitMQ with Vault

4.4 AWS

Spring Cloud Vault can obtain credentials for AWS.

The AWS integration requires the spring-cloud-vault-config-aws +dependency.

Example 4.3. pom.xml

<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-aws</artifactId>
+        <version>1.1.0.RC1</version>
+    </dependency>
+</dependencies>

The integration can be enabled by setting +spring.cloud.vault.aws=true (default false) +and providing the role name with spring.cloud.vault.aws.role=….

The access key and secret key are stored in cloud.aws.credentials.accessKey +and cloud.aws.credentials.secretKey so using Spring Cloud AWS will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.aws.access-key-property and +spring.cloud.vault.aws.secret-key-property.

spring.cloud.vault:
+    aws:
+        enabled: true
+        role: readonly
+        backend: aws
+        access-key-property: cloud.aws.credentials.accessKey
+        secret-key-property: cloud.aws.credentials.secretKey
  • enabled setting this value to true enables the AWS backend config usage
  • role sets the role name of the AWS role definition
  • backend sets the path of the AWS mount to use
  • access-key-property sets the property name in which the AWS access key is stored
  • secret-key-property sets the property name in which the AWS secret key is stored

See also: Vault Documentation: Setting up AWS with Vault

Prev   Next
3. Authentication methods Home 5. Database backends
\ No newline at end of file diff --git a/spring-cloud-vault/1.1.0.RC1/multi/multi_vault.config.fail-fast.html b/spring-cloud-vault/1.1.0.RC1/multi/multi_vault.config.fail-fast.html new file mode 100644 index 00000000..690bfc29 --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/multi/multi_vault.config.fail-fast.html @@ -0,0 +1,8 @@ + + + 8. Vault Client Fail Fast
8. Vault Client Fail Fast
Prev   Next

8. Vault Client Fail Fast

In some cases, it may be desirable to fail startup of a service if +it cannot connect to the Vault Server. If this is the desired +behavior, set the bootstrap configuration property +spring.cloud.vault.fail-fast=true and the client will halt with +an Exception.

spring.cloud.vault:
+    fail-fast: true
Prev   Next
7. Service Registry Configuration Home 9. Vault Client SSL configuration
\ No newline at end of file diff --git a/spring-cloud-vault/1.1.0.RC1/multi/multi_vault.config.ssl.html b/spring-cloud-vault/1.1.0.RC1/multi/multi_vault.config.ssl.html new file mode 100644 index 00000000..cd4e69ed --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/multi/multi_vault.config.ssl.html @@ -0,0 +1,13 @@ + + + 9. Vault Client SSL configuration
9. Vault Client SSL configuration
Prev   Next

9. Vault Client SSL configuration

SSL can be configured declaratively by setting various properties. +You can set either javax.net.ssl.trustStore to configure +JVM-wide SSL settings or spring.cloud.vault.ssl.trust-store +to set SSL settings only for Spring Cloud Vault Config.

spring.cloud.vault:
+    ssl:
+        trust-store: classpath:keystore.jks
+        trust-store-password: changeit
  • trust-store sets the resource for the trust-store. SSL-secured Vault +communication will validate the Vault SSL certificate with the specified +trust-store.
  • trust-store-password sets the trust-store password

Please note that configuring spring.cloud.vault.ssl.* can be only +applied when either Apache Http Components or the OkHttp client +is on your class-path.

Prev   Next
8. Vault Client Fail Fast Home 10. Lease lifecycle management (renewal and revocation)
\ No newline at end of file diff --git a/spring-cloud-vault/1.1.0.RC1/single/css/highlight.css b/spring-cloud-vault/1.1.0.RC1/single/css/highlight.css new file mode 100644 index 00000000..ffefef72 --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/single/css/highlight.css @@ -0,0 +1,35 @@ +/* + code highlight CSS resemblign the Eclipse IDE default color schema + @author Costin Leau +*/ + +.hl-keyword { + color: #7F0055; + font-weight: bold; +} + +.hl-comment { + color: #3F5F5F; + font-style: italic; +} + +.hl-multiline-comment { + color: #3F5FBF; + font-style: italic; +} + +.hl-tag { + color: #3F7F7F; +} + +.hl-attribute { + color: #7F007F; +} + +.hl-value { + color: #2A00FF; +} + +.hl-string { + color: #2A00FF; +} \ No newline at end of file diff --git a/spring-cloud-vault/1.1.0.RC1/single/css/manual-multipage.css b/spring-cloud-vault/1.1.0.RC1/single/css/manual-multipage.css new file mode 100644 index 00000000..0c484531 --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/single/css/manual-multipage.css @@ -0,0 +1,9 @@ +@IMPORT url("manual.css"); + +body.firstpage { + background: url("../images/background.png") no-repeat center top; +} + +div.part h1 { + border-top: none; +} diff --git a/spring-cloud-vault/1.1.0.RC1/single/css/manual-singlepage.css b/spring-cloud-vault/1.1.0.RC1/single/css/manual-singlepage.css new file mode 100644 index 00000000..4a7fd140 --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/single/css/manual-singlepage.css @@ -0,0 +1,6 @@ +@IMPORT url("manual.css"); + +body { + background: url("../images/background.png") no-repeat center top; +} + diff --git a/spring-cloud-vault/1.1.0.RC1/single/css/manual.css b/spring-cloud-vault/1.1.0.RC1/single/css/manual.css new file mode 100644 index 00000000..0ecbe2e8 --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/single/css/manual.css @@ -0,0 +1,344 @@ +@IMPORT url("highlight.css"); + +html { + padding: 0pt; + margin: 0pt; +} + +body { + color: #333333; + margin: 15px 30px; + font-family: Helvetica, Arial, Freesans, Clean, Sans-serif; + line-height: 1.6; + -webkit-font-smoothing: antialiased; +} + +code { + font-size: 16px; + font-family: Consolas, "Liberation Mono", Courier, monospace; +} + +:not(a)>code { + color: #6D180B; +} + +:not(pre)>code { + background-color: #F2F2F2; + border: 1px solid #CCCCCC; + border-radius: 4px; + padding: 1px 3px 0; + text-shadow: none; + white-space: nowrap; +} + +body>*:first-child { + margin-top: 0 !important; +} + +div { + margin: 0pt; +} + +hr { + border: 1px solid #CCCCCC; + background: #CCCCCC; +} + +h1,h2,h3,h4,h5,h6 { + color: #000000; + cursor: text; + font-weight: bold; + margin: 30px 0 10px; + padding: 0; +} + +h1,h2,h3 { + margin: 40px 0 10px; +} + +h1 { + margin: 70px 0 30px; + padding-top: 20px; +} + +div.part h1 { + border-top: 1px dotted #CCCCCC; +} + +h1,h1 code { + font-size: 32px; +} + +h2,h2 code { + font-size: 24px; +} + +h3,h3 code { + font-size: 20px; +} + +h4,h1 code,h5,h5 code,h6,h6 code { + font-size: 18px; +} + +div.book,div.chapter,div.appendix,div.part,div.preface { + min-width: 300px; + max-width: 1200px; + margin: 0 auto; +} + +p.releaseinfo { + font-weight: bold; + margin-bottom: 40px; + margin-top: 40px; +} + +div.authorgroup { + line-height: 1; +} + +p.copyright { + line-height: 1; + margin-bottom: -5px; +} + +.legalnotice p { + font-style: italic; + font-size: 14px; + line-height: 1; +} + +div.titlepage+p,div.titlepage+p { + margin-top: 0; +} + +pre { + line-height: 1.0; + color: black; +} + +a { + color: #4183C4; + text-decoration: none; +} + +p { + margin: 15px 0; + text-align: left; +} + +ul,ol { + padding-left: 30px; +} + +li p { + margin: 0; +} + +div.table { + margin: 1em; + padding: 0.5em; + text-align: center; +} + +div.table table,div.informaltable table { + display: table; + width: 100%; +} + +div.table td { + padding-left: 7px; + padding-right: 7px; +} + +.sidebar { + line-height: 1.4; + padding: 0 20px; + background-color: #F8F8F8; + border: 1px solid #CCCCCC; + border-radius: 3px 3px 3px 3px; +} + +.sidebar p.title { + color: #6D180B; +} + +pre.programlisting,pre.screen { + font-size: 15px; + padding: 6px 10px; + background-color: #F8F8F8; + border: 1px solid #CCCCCC; + border-radius: 3px 3px 3px 3px; + clear: both; + overflow: auto; + line-height: 1.4; + font-family: Consolas, "Liberation Mono", Courier, monospace; +} + +table { + border-collapse: collapse; + border-spacing: 0; + border: 1px solid #DDDDDD !important; + border-radius: 4px !important; + border-collapse: separate !important; + line-height: 1.6; +} + +table thead { + background: #F5F5F5; +} + +table tr { + border: none; + border-bottom: none; +} + +table th { + font-weight: bold; +} + +table th,table td { + border: none !important; + padding: 6px 13px; +} + +table tr:nth-child(2n) { + background-color: #F8F8F8; +} + +td p { + margin: 0 0 15px 0; +} + +div.table-contents td p { + margin: 0; +} + +div.important *,div.note *,div.tip *,div.warning *,div.navheader *,div.navfooter *,div.calloutlist * + { + border: none !important; + background: none !important; + margin: 0; +} + +div.important p,div.note p,div.tip p,div.warning p { + color: #6F6F6F; + line-height: 1.6; +} + +div.important code,div.note code,div.tip code,div.warning code { + background-color: #F2F2F2 !important; + border: 1px solid #CCCCCC !important; + border-radius: 4px !important; + padding: 1px 3px 0 !important; + text-shadow: none !important; + white-space: nowrap !important; +} + +.note th,.tip th,.warning th { + display: none; +} + +.note tr:first-child td,.tip tr:first-child td,.warning tr:first-child td + { + border-right: 1px solid #CCCCCC !important; + padding-top: 10px; +} + +div.calloutlist p,div.calloutlist td { + padding: 0; + margin: 0; +} + +div.calloutlist>table>tbody>tr>td:first-child { + padding-left: 10px; + width: 30px !important; +} + +div.important,div.note,div.tip,div.warning { + margin-left: 0px !important; + margin-right: 20px !important; + margin-top: 20px; + margin-bottom: 20px; + padding-top: 10px; + padding-bottom: 10px; +} + +div.toc { + line-height: 1.2; +} + +dl,dt { + margin-top: 1px; + margin-bottom: 0; +} + +div.toc>dl>dt { + font-size: 32px; + font-weight: bold; + margin: 30px 0 10px 0; + display: block; +} + +div.toc>dl>dd>dl>dt { + font-size: 24px; + font-weight: bold; + margin: 20px 0 10px 0; + display: block; +} + +div.toc>dl>dd>dl>dd>dl>dt { + font-weight: bold; + font-size: 20px; + margin: 10px 0 0 0; +} + +tbody.footnotes * { + border: none !important; +} + +div.footnote p { + margin: 0; + line-height: 1; +} + +div.footnote p sup { + margin-right: 6px; + vertical-align: middle; +} + +div.navheader { + border-bottom: 1px solid #CCCCCC; +} + +div.navfooter { + border-top: 1px solid #CCCCCC; +} + +.title { + margin-left: -1em; + padding-left: 1em; +} + +.title>a { + position: absolute; + visibility: hidden; + display: block; + font-size: 0.85em; + margin-top: 0.05em; + margin-left: -1em; + vertical-align: text-top; + color: black; +} + +.title>a:before { + content: "\00A7"; +} + +.title:hover>a,.title>a:hover,.title:hover>a:hover { + visibility: visible; +} + +.title:focus>a,.title>a:focus,.title:focus>a:focus { + outline: 0; +} diff --git a/spring-cloud-vault/1.1.0.RC1/single/images/background.png b/spring-cloud-vault/1.1.0.RC1/single/images/background.png new file mode 100644 index 00000000..15dca6fb Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/single/images/background.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/single/images/caution.png b/spring-cloud-vault/1.1.0.RC1/single/images/caution.png new file mode 100644 index 00000000..8a5e4fca Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/single/images/caution.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/single/images/important.png b/spring-cloud-vault/1.1.0.RC1/single/images/important.png new file mode 100644 index 00000000..ec54df65 Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/single/images/important.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/single/images/logo.png b/spring-cloud-vault/1.1.0.RC1/single/images/logo.png new file mode 100644 index 00000000..ade2ce6e Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/single/images/logo.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/single/images/note.png b/spring-cloud-vault/1.1.0.RC1/single/images/note.png new file mode 100644 index 00000000..88d997b1 Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/single/images/note.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/single/images/sts_exception.png b/spring-cloud-vault/1.1.0.RC1/single/images/sts_exception.png new file mode 100644 index 00000000..8607c38a Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/single/images/sts_exception.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/single/images/tip.png b/spring-cloud-vault/1.1.0.RC1/single/images/tip.png new file mode 100644 index 00000000..6530abb4 Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/single/images/tip.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/single/images/warning.png b/spring-cloud-vault/1.1.0.RC1/single/images/warning.png new file mode 100644 index 00000000..0d5b5244 Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/single/images/warning.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/single/images/web-selected.png b/spring-cloud-vault/1.1.0.RC1/single/images/web-selected.png new file mode 100644 index 00000000..aa6b2da6 Binary files /dev/null and b/spring-cloud-vault/1.1.0.RC1/single/images/web-selected.png differ diff --git a/spring-cloud-vault/1.1.0.RC1/single/spring-cloud-vault.html b/spring-cloud-vault/1.1.0.RC1/single/spring-cloud-vault.html new file mode 100644 index 00000000..ef6c12c3 --- /dev/null +++ b/spring-cloud-vault/1.1.0.RC1/single/spring-cloud-vault.html @@ -0,0 +1,427 @@ + + + Spring Cloud Vault

Spring Cloud Vault

Table of Contents

1. Quick Start
2. Client Side Usage
2.1. Authentication
3. Authentication methods
3.1. Token authentication
3.2. AppId authentication
3.2.1. Custom UserId
3.3. AppRole authentication
3.4. AWS-EC2 authentication
3.5. TLS certificate authentication
3.6. Cubbyhole authentication
4. Secret Backends
4.1. Generic Backend
4.2. Consul
4.3. RabbitMQ
4.4. AWS
5. Database backends
5.1. Apache Cassandra
5.2. MongoDB
5.3. MySQL
5.4. PostgreSQL
6. Configure PropertySourceLocator behavior
7. Service Registry Configuration
8. Vault Client Fail Fast
9. Vault Client SSL configuration
10. Lease lifecycle management (renewal and revocation)

© 2016-2017 The original authors.

[Note]Note

Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

Spring Cloud Vault Config provides client-side support for externalized configuration in a distributed system. With HashiCorp’s Vault you have a central place to manage external secret properties for applications across all environments. Vault can manage static and dynamic secrets such as username/password for remote applications/resources and provide credentials for external services such as MySQL, PostgreSQL, Apache Cassandra, MongoDB, Consul, AWS and more.

1. Quick Start

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 7 and a properly configured JAVA_HOME environment variable

Install Vault

$ src/test/bash/install_vault.sh

Create SSL certificates for Vault

$ src/test/bash/create_certificates.sh
[Note]Note

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.

Start Vault server

$ src/test/bash/local_run_vault.sh

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]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.

$ export VAULT_ADDR="https://localhost:8200"
+$ export VAULT_SKIP_VERIFY=true # Don't do this for production
+$ vault init

You should see something like:

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.

$ vault unseal (Key 1)
+$ vault unseal (Key 2)
+$ vault 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.

2. 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:

Example 2.1. pom.xml

<parent>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-parent</artifactId>
+    <version>1.5.4.RELEASE</version>
+    <relativePath /> <!-- lookup parent from repository -->
+</parent>
+
+<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-starter-vault-config</artifactId>
+        <version>1.1.0.RC1</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:

@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 bootstrap.properties (like application.properties but for +the bootstrap phase of an application context), e.g.

Example 2.2. bootstrap.yml

spring.cloud.vault:
+    host: localhost
+    port: 8200
+    scheme: https
+    uri: https://localhost:8200
+    connection-timeout: 5000
+    read-timeout: 15000
+    config:
+        order: -10

  • 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
  • config.order sets the order for the property source

Enabling further integrations requires additional dependencies and +configuration. Depending on how you have set up Vault you might need +additional configuration like +SSL and +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 health.vault.enabled (default true).

2.1 Authentication

Vault requires an authentication mechanism to authorize client requests.

Spring Cloud Vault supports multiple authentication mechanisms to authenticate applications with Vault.

For a quickstart, use the root token printed by the Vault initialization.

Example 2.3. bootstrap.yml

spring.cloud.vault:
+    token: 19aefa97-cccc-bbbb-aaaa-225940e63d76

[Warning]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.

3. Authentication methods

Different organizations have different requirements for security +and authentication. Vault reflects that need by shipping multiple authentication +methods. Spring Cloud Vault supports token and AppId authentication.

3.1 Token authentication

Tokens are the core method for authentication within Vault. +Token authentication requires a static token to be provided using the +Bootstrap Application Context.

[Note]Note

Token authentication is the default authentication method. +If a token is disclosed an unintended party gains access to Vault and +can access secrets for the intended client.

Example 3.1. bootstrap.yml

spring.cloud.vault:
+    authentication: TOKEN
+    token: 00000000-0000-0000-0000-000000000000

  • authentication setting this value to TOKEN selects the Token +authentication method
  • token sets the static token to use

See also: Vault Documentation: Tokens

3.2 AppId authentication

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 Cloud Vault Config 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.

Example 3.2. bootstrap.yml using SHA256 IP-Address UserId’s

spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: IP_ADDRESS

  • authentication setting this value to APPID selects the AppId +authentication method
  • app-id-path sets the path of the AppId mount to use
  • user-id sets the UserId method. Possible values are IP_ADDRESS, +MAC_ADDRESS or a class name implementing a custom AppIdUserIdMechanism

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

$ echo -n 192.168.99.1 | sha256sum
[Note]Note

Including the line break of echo leads to a different hash value +so make sure to include the -n flag.

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).

Example 3.3. bootstrap.yml using SHA256 Mac-Address UserId’s

spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: MAC_ADDRESS
+        network-interface: eth0

  • network-interface sets network interface to obtain the physical address

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

$ echo -n 0AFEDE1234AC | sha256sum
[Note]Note

The Mac address is specified uppercase and without colons. +Including the line break of echo leads to a different hash value +so make sure to include the -n flag.

3.2.1 Custom UserId

The UserId generation is an open mechanism. You can set +spring.cloud.vault.app-id.user-id to any string and the configured +value will be used as static UserId.

A more advanced approach lets you set spring.cloud.vault.app-id.user-id to a +classname. This class must be on your classpath and must implement +the org.springframework.cloud.vault.AppIdUserIdMechanism interface +and the createUserId method. Spring Cloud Vault will obtain the UserId +by calling createUserId each time it authenticates using AppId to +obtain a token.

Example 3.4. bootstrap.yml

spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: com.examlple.MyUserIdMechanism

Example 3.5. MyUserIdMechanism.java

public class MyUserIdMechanism implements AppIdUserIdMechanism {
+
+  @Override
+  public String createUserId() {
+    String userId = ...
+    return userId;
+  }
+}

See also: Vault Documentation: Using the App ID auth backend

3.3 AppRole authentication

AppRole is intended for machine +authentication, like the deprecated (since Vault 0.6.1) Section 3.2, “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 (push or pull mode).

RoleId and optionally SecretId must be provided by configuration, +Spring Vault will not look up these or create a custom SecretId.

Example 3.6. bootstrap.yml with AppRole authentication properties

spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52

  • role-id sets the RoleId.

Example 3.7. bootstrap.yml with all AppRole authentication properties

spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
+        secret-id: 1696536f-1976-73b1-b241-0b4213908d39
+        app-auth-path: approle

  • role-id sets the RoleId.
  • secret-id sets the SecretId. SecretId can be omitted if AppRole is configured without requiring SecretId (See bind_secret_id)
  • approle-path sets the path of the approle authentication mount to use

See also: Vault Documentation: Using the AppRole auth backend

3.4 AWS-EC2 authentication

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.

Example 3.8. bootstrap.yml using AWS-EC2 Authentication

spring.cloud.vault:
+    authentication: AWS_EC2

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 Cloud 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. +You can configure a static nonce with spring.cloud.vault.aws-ec2.nonce.

AWS-EC2 authentication roles are optional and default to the AMI. +You can configure the authentication role by setting the +spring.cloud.vault.aws-ec2.role property.

Example 3.9. bootstrap.yml with configured role

spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server

Example 3.10. bootstrap.yml with all AWS EC2 authentication properties

spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server
+        aws-ec2-path: aws-ec2
+        identity-document: http://...
+        nonce: my-static-nonce

  • authentication setting this value to AWS_EC2 selects the AWS EC2 +authentication method
  • role sets the role name of the AWS EC2 role definition
  • aws-ec2-path sets the path of the AWS EC2 mount to use
  • identity-document sets URL of the PKCS#7 AWS EC2 identity document
  • nonce used for AWS-EC2 authentication. An empty nonce defaults to nonce generation

See also: Vault Documentation: Using the aws-ec2 auth backend

3.5 TLS certificate authentication

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:

  1. Use SSL, see Chapter 9, Vault Client SSL configuration
  2. Configure a Java Keystore that contains the client +certificate and the private key
  3. Set the spring.cloud.vault.authentication to CERT

Example 3.11. bootstrap.yml

spring.cloud.vault:
+    authentication: CERT
+    ssl:
+        key-store: classpath:keystore.jks
+        key-store-password: changeit
+        cert-auth-path: cert

See also: Vault Documentation: Using the Cert auth backend

3.6 Cubbyhole authentication

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 will be retrieved from a wrapped +response stored at /cubbyhole/response.

Creating a wrapped token

[Note]Note

Response Wrapping for token creation requires Vault 0.6.0 or higher.

Example 3.12. Crating and storing tokens

$ vault token-create -wrap-ttl="10m"
+Key                            Value
+---                            -----
+wrapping_token:                397ccb93-ff6c-b17b-9389-380b01ca2645
+wrapping_token_ttl:            0h10m0s
+wrapping_token_creation_time:  2016-09-18 20:29:48.652957077 +0200 CEST
+wrapped_accessor:              46b6aebb-187f-932a-26d7-4f3d86a68319

Example 3.13. bootstrap.yml

spring.cloud.vault:
+    authentication: CUBBYHOLE
+    token: 397ccb93-ff6c-b17b-9389-380b01ca2645

See also:

4. Secret Backends

4.1 Generic Backend

Spring Cloud Vault supports at the basic level the generic secret +backend. The generic secret backend allows storage of arbitrary +values as key-value store. A single context can store one or many +key-value tuples. Contexts can be organized hierarchically. +Spring Cloud Vault allows using the Application name +and a default context name (application) in combination with active +profiles.

/secret/{application}/{profile}
+/secret/{application}
+/secret/{default-context}/{profile}
+/secret/{default-context}

The application name is determined by the properties:

  • spring.cloud.vault.generic.application-name
  • spring.cloud.vault.application-name
  • spring.application.name

Secrets can be obtained from other folders within the generic backend by adding their +paths to the application name, separated by commas. For example, given the application +name usefulapp,mysql1,projectx/aws, each of these folders will be used:

  • /secret/usefulapp
  • /secret/mysql1
  • /secret/projectx/aws

Spring Cloud Vault adds all active profiles to the list of possible context paths. +No active profiles will skip accessing contexts with a profile name.

Properties are exposed like they are stored (i.e. without additional prefixes).

spring.cloud.vault:
+    generic:
+        enabled: true
+        backend: secret
+        profile-separator: '/'
+        default-context: application
+        application-name: my-app
  • enabled setting this value to false disables the secret backend +config usage
  • backend sets the path of the secret mount to use
  • default-context sets the context name used by all applications
  • application-name overrides the application name for use in the generic backend
  • profile-separator separates the profile name from the context in +property sources with profiles

See also: Vault Documentation: Using the generic secret backend

4.2 Consul

Spring Cloud Vault can obtain credentials for HashiCorp Consul. +The Consul integration requires the spring-cloud-vault-config-consul +dependency.

Example 4.1. pom.xml

<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-consul</artifactId>
+        <version>1.1.0.RC1</version>
+    </dependency>
+</dependencies>

The integration can be enabled by setting +spring.cloud.vault.consul.enabled=true (default false) and +providing the role name with spring.cloud.vault.consul.role=….

The obtained token is stored in spring.cloud.consul.token +so using Spring Cloud Consul can pick up the generated +credentials without further configuration. You can configure +the property name by setting spring.cloud.vault.consul.token-property.

spring.cloud.vault:
+    consul:
+        enabled: true
+        role: readonly
+        backend: consul
+        token-property: spring.cloud.consul.token
  • enabled setting this value to true enables the Consul backend config usage
  • role sets the role name of the Consul role definition
  • backend sets the path of the Consul mount to use
  • token-property sets the property name in which the Consul ACL token is stored

See also: Vault Documentation: Setting up Consul with Vault

4.3 RabbitMQ

Spring Cloud Vault can obtain credentials for RabbitMQ.

The RabbitMQ integration requires the spring-cloud-vault-config-rabbitmq +dependency.

Example 4.2. pom.xml

<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-rabbitmq</artifactId>
+        <version>1.1.0.RC1</version>
+    </dependency>
+</dependencies>

The integration can be enabled by setting +spring.cloud.vault.rabbitmq.enabled=true (default false) +and providing the role name with spring.cloud.vault.rabbitmq.role=….

Username and password are stored in spring.rabbitmq.username +and spring.rabbitmq.password so using Spring Boot will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.rabbitmq.username-property and +spring.cloud.vault.rabbitmq.password-property.

spring.cloud.vault:
+    rabbitmq:
+        enabled: true
+        role: readonly
+        backend: rabbitmq
+        username-property: spring.rabbitmq.username
+        password-property: spring.rabbitmq.password
  • enabled setting this value to true enables the RabbitMQ backend config usage
  • role sets the role name of the RabbitMQ role definition
  • backend sets the path of the RabbitMQ mount to use
  • username-property sets the property name in which the RabbitMQ username is stored
  • password-property sets the property name in which the RabbitMQ password is stored

See also: Vault Documentation: Setting up RabbitMQ with Vault

4.4 AWS

Spring Cloud Vault can obtain credentials for AWS.

The AWS integration requires the spring-cloud-vault-config-aws +dependency.

Example 4.3. pom.xml

<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-aws</artifactId>
+        <version>1.1.0.RC1</version>
+    </dependency>
+</dependencies>

The integration can be enabled by setting +spring.cloud.vault.aws=true (default false) +and providing the role name with spring.cloud.vault.aws.role=….

The access key and secret key are stored in cloud.aws.credentials.accessKey +and cloud.aws.credentials.secretKey so using Spring Cloud AWS will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.aws.access-key-property and +spring.cloud.vault.aws.secret-key-property.

spring.cloud.vault:
+    aws:
+        enabled: true
+        role: readonly
+        backend: aws
+        access-key-property: cloud.aws.credentials.accessKey
+        secret-key-property: cloud.aws.credentials.secretKey
  • enabled setting this value to true enables the AWS backend config usage
  • role sets the role name of the AWS role definition
  • backend sets the path of the AWS mount to use
  • access-key-property sets the property name in which the AWS access key is stored
  • secret-key-property sets the property name in which the AWS secret key is stored

See also: Vault Documentation: Setting up AWS with Vault

5. Database backends

Vault supports several database secret backends to generate database +credentials dynamically based on configured roles. This means +services that need to access a database no longer need to configure +credentials: they can request them from Vault, and use Vault’s leasing +mechanism to more easily roll keys.

Spring Cloud Vault integrates with these backends:

Using a database secret backend requires to enable the +backend in the configuration and the spring-cloud-vault-config-databases +dependency.

Vault ships since 0.7.1 with a dedicated database secret backend that allows +database integration via plugins. You can use that specific backend by adapting +one of the JDBC database properties above. Make sure to specify the appropriate +backend path, e.g. spring.cloud.vault.mysql.role.backend=database.

Example 5.1. pom.xml

<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-databases</artifactId>
+        <version>1.1.0.RC1</version>
+    </dependency>
+</dependencies>

[Note]Note

Enabling multiple JDBC-compliant databases will generate credentials +and store them by default in the same property keys hence property names for +JDBC secrets need to be configured separately.

5.1 Apache Cassandra

Spring Cloud Vault can obtain credentials for Apache Cassandra. +The integration can be enabled by setting +spring.cloud.vault.cassandra.enabled=true (default false) and +providing the role name with spring.cloud.vault.cassandra.role=….

Username and password are stored in spring.data.cassandra.username +and spring.data.cassandra.password so using Spring Boot will pick +up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.cassandra.username-property and +spring.cloud.vault.cassandra.password-property.

spring.cloud.vault:
+    cassandra:
+        enabled: true
+        role: readonly
+        backend: cassandra
+        username-property: spring.data.cassandra.username
+        password-property: spring.data.cassandra.username
  • enabled setting this value to true enables the Cassandra backend config usage
  • role sets the role name of the Cassandra role definition
  • backend sets the path of the Cassandra mount to use
  • username-property sets the property name in which the Cassandra username is stored
  • password-property sets the property name in which the Cassandra password is stored

See also: Vault Documentation: Setting up Apache Cassandra with Vault

5.2 MongoDB

Spring Cloud Vault can obtain credentials for MongoDB. +The integration can be enabled by setting +spring.cloud.vault.mongodb.enabled=true (default false) and +providing the role name with spring.cloud.vault.mongodb.role=….

Username and password are stored in spring.data.mongodb.username +and spring.data.mongodb.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mongodb.username-property and +spring.cloud.vault.mongodb.password-property.

spring.cloud.vault:
+    mongodb:
+        enabled: true
+        role: readonly
+        backend: mongodb
+        username-property: spring.data.mongodb.username
+        password-property: spring.data.mongodb.password
  • enabled setting this value to true enables the MongodB backend config usage
  • role sets the role name of the MongoDB role definition
  • backend sets the path of the MongoDB mount to use
  • username-property sets the property name in which the MongoDB username is stored
  • password-property sets the property name in which the MongoDB password is stored

See also: Vault Documentation: Setting up MongoDB with Vault

5.3 MySQL

Spring Cloud Vault can obtain credentials for MySQL. +The integration can be enabled by setting +spring.cloud.vault.mysql.enabled=true (default false) and +providing the role name with spring.cloud.vault.mysql.role=….

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mysql.username-property and +spring.cloud.vault.mysql.password-property.

spring.cloud.vault:
+    mysql:
+        enabled: true
+        role: readonly
+        backend: mysql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
  • enabled setting this value to true enables the MySQL backend config usage
  • role sets the role name of the MySQL role definition
  • backend sets the path of the MySQL mount to use
  • username-property sets the property name in which the MySQL username is stored
  • password-property sets the property name in which the MySQL password is stored

See also: Vault Documentation: Setting up MySQL with Vault

5.4 PostgreSQL

Spring Cloud Vault can obtain credentials for PostgreSQL. +The integration can be enabled by setting +spring.cloud.vault.postgresql.enabled=true (default false) and +providing the role name with spring.cloud.vault.postgresql.role=….

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.postgresql.username-property and +spring.cloud.vault.postgresql.password-property.

spring.cloud.vault:
+    postgresql:
+        enabled: true
+        role: readonly
+        backend: postgresql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
  • enabled setting this value to true enables the PostgreSQL backend config usage
  • role sets the role name of the PostgreSQL role definition
  • backend sets the path of the PostgreSQL mount to use
  • username-property sets the property name in which the PostgreSQL username is stored
  • password-property sets the property name in which the PostgreSQL password is stored

See also: Vault Documentation: Setting up PostgreSQL with Vault

6. Configure PropertySourceLocator behavior

Spring Cloud Vault uses property-based configuration to create PropertySources +for generic and discovered secret backends.

Discovered backends provide VaultSecretBackendDescriptor beans to describe the configuration +state to use secret backend as PropertySource. A SecretBackendMetadataFactory is required +to create a SecretBackendMetadata object which contains path, name and property transformation +configuration.

SecretBackendMetadata is used to back a particular PropertySource.

You can register an arbitrary number of beans implementing VaultConfigurer for customization. +Default generic and discovered backend registration is disabled if Spring Cloud Vault discovers +at least one VaultConfigurer bean. You can however enable default registration with +SecretBackendConfigurer.registerDefaultGenericSecretBackends() and SecretBackendConfigurer.registerDefaultDiscoveredSecretBackends().

public class CustomizationBean implements VaultConfigurer {
+
+    @Override
+    public void addSecretBackends(SecretBackendConfigurer configurer) {
+
+        configurer.add("secret/my-application");
+
+        configurer.registerDefaultGenericSecretBackends(false);
+        configurer.registerDefaultDiscoveredSecretBackends(true);
+    }
+}
[Note]Note

All customization is required to happen in the bootstrap context. Add your configuration +classes to META-INF/spring.factories at org.springframework.cloud.bootstrap.BootstrapConfiguration +in your application.

7. Service Registry Configuration

You can use a DiscoveryClient (such as from Spring Cloud Consul) to locate +a Vault server by setting spring.cloud.vault.discovery.enabled=true (default false). +The net result of that is that your apps need a bootstrap.yml (or an environment variable) +with the appropriate discovery configuration. +The benefit is that the Vault can change its co-ordinates, as long as the discovery service +is a fixed point. The default service id is vault but you can change that on the client with +spring.cloud.vault.discovery.serviceId.

The discovery client implementations all support some kind of metadata map +(e.g. for Eureka we have eureka.instance.metadataMap). Some additional properties of the service +may need to be configured in its service registration metadata so that clients can connect +correctly. Service registries that do not provide details about transport layer security +need to provide a scheme metadata entry to be set either to https or http. +If no scheme is configured and the service is not exposed as secure service, then +configuration defaults to spring.cloud.vault.scheme which is https when it’s not set.

spring.cloud.vault.discovery:
+    enabled: true
+    service-id: my-vault-service

8. Vault Client Fail Fast

In some cases, it may be desirable to fail startup of a service if +it cannot connect to the Vault Server. If this is the desired +behavior, set the bootstrap configuration property +spring.cloud.vault.fail-fast=true and the client will halt with +an Exception.

spring.cloud.vault:
+    fail-fast: true

9. Vault Client SSL configuration

SSL can be configured declaratively by setting various properties. +You can set either javax.net.ssl.trustStore to configure +JVM-wide SSL settings or spring.cloud.vault.ssl.trust-store +to set SSL settings only for Spring Cloud Vault Config.

spring.cloud.vault:
+    ssl:
+        trust-store: classpath:keystore.jks
+        trust-store-password: changeit
  • trust-store sets the resource for the trust-store. SSL-secured Vault +communication will validate the Vault SSL certificate with the specified +trust-store.
  • trust-store-password sets the trust-store password

Please note that configuring spring.cloud.vault.ssl.* can be only +applied when either Apache Http Components or the OkHttp client +is on your class-path.

10. Lease lifecycle management (renewal and revocation)

With every secret, Vault creates a lease: +metadata containing information such as a time duration, +renewability, and more.

Vault promises that the data will be valid for the given duration, +or Time To Live (TTL). Once the lease is expired, Vault can +revoke the data, and the consumer of the secret can no longer +be certain that it is valid.

Spring Cloud Vault maintains a lease lifecycle beyond +the creation of login tokens and secrets. That said, +login tokens and secrets associated with a lease +are scheduled for renewal just before the lease expires +until terminal expiry. +Application shutdown revokes obtained login tokens and renewable +leases.

Secret service and database backends (such as MongoDB or MySQL) +usually generate a renewable lease so generated credentials will +be disabled on application shutdown.

[Note]Note

Static tokens are not renewed or revoked.

Lease renewal and revocation is enabled by default and can +be disabled by setting spring.cloud.vault.config.lifecycle.enabled +to false. This is not recommended as leases can expire and +Spring Cloud Vault cannot longer access Vault or services +using generated credentials and valid credentials remain active +after application shutdown.

spring.cloud.vault:
+    config.lifecycle.enabled: true

See also: Vault Documentation: Lease, Renew, and Revoke

\ No newline at end of file diff --git a/spring-cloud-vault/2.0.0.M1/ghpages.sh b/spring-cloud-vault/2.0.0.M1/ghpages.sh new file mode 100644 index 00000000..57c5da3a --- /dev/null +++ b/spring-cloud-vault/2.0.0.M1/ghpages.sh @@ -0,0 +1,330 @@ +#!/bin/bash -x + +set -e + +# Set default props like MAVEN_PATH, ROOT_FOLDER etc. +function set_default_props() { + # The script should be executed from the root folder + ROOT_FOLDER=`pwd` + echo "Current folder is ${ROOT_FOLDER}" + + if [[ ! -e "${ROOT_FOLDER}/.git" ]]; then + echo "You're not in the root folder of the project!" + exit 1 + fi + + # Prop that will let commit the changes + COMMIT_CHANGES="no" + MAVEN_PATH=${MAVEN_PATH:-} + echo "Path to Maven is [${MAVEN_PATH}]" + REPO_NAME=${PWD##*/} + echo "Repo name is [${REPO_NAME}]" + SPRING_CLOUD_STATIC_REPO=${SPRING_CLOUD_STATIC_REPO:-git@github.com:spring-cloud/spring-cloud-static.git} + echo "Spring Cloud Static repo is [${SPRING_CLOUD_STATIC_REPO}" +} + +# Check if gh-pages exists and docs have been built +function check_if_anything_to_sync() { + git remote set-url --push origin `git config remote.origin.url | sed -e 's/^git:/https:/'` + + if ! (git remote set-branches --add origin gh-pages && git fetch -q); then + echo "No gh-pages, so not syncing" + exit 0 + fi + + if ! [ -d docs/target/generated-docs ] && ! [ "${BUILD}" == "yes" ]; then + echo "No gh-pages sources in docs/target/generated-docs, so not syncing" + exit 0 + fi +} + +function retrieve_current_branch() { + # Code getting the name of the current branch. For master we want to publish as we did until now + # http://stackoverflow.com/questions/1593051/how-to-programmatically-determine-the-current-checked-out-git-branch + # If there is a branch already passed will reuse it - otherwise will try to find it + CURRENT_BRANCH=${BRANCH} + if [[ -z "${CURRENT_BRANCH}" ]] ; then + CURRENT_BRANCH=$(git symbolic-ref -q HEAD) + CURRENT_BRANCH=${CURRENT_BRANCH##refs/heads/} + CURRENT_BRANCH=${CURRENT_BRANCH:-HEAD} + fi + echo "Current branch is [${CURRENT_BRANCH}]" + git checkout ${CURRENT_BRANCH} || echo "Failed to check the branch... continuing with the script" +} + +# Switches to the provided value of the release version. We always prefix it with `v` +function switch_to_tag() { + git checkout v${VERSION} +} + +# Build the docs if switch is on +function build_docs_if_applicable() { + if [[ "${BUILD}" == "yes" ]] ; then + ./mvnw clean install -P docs -pl docs -DskipTests + fi +} + +# Get the name of the `docs.main` property +# Get whitelisted branches - assumes that a `docs` module is available under `docs` profile +function retrieve_doc_properties() { + MAIN_ADOC_VALUE=$("${MAVEN_PATH}"mvn -q \ + -Dexec.executable="echo" \ + -Dexec.args='${docs.main}' \ + --non-recursive \ + org.codehaus.mojo:exec-maven-plugin:1.3.1:exec) + echo "Extracted 'main.adoc' from Maven build [${MAIN_ADOC_VALUE}]" + + + WHITELIST_PROPERTY=${WHITELIST_PROPERTY:-"docs.whitelisted.branches"} + WHITELISTED_BRANCHES_VALUE=$("${MAVEN_PATH}"mvn -q \ + -Dexec.executable="echo" \ + -Dexec.args="\${${WHITELIST_PROPERTY}}" \ + org.codehaus.mojo:exec-maven-plugin:1.3.1:exec \ + -P docs \ + -pl docs) + echo "Extracted '${WHITELIST_PROPERTY}' from Maven build [${WHITELISTED_BRANCHES_VALUE}]" +} + +# Stash any outstanding changes +function stash_changes() { + git diff-index --quiet HEAD && dirty=$? || (echo "Failed to check if the current repo is dirty. Assuming that it is." && dirty="1") + if [ "$dirty" != "0" ]; then git stash; fi +} + +# Switch to gh-pages branch to sync it with current branch +function add_docs_from_target() { + local DESTINATION_REPO_FOLDER + if [[ -z "${DESTINATION}" && -z "${CLONE}" ]] ; then + DESTINATION_REPO_FOLDER=${ROOT_FOLDER} + elif [[ "${CLONE}" == "yes" ]]; then + mkdir -p ${ROOT_FOLDER}/target + local clonedStatic=${ROOT_FOLDER}/target/spring-cloud-static + if [[ ! -e "${clonedStatic}/.git" ]]; then + echo "Cloning Spring Cloud Static to target" + git clone ${SPRING_CLOUD_STATIC_REPO} ${clonedStatic} && git checkout gh-pages + else + echo "Spring Cloud Static already cloned - will pull changes" + cd ${clonedStatic} && git checkout gh-pages && git pull origin gh-pages + fi + DESTINATION_REPO_FOLDER=${clonedStatic}/${REPO_NAME} + mkdir -p ${DESTINATION_REPO_FOLDER} + else + if [[ ! -e "${DESTINATION}/.git" ]]; then + echo "[${DESTINATION}] is not a git repository" + exit 1 + fi + DESTINATION_REPO_FOLDER=${DESTINATION}/${REPO_NAME} + mkdir -p ${DESTINATION_REPO_FOLDER} + echo "Destination was provided [${DESTINATION}]" + fi + cd ${DESTINATION_REPO_FOLDER} + git checkout gh-pages + git pull origin gh-pages + + # Add git branches + ################################################################### + if [[ -z "${VERSION}" ]] ; then + copy_docs_for_current_version + else + copy_docs_for_provided_version + fi + commit_changes_if_applicable +} + + +# Copies the docs by using the retrieved properties from Maven build +function copy_docs_for_current_version() { + if [[ "${CURRENT_BRANCH}" == "master" ]] ; then + echo -e "Current branch is master - will copy the current docs only to the root folder" + for f in docs/target/generated-docs/*; do + file=${f#docs/target/generated-docs/*} + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then + # Not ignored... + cp -rf $f ${ROOT_FOLDER}/ + git add -A ${ROOT_FOLDER}/$file + fi + done + COMMIT_CHANGES="yes" + else + echo -e "Current branch is [${CURRENT_BRANCH}]" + # http://stackoverflow.com/questions/29300806/a-bash-script-to-check-if-a-string-is-present-in-a-comma-separated-list-of-strin + if [[ ",${WHITELISTED_BRANCHES_VALUE}," = *",${CURRENT_BRANCH},"* ]] ; then + mkdir -p ${ROOT_FOLDER}/${CURRENT_BRANCH} + echo -e "Branch [${CURRENT_BRANCH}] is whitelisted! Will copy the current docs to the [${CURRENT_BRANCH}] folder" + for f in docs/target/generated-docs/*; do + file=${f#docs/target/generated-docs/*} + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then + # Not ignored... + # We want users to access 1.0.0.RELEASE/ instead of 1.0.0.RELEASE/spring-cloud.sleuth.html + if [[ "${file}" == "${MAIN_ADOC_VALUE}.html" ]] ; then + # We don't want to copy the spring-cloud-sleuth.html + # we want it to be converted to index.html + cp -rf $f ${ROOT_FOLDER}/${CURRENT_BRANCH}/index.html + git add -A ${ROOT_FOLDER}/${CURRENT_BRANCH}/index.html + else + cp -rf $f ${ROOT_FOLDER}/${CURRENT_BRANCH} + git add -A ${ROOT_FOLDER}/${CURRENT_BRANCH}/$file + fi + fi + done + COMMIT_CHANGES="yes" + else + echo -e "Branch [${CURRENT_BRANCH}] is not on the white list! Check out the Maven [${WHITELIST_PROPERTY}] property in + [docs] module available under [docs] profile. Won't commit any changes to gh-pages for this branch." + fi + fi +} + +# Copies the docs by using the explicitly provided version +function copy_docs_for_provided_version() { + local FOLDER=${DESTINATION_REPO_FOLDER}/${VERSION} + mkdir -p ${FOLDER} + echo -e "Current tag is [v${VERSION}] Will copy the current docs to the [${FOLDER}] folder" + for f in ${ROOT_FOLDER}/docs/target/generated-docs/*; do + file=${f#${ROOT_FOLDER}/docs/target/generated-docs/*} + copy_docs_for_branch ${file} ${FOLDER} + done + COMMIT_CHANGES="yes" + CURRENT_BRANCH="v${VERSION}" +} + +# Copies the docs from target to the provided destination +# Params: +# $1 - file from target +# $2 - destination to which copy the files +function copy_docs_for_branch() { + local file=$1 + local destination=$2 + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^${file}$; then + # Not ignored... + # We want users to access 1.0.0.RELEASE/ instead of 1.0.0.RELEASE/spring-cloud.sleuth.html + if [[ ("${file}" == "${MAIN_ADOC_VALUE}.html") || ("${file}" == "${REPO_NAME}.html") ]] ; then + # We don't want to copy the spring-cloud-sleuth.html + # we want it to be converted to index.html + cp -rf $f ${destination}/index.html + git add -A ${destination}/index.html + else + cp -rf $f ${destination} + git add -A ${destination}/$file + fi + fi +} + +function commit_changes_if_applicable() { + if [[ "${COMMIT_CHANGES}" == "yes" ]] ; then + COMMIT_SUCCESSFUL="no" + git commit -a -m "Sync docs from ${CURRENT_BRANCH} to gh-pages" && COMMIT_SUCCESSFUL="yes" || echo "Failed to commit changes" + + # Uncomment the following push if you want to auto push to + # the gh-pages branch whenever you commit to master locally. + # This is a little extreme. Use with care! + ################################################################### + if [[ "${COMMIT_SUCCESSFUL}" == "yes" ]] ; then + git push origin gh-pages + fi + fi +} + +# Switch back to the previous branch and exit block +function checkout_previous_branch() { + # If -version was provided we need to come back to root project + cd ${ROOT_FOLDER} + git checkout ${CURRENT_BRANCH} || echo "Failed to check the branch... continuing with the script" + if [ "$dirty" != "0" ]; then git stash pop; fi + exit 0 +} + +# Assert if properties have been properly passed +function assert_properties() { +echo "VERSION [${VERSION}], DESTINATION [${DESTINATION}], CLONE [${CLONE}]" +if [[ "${VERSION}" != "" && (-z "${DESTINATION}" && -z "${CLONE}") ]] ; then echo "Version was set but destination / clone was not!"; exit 1;fi +if [[ ("${DESTINATION}" != "" && "${CLONE}" != "") && -z "${VERSION}" ]] ; then echo "Destination / clone was set but version was not!"; exit 1;fi +if [[ "${DESTINATION}" != "" && "${CLONE}" == "yes" ]] ; then echo "Destination and clone was set. Pick one!"; exit 1;fi +} + +# Prints the usage +function print_usage() { +cat </` +- if the destination switch is passed (-d) then the script will check if the provided dir is a git repo and then will + switch to gh-pages of that repo and copy the generated docs to `docs//` + +USAGE: + +You can use the following options: + +-v|--version - the script will apply the whole procedure for a particular library version +-d|--destination - the root of destination folder where the docs should be copied. You have to use the full path. + E.g. point to spring-cloud-static folder. Can't be used with (-c) +-b|--build - will run the standard build process after checking out the branch +-c|--clone - will automatically clone the spring-cloud-static repo instead of providing the destination. + Obviously can't be used with (-d) + +EOF +} + + +# ========================================== +# ____ ____ _____ _____ _____ _______ +# / ____|/ ____| __ \|_ _| __ \__ __| +# | (___ | | | |__) | | | | |__) | | | +# \___ \| | | _ / | | | ___/ | | +# ____) | |____| | \ \ _| |_| | | | +# |_____/ \_____|_| \_\_____|_| |_| +# +# ========================================== + +while [[ $# > 0 ]] +do +key="$1" +case ${key} in + -v|--version) + VERSION="$2" + shift # past argument + ;; + -d|--destination) + DESTINATION="$2" + shift # past argument + ;; + -b|--build) + BUILD="yes" + ;; + -c|--clone) + CLONE="yes" + ;; + -h|--help) + print_usage + exit 0 + ;; + *) + echo "Invalid option: [$1]" + print_usage + exit 1 + ;; +esac +shift # past argument or value +done + +assert_properties +set_default_props +check_if_anything_to_sync +if [[ -z "${VERSION}" ]] ; then + retrieve_current_branch +else + switch_to_tag +fi +build_docs_if_applicable +retrieve_doc_properties +stash_changes +add_docs_from_target +checkout_previous_branch \ No newline at end of file diff --git a/spring-cloud-vault/2.0.0.M1/index.html b/spring-cloud-vault/2.0.0.M1/index.html new file mode 100644 index 00000000..ed97e159 --- /dev/null +++ b/spring-cloud-vault/2.0.0.M1/index.html @@ -0,0 +1,2102 @@ + + + + + + + +Spring Cloud Vault + + + + + +
+
+
+
+

© 2016-2017 The original authors.

+
+
+ + + + + +
+
Note
+		 +Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically. +
+
+
+

Spring Cloud Vault Config provides client-side support for externalized configuration in a distributed system. With HashiCorp’s Vault you have a central place to manage external secret properties for applications across all environments. Vault can manage static and dynamic secrets such as username/password for remote applications/resources and provide credentials for external services such as MySQL, PostgreSQL, Apache Cassandra, MongoDB, Consul, AWS and more.

+
+
+
+
+

Quick Start

+
+
+

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 7 and a properly configured JAVA_HOME environment variable

    +
    • +
+
+
+

Install Vault

+
+
+
+
$ src/test/bash/install_vault.sh
+
+
+
+

Create SSL certificates for Vault

+
+
+
+
$ src/test/bash/create_certificates.sh
+
+
+
+ + + + + +
+
Note
+		 +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. +
+
+
+

Start Vault server

+
+
+
+
$ src/test/bash/local_run_vault.sh
+
+
+
+

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.

+
+
+
+
$ export VAULT_ADDR="https://localhost:8200"
+$ export VAULT_SKIP_VERIFY=true # Don't do this for production
+$ vault init
+
+
+
+

You should see something like:

+
+
+
+
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.

+
+
+
+
$ vault unseal (Key 1)
+$ vault unseal (Key 2)
+$ vault 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

+
+
+

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:

+
+
+
Example 1. pom.xml
+
+
+
+
<parent>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-parent</artifactId>
+    <version>1.5.4.RELEASE</version>
+    <relativePath /> <!-- lookup parent from repository -->
+</parent>
+
+<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-starter-vault-config</artifactId>
+        <version>2.0.0.M1</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:

+
+
+
+
+
+
@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 bootstrap.properties (like application.properties but for +the bootstrap phase of an application context), e.g.

+
+
+
Example 2. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    host: localhost
+    port: 8200
+    scheme: https
+    uri: https://localhost:8200
+    connection-timeout: 5000
+    read-timeout: 15000
+    config:
+        order: -10
+
+
+
+
+
+
    +
  • +

    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

    +
    • +
  • +

    config.order sets the order for the property source

    +
    • +
+
+
+

Enabling further integrations requires additional dependencies and +configuration. Depending on how you have set up Vault you might need +additional configuration like +SSL and +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 health.vault.enabled (default true).

+
+
+

Authentication

+
+

Vault requires an authentication mechanism to authorize client requests.

+
+
+

Spring Cloud Vault supports multiple authentication mechanisms to authenticate applications with Vault.

+
+
+

For a quickstart, use the root token printed by the Vault initialization.

+
+
+
Example 3. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    token: 19aefa97-cccc-bbbb-aaaa-225940e63d76
+
+
+
+
+
+ + + + + +
+
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. +
+
+
+
+
+
+

Authentication methods

+
+
+

Different organizations have different requirements for security +and authentication. Vault reflects that need by shipping multiple authentication +methods. Spring Cloud Vault supports token and AppId authentication.

+
+
+

Token authentication

+
+

Tokens are the core method for authentication within Vault. +Token authentication requires a static token to be provided using the +Bootstrap Application Context.

+
+
+ + + + + +
+
Note
+		 +Token authentication is the default authentication method. +If a token is disclosed an unintended party gains access to Vault and +can access secrets for the intended client. +
+
+
+
Example 4. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: TOKEN
+    token: 00000000-0000-0000-0000-000000000000
+
+
+
+
+
+
    +
  • +

    authentication setting this value to TOKEN selects the Token +authentication method

    +
    • +
  • +

    token sets the static token to use

    +
    • +
+
+
+

See also: Vault Documentation: Tokens

+
+
+
+

AppId authentication

+
+

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 Cloud Vault Config 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.

+
+
+
Example 5. bootstrap.yml using SHA256 IP-Address UserId’s
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: IP_ADDRESS
+
+
+
+
+
+
    +
  • +

    authentication setting this value to APPID selects the AppId +authentication method

    +
    • +
  • +

    app-id-path sets the path of the AppId mount to use

    +
    • +
  • +

    user-id sets the UserId method. Possible values are IP_ADDRESS, +MAC_ADDRESS or a class name implementing a custom AppIdUserIdMechanism

    +
    • +
+
+
+

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

+
+
+
+
$ echo -n 192.168.99.1 | sha256sum
+
+
+
+ + + + + +
+
Note
+		 +Including the line break of echo leads to a different hash value +so make sure to include the -n flag. +
+
+
+

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).

+
+
+
Example 6. bootstrap.yml using SHA256 Mac-Address UserId’s
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: MAC_ADDRESS
+        network-interface: eth0
+
+
+
+
+
+
    +
  • +

    network-interface sets network interface to obtain the physical address

    +
    • +
+
+
+

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

+
+
+
+
$ echo -n 0AFEDE1234AC | sha256sum
+
+
+
+ + + + + +
+
Note
+		 +The Mac address is specified uppercase and without colons. +Including the line break of echo leads to a different hash value +so make sure to include the -n flag. +
+
+
+

Custom UserId

+
+

The UserId generation is an open mechanism. You can set +spring.cloud.vault.app-id.user-id to any string and the configured +value will be used as static UserId.

+
+
+

A more advanced approach lets you set spring.cloud.vault.app-id.user-id to a +classname. This class must be on your classpath and must implement +the org.springframework.cloud.vault.AppIdUserIdMechanism interface +and the createUserId method. Spring Cloud Vault will obtain the UserId +by calling createUserId each time it authenticates using AppId to +obtain a token.

+
+
+
Example 7. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: com.examlple.MyUserIdMechanism
+
+
+
+
+
+
Example 8. MyUserIdMechanism.java
+
+
+
+
public class MyUserIdMechanism implements AppIdUserIdMechanism {
+
+  @Override
+  public String createUserId() {
+    String userId = ...
+    return userId;
+  }
+}
+
+
+
+
+
+

See also: Vault Documentation: Using the App ID auth backend

+
+
+
+
+

AppRole authentication

+
+

AppRole is intended for 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 (push or pull mode).

+
+
+

RoleId and optionally SecretId must be provided by configuration, +Spring Vault will not look up these or create a custom SecretId.

+
+
+
Example 9. bootstrap.yml with AppRole authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
+
+
+
+
+
+
    +
  • +

    role-id sets the RoleId.

    +
    • +
+
+
+
Example 10. bootstrap.yml with all AppRole authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
+        secret-id: 1696536f-1976-73b1-b241-0b4213908d39
+        app-auth-path: approle
+
+
+
+
+
+
    +
  • +

    role-id sets the RoleId.

    +
    • +
  • +

    secret-id sets the SecretId. SecretId can be omitted if AppRole is configured without requiring SecretId (See bind_secret_id)

    +
    • +
  • +

    approle-path sets the path of the approle authentication mount to use

    +
    • +
+
+
+

See also: Vault Documentation: Using the AppRole auth backend

+
+
+
+

AWS-EC2 authentication

+
+

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.

+
+
+
Example 11. bootstrap.yml using AWS-EC2 Authentication
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+
+
+
+
+
+

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 Cloud 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. +You can configure a static nonce with spring.cloud.vault.aws-ec2.nonce.

+
+
+

AWS-EC2 authentication roles are optional and default to the AMI. +You can configure the authentication role by setting the +spring.cloud.vault.aws-ec2.role property.

+
+
+
Example 12. bootstrap.yml with configured role
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server
+
+
+
+
+
+
Example 13. bootstrap.yml with all AWS EC2 authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server
+        aws-ec2-path: aws-ec2
+        identity-document: http://...
+        nonce: my-static-nonce
+
+
+
+
+
+
    +
  • +

    authentication setting this value to AWS_EC2 selects the AWS EC2 +authentication method

    +
    • +
  • +

    role sets the role name of the AWS EC2 role definition

    +
    • +
  • +

    aws-ec2-path sets the path of the AWS EC2 mount to use

    +
    • +
  • +

    identity-document sets URL of the PKCS#7 AWS EC2 identity document

    +
    • +
  • +

    nonce used for AWS-EC2 authentication. An empty nonce defaults to nonce generation

    +
    • +
+
+
+

See also: Vault Documentation: Using the aws-ec2 auth backend

+
+
+
+

TLS certificate authentication

+
+

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:

+
+
+
    +
  1. +

    Use SSL, see Vault Client SSL configuration

    +
    2. +
  2. +

    Configure a Java Keystore that contains the client +certificate and the private key

    +
    3. +
  3. +

    Set the spring.cloud.vault.authentication to CERT

    +
    4. +
+
+
+
Example 14. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: CERT
+    ssl:
+        key-store: classpath:keystore.jks
+        key-store-password: changeit
+        cert-auth-path: cert
+
+
+
+
+
+

See also: Vault Documentation: Using the Cert auth backend

+
+
+
+

Cubbyhole authentication

+
+

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 will be retrieved from a wrapped +response stored at /cubbyhole/response.

+
+
+

Creating a wrapped token

+
+
+ + + + + +
+
Note
+		 +Response Wrapping for token creation requires Vault 0.6.0 or higher. +
+
+
+
Example 15. Crating and storing tokens
+
+
+
+
$ vault token-create -wrap-ttl="10m"
+Key                            Value
+---                            -----
+wrapping_token:                397ccb93-ff6c-b17b-9389-380b01ca2645
+wrapping_token_ttl:            0h10m0s
+wrapping_token_creation_time:  2016-09-18 20:29:48.652957077 +0200 CEST
+wrapped_accessor:              46b6aebb-187f-932a-26d7-4f3d86a68319
+
+
+
+
+
+
Example 16. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: CUBBYHOLE
+    token: 397ccb93-ff6c-b17b-9389-380b01ca2645
+
+
+
+
+
+

See also:

+
+
+ +
+
+
+
+
+

Secret Backends

+
+
+

Generic Backend

+
+

Spring Cloud Vault supports at the basic level the generic secret +backend. The generic secret backend allows storage of arbitrary +values as key-value store. A single context can store one or many +key-value tuples. Contexts can be organized hierarchically. +Spring Cloud Vault allows using the Application name +and a default context name (application) in combination with active +profiles.

+
+
+
+
/secret/{application}/{profile}
+/secret/{application}
+/secret/{default-context}/{profile}
+/secret/{default-context}
+
+
+
+

The application name is determined by the properties:

+
+
+
    +
  • +

    spring.cloud.vault.generic.application-name

    +
    • +
  • +

    spring.cloud.vault.application-name

    +
    • +
  • +

    spring.application.name

    +
    • +
+
+
+

Secrets can be obtained from other folders within the generic backend by adding their +paths to the application name, separated by commas. For example, given the application +name usefulapp,mysql1,projectx/aws, each of these folders will be used:

+
+
+
    +
  • +

    /secret/usefulapp

    +
    • +
  • +

    /secret/mysql1

    +
    • +
  • +

    /secret/projectx/aws

    +
    • +
+
+
+

Spring Cloud Vault adds all active profiles to the list of possible context paths. +No active profiles will skip accessing contexts with a profile name.

+
+
+

Properties are exposed like they are stored (i.e. without additional prefixes).

+
+
+
+
+
+
spring.cloud.vault:
+    generic:
+        enabled: true
+        backend: secret
+        profile-separator: '/'
+        default-context: application
+        application-name: my-app
+
+
+
+
+
+
    +
  • +

    enabled setting this value to false disables the secret backend +config usage

    +
    • +
  • +

    backend sets the path of the secret mount to use

    +
    • +
  • +

    default-context sets the context name used by all applications

    +
    • +
  • +

    application-name overrides the application name for use in the generic backend

    +
    • +
  • +

    profile-separator separates the profile name from the context in +property sources with profiles

    +
    • +
+
+
+

See also: Vault Documentation: Using the generic secret backend

+
+
+
+

Consul

+
+

Spring Cloud Vault can obtain credentials for HashiCorp Consul. +The Consul integration requires the spring-cloud-vault-config-consul +dependency.

+
+
+
Example 17. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-consul</artifactId>
+        <version>2.0.0.M1</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.consul.enabled=true (default false) and +providing the role name with spring.cloud.vault.consul.role=….

+
+
+

The obtained token is stored in spring.cloud.consul.token +so using Spring Cloud Consul can pick up the generated +credentials without further configuration. You can configure +the property name by setting spring.cloud.vault.consul.token-property.

+
+
+
+
+
+
spring.cloud.vault:
+    consul:
+        enabled: true
+        role: readonly
+        backend: consul
+        token-property: spring.cloud.consul.token
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the Consul backend config usage

    +
    • +
  • +

    role sets the role name of the Consul role definition

    +
    • +
  • +

    backend sets the path of the Consul mount to use

    +
    • +
  • +

    token-property sets the property name in which the Consul ACL token is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up Consul with Vault

+
+
+
+

RabbitMQ

+
+

Spring Cloud Vault can obtain credentials for RabbitMQ.

+
+
+

The RabbitMQ integration requires the spring-cloud-vault-config-rabbitmq +dependency.

+
+
+
Example 18. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-rabbitmq</artifactId>
+        <version>2.0.0.M1</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.rabbitmq.enabled=true (default false) +and providing the role name with spring.cloud.vault.rabbitmq.role=….

+
+
+

Username and password are stored in spring.rabbitmq.username +and spring.rabbitmq.password so using Spring Boot will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.rabbitmq.username-property and +spring.cloud.vault.rabbitmq.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    rabbitmq:
+        enabled: true
+        role: readonly
+        backend: rabbitmq
+        username-property: spring.rabbitmq.username
+        password-property: spring.rabbitmq.password
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the RabbitMQ backend config usage

    +
    • +
  • +

    role sets the role name of the RabbitMQ role definition

    +
    • +
  • +

    backend sets the path of the RabbitMQ mount to use

    +
    • +
  • +

    username-property sets the property name in which the RabbitMQ username is stored

    +
    • +
  • +

    password-property sets the property name in which the RabbitMQ password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up RabbitMQ with Vault

+
+
+
+

AWS

+
+

Spring Cloud Vault can obtain credentials for AWS.

+
+
+

The AWS integration requires the spring-cloud-vault-config-aws +dependency.

+
+
+
Example 19. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-aws</artifactId>
+        <version>2.0.0.M1</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.aws=true (default false) +and providing the role name with spring.cloud.vault.aws.role=….

+
+
+

The access key and secret key are stored in cloud.aws.credentials.accessKey +and cloud.aws.credentials.secretKey so using Spring Cloud AWS will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.aws.access-key-property and +spring.cloud.vault.aws.secret-key-property.

+
+
+
+
+
+
spring.cloud.vault:
+    aws:
+        enabled: true
+        role: readonly
+        backend: aws
+        access-key-property: cloud.aws.credentials.accessKey
+        secret-key-property: cloud.aws.credentials.secretKey
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the AWS backend config usage

    +
    • +
  • +

    role sets the role name of the AWS role definition

    +
    • +
  • +

    backend sets the path of the AWS mount to use

    +
    • +
  • +

    access-key-property sets the property name in which the AWS access key is stored

    +
    • +
  • +

    secret-key-property sets the property name in which the AWS secret key is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up AWS with Vault

+
+
+
+
+
+

Database backends

+
+
+

Vault supports several database secret backends to generate database +credentials dynamically based on configured roles. This means +services that need to access a database no longer need to configure +credentials: they can request them from Vault, and use Vault’s leasing +mechanism to more easily roll keys.

+
+
+

Spring Cloud Vault integrates with these backends:

+
+
+ +
+
+

Using a database secret backend requires to enable the +backend in the configuration and the spring-cloud-vault-config-databases +dependency.

+
+
+
Example 20. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-databases</artifactId>
+        <version>2.0.0.M1</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+ + + + + +
+
Note
+		 +Enabling multiple JDBC-compliant databases will generate credentials +and store them by default in the same property keys hence property names for +JDBC secrets need to be configured separately. +
+
+
+

Apache Cassandra

+
+

Spring Cloud Vault can obtain credentials for Apache Cassandra. +The integration can be enabled by setting +spring.cloud.vault.cassandra.enabled=true (default false) and +providing the role name with spring.cloud.vault.cassandra.role=….

+
+
+

Username and password are stored in spring.data.cassandra.username +and spring.data.cassandra.password so using Spring Boot will pick +up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.cassandra.username-property and +spring.cloud.vault.cassandra.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    cassandra:
+        enabled: true
+        role: readonly
+        backend: cassandra
+        username-property: spring.data.cassandra.username
+        password-property: spring.data.cassandra.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the Cassandra backend config usage

    +
    • +
  • +

    role sets the role name of the Cassandra role definition

    +
    • +
  • +

    backend sets the path of the Cassandra mount to use

    +
    • +
  • +

    username-property sets the property name in which the Cassandra username is stored

    +
    • +
  • +

    password-property sets the property name in which the Cassandra password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up Apache Cassandra with Vault

+
+
+
+

MongoDB

+
+

Spring Cloud Vault can obtain credentials for MongoDB. +The integration can be enabled by setting +spring.cloud.vault.mongodb.enabled=true (default false) and +providing the role name with spring.cloud.vault.mongodb.role=….

+
+
+

Username and password are stored in spring.data.mongodb.username +and spring.data.mongodb.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mongodb.username-property and +spring.cloud.vault.mongodb.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    mongodb:
+        enabled: true
+        role: readonly
+        backend: mongodb
+        username-property: spring.data.mongodb.username
+        password-property: spring.data.mongodb.password
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the MongodB backend config usage

    +
    • +
  • +

    role sets the role name of the MongoDB role definition

    +
    • +
  • +

    backend sets the path of the MongoDB mount to use

    +
    • +
  • +

    username-property sets the property name in which the MongoDB username is stored

    +
    • +
  • +

    password-property sets the property name in which the MongoDB password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up MongoDB with Vault

+
+
+
+

MySQL

+
+

Spring Cloud Vault can obtain credentials for MySQL. +The integration can be enabled by setting +spring.cloud.vault.mysql.enabled=true (default false) and +providing the role name with spring.cloud.vault.mysql.role=….

+
+
+

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mysql.username-property and +spring.cloud.vault.mysql.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    mysql:
+        enabled: true
+        role: readonly
+        backend: mysql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the MySQL backend config usage

    +
    • +
  • +

    role sets the role name of the MySQL role definition

    +
    • +
  • +

    backend sets the path of the MySQL mount to use

    +
    • +
  • +

    username-property sets the property name in which the MySQL username is stored

    +
    • +
  • +

    password-property sets the property name in which the MySQL password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up MySQL with Vault

+
+
+
+

PostgreSQL

+
+

Spring Cloud Vault can obtain credentials for PostgreSQL. +The integration can be enabled by setting +spring.cloud.vault.postgresql.enabled=true (default false) and +providing the role name with spring.cloud.vault.postgresql.role=….

+
+
+

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.postgresql.username-property and +spring.cloud.vault.postgresql.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    postgresql:
+        enabled: true
+        role: readonly
+        backend: postgresql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the PostgreSQL backend config usage

    +
    • +
  • +

    role sets the role name of the PostgreSQL role definition

    +
    • +
  • +

    backend sets the path of the PostgreSQL mount to use

    +
    • +
  • +

    username-property sets the property name in which the PostgreSQL username is stored

    +
    • +
  • +

    password-property sets the property name in which the PostgreSQL password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up PostgreSQL with Vault

+
+
+
+
+
+

Configure PropertySourceLocator behavior

+
+
+

Spring Cloud Vault uses property-based configuration to create PropertySources +for generic and discovered secret backends.

+
+
+

Discovered backends provide VaultSecretBackendDescriptor beans to describe the configuration +state to use secret backend as PropertySource. A SecretBackendMetadataFactory is required +to create a SecretBackendMetadata object which contains path, name and property transformation +configuration.

+
+
+

SecretBackendMetadata is used to back a particular PropertySource.

+
+
+

You can register an arbitrary number of beans implementing VaultConfigurer for customization. +Default generic and discovered backend registration is disabled if Spring Cloud Vault discovers +at least one VaultConfigurer bean. You can however enable default registration with +SecretBackendConfigurer.registerDefaultGenericSecretBackends() and SecretBackendConfigurer.registerDefaultDiscoveredSecretBackends().

+
+
+
+
+
+
public class CustomizationBean implements VaultConfigurer {
+
+    @Override
+    public void addSecretBackends(SecretBackendConfigurer configurer) {
+
+        configurer.add("secret/my-application");
+
+        configurer.registerDefaultGenericSecretBackends(false);
+        configurer.registerDefaultDiscoveredSecretBackends(true);
+    }
+}
+
+
+
+
+
+ + + + + +
+
Note
+		 +All customization is required to happen in the bootstrap context. Add your configuration +classes to META-INF/spring.factories at org.springframework.cloud.bootstrap.BootstrapConfiguration +in your application. +
+
+
+
+
+

Vault Client Fail Fast

+
+
+

In some cases, it may be desirable to fail startup of a service if +it cannot connect to the Vault Server. If this is the desired +behavior, set the bootstrap configuration property +spring.cloud.vault.fail-fast=true and the client will halt with +an Exception.

+
+
+
+
+
+
spring.cloud.vault:
+    fail-fast: true
+
+
+
+
+
+
+
+

Vault Client SSL configuration

+
+
+

SSL can be configured declaratively by setting various properties. +You can set either javax.net.ssl.trustStore to configure +JVM-wide SSL settings or spring.cloud.vault.ssl.trust-store +to set SSL settings only for Spring Cloud Vault Config.

+
+
+
+
+
+
spring.cloud.vault:
+    ssl:
+        trust-store: classpath:keystore.jks
+        trust-store-password: changeit
+
+
+
+
+
+
    +
  • +

    trust-store sets the resource for the trust-store. SSL-secured Vault +communication will validate the Vault SSL certificate with the specified +trust-store.

    +
    • +
  • +

    trust-store-password sets the trust-store password

    +
    • +
+
+
+

Please note that configuring spring.cloud.vault.ssl.* can be only +applied when either Apache Http Components or the OkHttp client +is on your class-path.

+
+
+
+
+

Lease lifecycle management (renewal and revocation)

+
+
+

With every secret, Vault creates a lease: +metadata containing information such as a time duration, +renewability, and more.

+
+
+

Vault promises that the data will be valid for the given duration, +or Time To Live (TTL). Once the lease is expired, Vault can +revoke the data, and the consumer of the secret can no longer +be certain that it is valid.

+
+
+

Spring Cloud Vault maintains a lease lifecycle beyond +the creation of login tokens and secrets. That said, +login tokens and secrets associated with a lease +are scheduled for renewal just before the lease expires +until terminal expiry. +Application shutdown revokes obtained login tokens and renewable +leases.

+
+
+

Secret service and database backends (such as MongoDB or MySQL) +usually generate a renewable lease so generated credentials will +be disabled on application shutdown.

+
+
+ + + + + +
+
Note
+		 +Static tokens are not renewed or revoked. +
+
+
+

Lease renewal and revocation is enabled by default and can +be disabled by setting spring.cloud.vault.config.lifecycle.enabled +to false. This is not recommended as leases can expire and +Spring Cloud Vault cannot longer access Vault or services +using generated credentials and valid credentials remain active +after application shutdown.

+
+
+
+
+
+
spring.cloud.vault:
+    config.lifecycle.enabled: true
+
+
+
+
+
+

See also: Vault Documentation: Lease, Renew, and Revoke

+
+
+
+
+ + + + + \ No newline at end of file diff --git a/spring-cloud-vault/2.0.0.M2/ghpages.sh b/spring-cloud-vault/2.0.0.M2/ghpages.sh new file mode 100644 index 00000000..57c5da3a --- /dev/null +++ b/spring-cloud-vault/2.0.0.M2/ghpages.sh @@ -0,0 +1,330 @@ +#!/bin/bash -x + +set -e + +# Set default props like MAVEN_PATH, ROOT_FOLDER etc. +function set_default_props() { + # The script should be executed from the root folder + ROOT_FOLDER=`pwd` + echo "Current folder is ${ROOT_FOLDER}" + + if [[ ! -e "${ROOT_FOLDER}/.git" ]]; then + echo "You're not in the root folder of the project!" + exit 1 + fi + + # Prop that will let commit the changes + COMMIT_CHANGES="no" + MAVEN_PATH=${MAVEN_PATH:-} + echo "Path to Maven is [${MAVEN_PATH}]" + REPO_NAME=${PWD##*/} + echo "Repo name is [${REPO_NAME}]" + SPRING_CLOUD_STATIC_REPO=${SPRING_CLOUD_STATIC_REPO:-git@github.com:spring-cloud/spring-cloud-static.git} + echo "Spring Cloud Static repo is [${SPRING_CLOUD_STATIC_REPO}" +} + +# Check if gh-pages exists and docs have been built +function check_if_anything_to_sync() { + git remote set-url --push origin `git config remote.origin.url | sed -e 's/^git:/https:/'` + + if ! (git remote set-branches --add origin gh-pages && git fetch -q); then + echo "No gh-pages, so not syncing" + exit 0 + fi + + if ! [ -d docs/target/generated-docs ] && ! [ "${BUILD}" == "yes" ]; then + echo "No gh-pages sources in docs/target/generated-docs, so not syncing" + exit 0 + fi +} + +function retrieve_current_branch() { + # Code getting the name of the current branch. For master we want to publish as we did until now + # http://stackoverflow.com/questions/1593051/how-to-programmatically-determine-the-current-checked-out-git-branch + # If there is a branch already passed will reuse it - otherwise will try to find it + CURRENT_BRANCH=${BRANCH} + if [[ -z "${CURRENT_BRANCH}" ]] ; then + CURRENT_BRANCH=$(git symbolic-ref -q HEAD) + CURRENT_BRANCH=${CURRENT_BRANCH##refs/heads/} + CURRENT_BRANCH=${CURRENT_BRANCH:-HEAD} + fi + echo "Current branch is [${CURRENT_BRANCH}]" + git checkout ${CURRENT_BRANCH} || echo "Failed to check the branch... continuing with the script" +} + +# Switches to the provided value of the release version. We always prefix it with `v` +function switch_to_tag() { + git checkout v${VERSION} +} + +# Build the docs if switch is on +function build_docs_if_applicable() { + if [[ "${BUILD}" == "yes" ]] ; then + ./mvnw clean install -P docs -pl docs -DskipTests + fi +} + +# Get the name of the `docs.main` property +# Get whitelisted branches - assumes that a `docs` module is available under `docs` profile +function retrieve_doc_properties() { + MAIN_ADOC_VALUE=$("${MAVEN_PATH}"mvn -q \ + -Dexec.executable="echo" \ + -Dexec.args='${docs.main}' \ + --non-recursive \ + org.codehaus.mojo:exec-maven-plugin:1.3.1:exec) + echo "Extracted 'main.adoc' from Maven build [${MAIN_ADOC_VALUE}]" + + + WHITELIST_PROPERTY=${WHITELIST_PROPERTY:-"docs.whitelisted.branches"} + WHITELISTED_BRANCHES_VALUE=$("${MAVEN_PATH}"mvn -q \ + -Dexec.executable="echo" \ + -Dexec.args="\${${WHITELIST_PROPERTY}}" \ + org.codehaus.mojo:exec-maven-plugin:1.3.1:exec \ + -P docs \ + -pl docs) + echo "Extracted '${WHITELIST_PROPERTY}' from Maven build [${WHITELISTED_BRANCHES_VALUE}]" +} + +# Stash any outstanding changes +function stash_changes() { + git diff-index --quiet HEAD && dirty=$? || (echo "Failed to check if the current repo is dirty. Assuming that it is." && dirty="1") + if [ "$dirty" != "0" ]; then git stash; fi +} + +# Switch to gh-pages branch to sync it with current branch +function add_docs_from_target() { + local DESTINATION_REPO_FOLDER + if [[ -z "${DESTINATION}" && -z "${CLONE}" ]] ; then + DESTINATION_REPO_FOLDER=${ROOT_FOLDER} + elif [[ "${CLONE}" == "yes" ]]; then + mkdir -p ${ROOT_FOLDER}/target + local clonedStatic=${ROOT_FOLDER}/target/spring-cloud-static + if [[ ! -e "${clonedStatic}/.git" ]]; then + echo "Cloning Spring Cloud Static to target" + git clone ${SPRING_CLOUD_STATIC_REPO} ${clonedStatic} && git checkout gh-pages + else + echo "Spring Cloud Static already cloned - will pull changes" + cd ${clonedStatic} && git checkout gh-pages && git pull origin gh-pages + fi + DESTINATION_REPO_FOLDER=${clonedStatic}/${REPO_NAME} + mkdir -p ${DESTINATION_REPO_FOLDER} + else + if [[ ! -e "${DESTINATION}/.git" ]]; then + echo "[${DESTINATION}] is not a git repository" + exit 1 + fi + DESTINATION_REPO_FOLDER=${DESTINATION}/${REPO_NAME} + mkdir -p ${DESTINATION_REPO_FOLDER} + echo "Destination was provided [${DESTINATION}]" + fi + cd ${DESTINATION_REPO_FOLDER} + git checkout gh-pages + git pull origin gh-pages + + # Add git branches + ################################################################### + if [[ -z "${VERSION}" ]] ; then + copy_docs_for_current_version + else + copy_docs_for_provided_version + fi + commit_changes_if_applicable +} + + +# Copies the docs by using the retrieved properties from Maven build +function copy_docs_for_current_version() { + if [[ "${CURRENT_BRANCH}" == "master" ]] ; then + echo -e "Current branch is master - will copy the current docs only to the root folder" + for f in docs/target/generated-docs/*; do + file=${f#docs/target/generated-docs/*} + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then + # Not ignored... + cp -rf $f ${ROOT_FOLDER}/ + git add -A ${ROOT_FOLDER}/$file + fi + done + COMMIT_CHANGES="yes" + else + echo -e "Current branch is [${CURRENT_BRANCH}]" + # http://stackoverflow.com/questions/29300806/a-bash-script-to-check-if-a-string-is-present-in-a-comma-separated-list-of-strin + if [[ ",${WHITELISTED_BRANCHES_VALUE}," = *",${CURRENT_BRANCH},"* ]] ; then + mkdir -p ${ROOT_FOLDER}/${CURRENT_BRANCH} + echo -e "Branch [${CURRENT_BRANCH}] is whitelisted! Will copy the current docs to the [${CURRENT_BRANCH}] folder" + for f in docs/target/generated-docs/*; do + file=${f#docs/target/generated-docs/*} + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then + # Not ignored... + # We want users to access 1.0.0.RELEASE/ instead of 1.0.0.RELEASE/spring-cloud.sleuth.html + if [[ "${file}" == "${MAIN_ADOC_VALUE}.html" ]] ; then + # We don't want to copy the spring-cloud-sleuth.html + # we want it to be converted to index.html + cp -rf $f ${ROOT_FOLDER}/${CURRENT_BRANCH}/index.html + git add -A ${ROOT_FOLDER}/${CURRENT_BRANCH}/index.html + else + cp -rf $f ${ROOT_FOLDER}/${CURRENT_BRANCH} + git add -A ${ROOT_FOLDER}/${CURRENT_BRANCH}/$file + fi + fi + done + COMMIT_CHANGES="yes" + else + echo -e "Branch [${CURRENT_BRANCH}] is not on the white list! Check out the Maven [${WHITELIST_PROPERTY}] property in + [docs] module available under [docs] profile. Won't commit any changes to gh-pages for this branch." + fi + fi +} + +# Copies the docs by using the explicitly provided version +function copy_docs_for_provided_version() { + local FOLDER=${DESTINATION_REPO_FOLDER}/${VERSION} + mkdir -p ${FOLDER} + echo -e "Current tag is [v${VERSION}] Will copy the current docs to the [${FOLDER}] folder" + for f in ${ROOT_FOLDER}/docs/target/generated-docs/*; do + file=${f#${ROOT_FOLDER}/docs/target/generated-docs/*} + copy_docs_for_branch ${file} ${FOLDER} + done + COMMIT_CHANGES="yes" + CURRENT_BRANCH="v${VERSION}" +} + +# Copies the docs from target to the provided destination +# Params: +# $1 - file from target +# $2 - destination to which copy the files +function copy_docs_for_branch() { + local file=$1 + local destination=$2 + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^${file}$; then + # Not ignored... + # We want users to access 1.0.0.RELEASE/ instead of 1.0.0.RELEASE/spring-cloud.sleuth.html + if [[ ("${file}" == "${MAIN_ADOC_VALUE}.html") || ("${file}" == "${REPO_NAME}.html") ]] ; then + # We don't want to copy the spring-cloud-sleuth.html + # we want it to be converted to index.html + cp -rf $f ${destination}/index.html + git add -A ${destination}/index.html + else + cp -rf $f ${destination} + git add -A ${destination}/$file + fi + fi +} + +function commit_changes_if_applicable() { + if [[ "${COMMIT_CHANGES}" == "yes" ]] ; then + COMMIT_SUCCESSFUL="no" + git commit -a -m "Sync docs from ${CURRENT_BRANCH} to gh-pages" && COMMIT_SUCCESSFUL="yes" || echo "Failed to commit changes" + + # Uncomment the following push if you want to auto push to + # the gh-pages branch whenever you commit to master locally. + # This is a little extreme. Use with care! + ################################################################### + if [[ "${COMMIT_SUCCESSFUL}" == "yes" ]] ; then + git push origin gh-pages + fi + fi +} + +# Switch back to the previous branch and exit block +function checkout_previous_branch() { + # If -version was provided we need to come back to root project + cd ${ROOT_FOLDER} + git checkout ${CURRENT_BRANCH} || echo "Failed to check the branch... continuing with the script" + if [ "$dirty" != "0" ]; then git stash pop; fi + exit 0 +} + +# Assert if properties have been properly passed +function assert_properties() { +echo "VERSION [${VERSION}], DESTINATION [${DESTINATION}], CLONE [${CLONE}]" +if [[ "${VERSION}" != "" && (-z "${DESTINATION}" && -z "${CLONE}") ]] ; then echo "Version was set but destination / clone was not!"; exit 1;fi +if [[ ("${DESTINATION}" != "" && "${CLONE}" != "") && -z "${VERSION}" ]] ; then echo "Destination / clone was set but version was not!"; exit 1;fi +if [[ "${DESTINATION}" != "" && "${CLONE}" == "yes" ]] ; then echo "Destination and clone was set. Pick one!"; exit 1;fi +} + +# Prints the usage +function print_usage() { +cat </` +- if the destination switch is passed (-d) then the script will check if the provided dir is a git repo and then will + switch to gh-pages of that repo and copy the generated docs to `docs//` + +USAGE: + +You can use the following options: + +-v|--version - the script will apply the whole procedure for a particular library version +-d|--destination - the root of destination folder where the docs should be copied. You have to use the full path. + E.g. point to spring-cloud-static folder. Can't be used with (-c) +-b|--build - will run the standard build process after checking out the branch +-c|--clone - will automatically clone the spring-cloud-static repo instead of providing the destination. + Obviously can't be used with (-d) + +EOF +} + + +# ========================================== +# ____ ____ _____ _____ _____ _______ +# / ____|/ ____| __ \|_ _| __ \__ __| +# | (___ | | | |__) | | | | |__) | | | +# \___ \| | | _ / | | | ___/ | | +# ____) | |____| | \ \ _| |_| | | | +# |_____/ \_____|_| \_\_____|_| |_| +# +# ========================================== + +while [[ $# > 0 ]] +do +key="$1" +case ${key} in + -v|--version) + VERSION="$2" + shift # past argument + ;; + -d|--destination) + DESTINATION="$2" + shift # past argument + ;; + -b|--build) + BUILD="yes" + ;; + -c|--clone) + CLONE="yes" + ;; + -h|--help) + print_usage + exit 0 + ;; + *) + echo "Invalid option: [$1]" + print_usage + exit 1 + ;; +esac +shift # past argument or value +done + +assert_properties +set_default_props +check_if_anything_to_sync +if [[ -z "${VERSION}" ]] ; then + retrieve_current_branch +else + switch_to_tag +fi +build_docs_if_applicable +retrieve_doc_properties +stash_changes +add_docs_from_target +checkout_previous_branch \ No newline at end of file diff --git a/spring-cloud-vault/2.0.0.M2/index.html b/spring-cloud-vault/2.0.0.M2/index.html new file mode 100644 index 00000000..1043a07b --- /dev/null +++ b/spring-cloud-vault/2.0.0.M2/index.html @@ -0,0 +1,2137 @@ + + + + + + + +Spring Cloud Vault + + + + + +
+
+
+
+

© 2016-2017 The original authors.

+
+
+ + + + + +
+
Note
+		 +Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically. +
+
+
+

Spring Cloud Vault Config provides client-side support for externalized configuration in a distributed system. With HashiCorp’s Vault you have a central place to manage external secret properties for applications across all environments. Vault can manage static and dynamic secrets such as username/password for remote applications/resources and provide credentials for external services such as MySQL, PostgreSQL, Apache Cassandra, MongoDB, Consul, AWS and more.

+
+
+
+
+

Quick Start

+
+
+

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 7 and a properly configured JAVA_HOME environment variable

    +
    • +
+
+
+

Install Vault

+
+
+
+
$ src/test/bash/install_vault.sh
+
+
+
+

Create SSL certificates for Vault

+
+
+
+
$ src/test/bash/create_certificates.sh
+
+
+
+ + + + + +
+
Note
+		 +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. +
+
+
+

Start Vault server

+
+
+
+
$ src/test/bash/local_run_vault.sh
+
+
+
+

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.

+
+
+
+
$ export VAULT_ADDR="https://localhost:8200"
+$ export VAULT_SKIP_VERIFY=true # Don't do this for production
+$ vault init
+
+
+
+

You should see something like:

+
+
+
+
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.

+
+
+
+
$ vault unseal (Key 1)
+$ vault unseal (Key 2)
+$ vault 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

+
+
+

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:

+
+
+
Example 1. pom.xml
+
+
+
+
<parent>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-parent</artifactId>
+    <version>1.5.4.RELEASE</version>
+    <relativePath /> <!-- lookup parent from repository -->
+</parent>
+
+<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-starter-vault-config</artifactId>
+        <version>2.0.0.M2</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:

+
+
+
+
+
+
@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 bootstrap.properties (like application.properties but for +the bootstrap phase of an application context), e.g.

+
+
+
Example 2. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    host: localhost
+    port: 8200
+    scheme: https
+    uri: https://localhost:8200
+    connection-timeout: 5000
+    read-timeout: 15000
+    config:
+        order: -10
+
+
+
+
+
+
    +
  • +

    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

    +
    • +
  • +

    config.order sets the order for the property source

    +
    • +
+
+
+

Enabling further integrations requires additional dependencies and +configuration. Depending on how you have set up Vault you might need +additional configuration like +SSL and +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 health.vault.enabled (default true).

+
+
+

Authentication

+
+

Vault requires an authentication mechanism to authorize client requests.

+
+
+

Spring Cloud Vault supports multiple authentication mechanisms to authenticate applications with Vault.

+
+
+

For a quickstart, use the root token printed by the Vault initialization.

+
+
+
Example 3. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    token: 19aefa97-cccc-bbbb-aaaa-225940e63d76
+
+
+
+
+
+ + + + + +
+
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. +
+
+
+
+
+
+

Authentication methods

+
+
+

Different organizations have different requirements for security +and authentication. Vault reflects that need by shipping multiple authentication +methods. Spring Cloud Vault supports token and AppId authentication.

+
+
+

Token authentication

+
+

Tokens are the core method for authentication within Vault. +Token authentication requires a static token to be provided using the +Bootstrap Application Context.

+
+
+ + + + + +
+
Note
+		 +Token authentication is the default authentication method. +If a token is disclosed an unintended party gains access to Vault and +can access secrets for the intended client. +
+
+
+
Example 4. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: TOKEN
+    token: 00000000-0000-0000-0000-000000000000
+
+
+
+
+
+
    +
  • +

    authentication setting this value to TOKEN selects the Token +authentication method

    +
    • +
  • +

    token sets the static token to use

    +
    • +
+
+
+

See also: Vault Documentation: Tokens

+
+
+
+

AppId authentication

+
+

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 Cloud Vault Config 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.

+
+
+
Example 5. bootstrap.yml using SHA256 IP-Address UserId’s
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: IP_ADDRESS
+
+
+
+
+
+
    +
  • +

    authentication setting this value to APPID selects the AppId +authentication method

    +
    • +
  • +

    app-id-path sets the path of the AppId mount to use

    +
    • +
  • +

    user-id sets the UserId method. Possible values are IP_ADDRESS, +MAC_ADDRESS or a class name implementing a custom AppIdUserIdMechanism

    +
    • +
+
+
+

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

+
+
+
+
$ echo -n 192.168.99.1 | sha256sum
+
+
+
+ + + + + +
+
Note
+		 +Including the line break of echo leads to a different hash value +so make sure to include the -n flag. +
+
+
+

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).

+
+
+
Example 6. bootstrap.yml using SHA256 Mac-Address UserId’s
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: MAC_ADDRESS
+        network-interface: eth0
+
+
+
+
+
+
    +
  • +

    network-interface sets network interface to obtain the physical address

    +
    • +
+
+
+

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

+
+
+
+
$ echo -n 0AFEDE1234AC | sha256sum
+
+
+
+ + + + + +
+
Note
+		 +The Mac address is specified uppercase and without colons. +Including the line break of echo leads to a different hash value +so make sure to include the -n flag. +
+
+
+

Custom UserId

+
+

The UserId generation is an open mechanism. You can set +spring.cloud.vault.app-id.user-id to any string and the configured +value will be used as static UserId.

+
+
+

A more advanced approach lets you set spring.cloud.vault.app-id.user-id to a +classname. This class must be on your classpath and must implement +the org.springframework.cloud.vault.AppIdUserIdMechanism interface +and the createUserId method. Spring Cloud Vault will obtain the UserId +by calling createUserId each time it authenticates using AppId to +obtain a token.

+
+
+
Example 7. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: APPID
+    app-id:
+        user-id: com.examlple.MyUserIdMechanism
+
+
+
+
+
+
Example 8. MyUserIdMechanism.java
+
+
+
+
public class MyUserIdMechanism implements AppIdUserIdMechanism {
+
+  @Override
+  public String createUserId() {
+    String userId = ...
+    return userId;
+  }
+}
+
+
+
+
+
+

See also: Vault Documentation: Using the App ID auth backend

+
+
+
+
+

AppRole authentication

+
+

AppRole is intended for 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 (push or pull mode).

+
+
+

RoleId and optionally SecretId must be provided by configuration, +Spring Vault will not look up these or create a custom SecretId.

+
+
+
Example 9. bootstrap.yml with AppRole authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
+
+
+
+
+
+
    +
  • +

    role-id sets the RoleId.

    +
    • +
+
+
+
Example 10. bootstrap.yml with all AppRole authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: APPROLE
+    app-role:
+        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
+        secret-id: 1696536f-1976-73b1-b241-0b4213908d39
+        app-auth-path: approle
+
+
+
+
+
+
    +
  • +

    role-id sets the RoleId.

    +
    • +
  • +

    secret-id sets the SecretId. SecretId can be omitted if AppRole is configured without requiring SecretId (See bind_secret_id)

    +
    • +
  • +

    approle-path sets the path of the approle authentication mount to use

    +
    • +
+
+
+

See also: Vault Documentation: Using the AppRole auth backend

+
+
+
+

AWS-EC2 authentication

+
+

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.

+
+
+
Example 11. bootstrap.yml using AWS-EC2 Authentication
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+
+
+
+
+
+

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 Cloud 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. +You can configure a static nonce with spring.cloud.vault.aws-ec2.nonce.

+
+
+

AWS-EC2 authentication roles are optional and default to the AMI. +You can configure the authentication role by setting the +spring.cloud.vault.aws-ec2.role property.

+
+
+
Example 12. bootstrap.yml with configured role
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server
+
+
+
+
+
+
Example 13. bootstrap.yml with all AWS EC2 authentication properties
+
+
+
+
spring.cloud.vault:
+    authentication: AWS_EC2
+    aws-ec2:
+        role: application-server
+        aws-ec2-path: aws-ec2
+        identity-document: http://...
+        nonce: my-static-nonce
+
+
+
+
+
+
    +
  • +

    authentication setting this value to AWS_EC2 selects the AWS EC2 +authentication method

    +
    • +
  • +

    role sets the role name of the AWS EC2 role definition

    +
    • +
  • +

    aws-ec2-path sets the path of the AWS EC2 mount to use

    +
    • +
  • +

    identity-document sets URL of the PKCS#7 AWS EC2 identity document

    +
    • +
  • +

    nonce used for AWS-EC2 authentication. An empty nonce defaults to nonce generation

    +
    • +
+
+
+

See also: Vault Documentation: Using the aws-ec2 auth backend

+
+
+
+

TLS certificate authentication

+
+

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:

+
+
+
    +
  1. +

    Use SSL, see Vault Client SSL configuration

    +
    2. +
  2. +

    Configure a Java Keystore that contains the client +certificate and the private key

    +
    3. +
  3. +

    Set the spring.cloud.vault.authentication to CERT

    +
    4. +
+
+
+
Example 14. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: CERT
+    ssl:
+        key-store: classpath:keystore.jks
+        key-store-password: changeit
+        cert-auth-path: cert
+
+
+
+
+
+

See also: Vault Documentation: Using the Cert auth backend

+
+
+
+

Cubbyhole authentication

+
+

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 will be retrieved from a wrapped +response stored at /cubbyhole/response.

+
+
+

Creating a wrapped token

+
+
+ + + + + +
+
Note
+		 +Response Wrapping for token creation requires Vault 0.6.0 or higher. +
+
+
+
Example 15. Crating and storing tokens
+
+
+
+
$ vault token-create -wrap-ttl="10m"
+Key                            Value
+---                            -----
+wrapping_token:                397ccb93-ff6c-b17b-9389-380b01ca2645
+wrapping_token_ttl:            0h10m0s
+wrapping_token_creation_time:  2016-09-18 20:29:48.652957077 +0200 CEST
+wrapped_accessor:              46b6aebb-187f-932a-26d7-4f3d86a68319
+
+
+
+
+
+
Example 16. bootstrap.yml
+
+
+
+
spring.cloud.vault:
+    authentication: CUBBYHOLE
+    token: 397ccb93-ff6c-b17b-9389-380b01ca2645
+
+
+
+
+
+

See also:

+
+
+ +
+
+
+
+
+

Secret Backends

+
+
+

Generic Backend

+
+

Spring Cloud Vault supports at the basic level the generic secret +backend. The generic secret backend allows storage of arbitrary +values as key-value store. A single context can store one or many +key-value tuples. Contexts can be organized hierarchically. +Spring Cloud Vault allows using the Application name +and a default context name (application) in combination with active +profiles.

+
+
+
+
/secret/{application}/{profile}
+/secret/{application}
+/secret/{default-context}/{profile}
+/secret/{default-context}
+
+
+
+

The application name is determined by the properties:

+
+
+
    +
  • +

    spring.cloud.vault.generic.application-name

    +
    • +
  • +

    spring.cloud.vault.application-name

    +
    • +
  • +

    spring.application.name

    +
    • +
+
+
+

Secrets can be obtained from other folders within the generic backend by adding their +paths to the application name, separated by commas. For example, given the application +name usefulapp,mysql1,projectx/aws, each of these folders will be used:

+
+
+
    +
  • +

    /secret/usefulapp

    +
    • +
  • +

    /secret/mysql1

    +
    • +
  • +

    /secret/projectx/aws

    +
    • +
+
+
+

Spring Cloud Vault adds all active profiles to the list of possible context paths. +No active profiles will skip accessing contexts with a profile name.

+
+
+

Properties are exposed like they are stored (i.e. without additional prefixes).

+
+
+
+
+
+
spring.cloud.vault:
+    generic:
+        enabled: true
+        backend: secret
+        profile-separator: '/'
+        default-context: application
+        application-name: my-app
+
+
+
+
+
+
    +
  • +

    enabled setting this value to false disables the secret backend +config usage

    +
    • +
  • +

    backend sets the path of the secret mount to use

    +
    • +
  • +

    default-context sets the context name used by all applications

    +
    • +
  • +

    application-name overrides the application name for use in the generic backend

    +
    • +
  • +

    profile-separator separates the profile name from the context in +property sources with profiles

    +
    • +
+
+
+

See also: Vault Documentation: Using the generic secret backend

+
+
+
+

Consul

+
+

Spring Cloud Vault can obtain credentials for HashiCorp Consul. +The Consul integration requires the spring-cloud-vault-config-consul +dependency.

+
+
+
Example 17. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-consul</artifactId>
+        <version>2.0.0.M2</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.consul.enabled=true (default false) and +providing the role name with spring.cloud.vault.consul.role=….

+
+
+

The obtained token is stored in spring.cloud.consul.token +so using Spring Cloud Consul can pick up the generated +credentials without further configuration. You can configure +the property name by setting spring.cloud.vault.consul.token-property.

+
+
+
+
+
+
spring.cloud.vault:
+    consul:
+        enabled: true
+        role: readonly
+        backend: consul
+        token-property: spring.cloud.consul.token
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the Consul backend config usage

    +
    • +
  • +

    role sets the role name of the Consul role definition

    +
    • +
  • +

    backend sets the path of the Consul mount to use

    +
    • +
  • +

    token-property sets the property name in which the Consul ACL token is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up Consul with Vault

+
+
+
+

RabbitMQ

+
+

Spring Cloud Vault can obtain credentials for RabbitMQ.

+
+
+

The RabbitMQ integration requires the spring-cloud-vault-config-rabbitmq +dependency.

+
+
+
Example 18. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-rabbitmq</artifactId>
+        <version>2.0.0.M2</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.rabbitmq.enabled=true (default false) +and providing the role name with spring.cloud.vault.rabbitmq.role=….

+
+
+

Username and password are stored in spring.rabbitmq.username +and spring.rabbitmq.password so using Spring Boot will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.rabbitmq.username-property and +spring.cloud.vault.rabbitmq.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    rabbitmq:
+        enabled: true
+        role: readonly
+        backend: rabbitmq
+        username-property: spring.rabbitmq.username
+        password-property: spring.rabbitmq.password
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the RabbitMQ backend config usage

    +
    • +
  • +

    role sets the role name of the RabbitMQ role definition

    +
    • +
  • +

    backend sets the path of the RabbitMQ mount to use

    +
    • +
  • +

    username-property sets the property name in which the RabbitMQ username is stored

    +
    • +
  • +

    password-property sets the property name in which the RabbitMQ password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up RabbitMQ with Vault

+
+
+
+

AWS

+
+

Spring Cloud Vault can obtain credentials for AWS.

+
+
+

The AWS integration requires the spring-cloud-vault-config-aws +dependency.

+
+
+
Example 19. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-aws</artifactId>
+        <version>2.0.0.M2</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+

The integration can be enabled by setting +spring.cloud.vault.aws=true (default false) +and providing the role name with spring.cloud.vault.aws.role=….

+
+
+

The access key and secret key are stored in cloud.aws.credentials.accessKey +and cloud.aws.credentials.secretKey so using Spring Cloud AWS will pick up the generated +credentials without further configuration. You can configure the property names +by setting spring.cloud.vault.aws.access-key-property and +spring.cloud.vault.aws.secret-key-property.

+
+
+
+
+
+
spring.cloud.vault:
+    aws:
+        enabled: true
+        role: readonly
+        backend: aws
+        access-key-property: cloud.aws.credentials.accessKey
+        secret-key-property: cloud.aws.credentials.secretKey
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the AWS backend config usage

    +
    • +
  • +

    role sets the role name of the AWS role definition

    +
    • +
  • +

    backend sets the path of the AWS mount to use

    +
    • +
  • +

    access-key-property sets the property name in which the AWS access key is stored

    +
    • +
  • +

    secret-key-property sets the property name in which the AWS secret key is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up AWS with Vault

+
+
+
+
+
+

Database backends

+
+
+

Vault supports several database secret backends to generate database +credentials dynamically based on configured roles. This means +services that need to access a database no longer need to configure +credentials: they can request them from Vault, and use Vault’s leasing +mechanism to more easily roll keys.

+
+
+

Spring Cloud Vault integrates with these backends:

+
+
+ +
+
+

Using a database secret backend requires to enable the +backend in the configuration and the spring-cloud-vault-config-databases +dependency.

+
+
+
Example 20. pom.xml
+
+
+
+
<dependencies>
+    <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-vault-config-databases</artifactId>
+        <version>2.0.0.M2</version>
+    </dependency>
+</dependencies>
+
+
+
+
+
+ + + + + +
+
Note
+		 +Enabling multiple JDBC-compliant databases will generate credentials +and store them by default in the same property keys hence property names for +JDBC secrets need to be configured separately. +
+
+
+

Apache Cassandra

+
+

Spring Cloud Vault can obtain credentials for Apache Cassandra. +The integration can be enabled by setting +spring.cloud.vault.cassandra.enabled=true (default false) and +providing the role name with spring.cloud.vault.cassandra.role=….

+
+
+

Username and password are stored in spring.data.cassandra.username +and spring.data.cassandra.password so using Spring Boot will pick +up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.cassandra.username-property and +spring.cloud.vault.cassandra.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    cassandra:
+        enabled: true
+        role: readonly
+        backend: cassandra
+        username-property: spring.data.cassandra.username
+        password-property: spring.data.cassandra.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the Cassandra backend config usage

    +
    • +
  • +

    role sets the role name of the Cassandra role definition

    +
    • +
  • +

    backend sets the path of the Cassandra mount to use

    +
    • +
  • +

    username-property sets the property name in which the Cassandra username is stored

    +
    • +
  • +

    password-property sets the property name in which the Cassandra password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up Apache Cassandra with Vault

+
+
+
+

MongoDB

+
+

Spring Cloud Vault can obtain credentials for MongoDB. +The integration can be enabled by setting +spring.cloud.vault.mongodb.enabled=true (default false) and +providing the role name with spring.cloud.vault.mongodb.role=….

+
+
+

Username and password are stored in spring.data.mongodb.username +and spring.data.mongodb.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mongodb.username-property and +spring.cloud.vault.mongodb.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    mongodb:
+        enabled: true
+        role: readonly
+        backend: mongodb
+        username-property: spring.data.mongodb.username
+        password-property: spring.data.mongodb.password
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the MongodB backend config usage

    +
    • +
  • +

    role sets the role name of the MongoDB role definition

    +
    • +
  • +

    backend sets the path of the MongoDB mount to use

    +
    • +
  • +

    username-property sets the property name in which the MongoDB username is stored

    +
    • +
  • +

    password-property sets the property name in which the MongoDB password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up MongoDB with Vault

+
+
+
+

MySQL

+
+

Spring Cloud Vault can obtain credentials for MySQL. +The integration can be enabled by setting +spring.cloud.vault.mysql.enabled=true (default false) and +providing the role name with spring.cloud.vault.mysql.role=….

+
+
+

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.mysql.username-property and +spring.cloud.vault.mysql.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    mysql:
+        enabled: true
+        role: readonly
+        backend: mysql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the MySQL backend config usage

    +
    • +
  • +

    role sets the role name of the MySQL role definition

    +
    • +
  • +

    backend sets the path of the MySQL mount to use

    +
    • +
  • +

    username-property sets the property name in which the MySQL username is stored

    +
    • +
  • +

    password-property sets the property name in which the MySQL password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up MySQL with Vault

+
+
+
+

PostgreSQL

+
+

Spring Cloud Vault can obtain credentials for PostgreSQL. +The integration can be enabled by setting +spring.cloud.vault.postgresql.enabled=true (default false) and +providing the role name with spring.cloud.vault.postgresql.role=….

+
+
+

Username and password are stored in spring.datasource.username +and spring.datasource.password so using Spring Boot will +pick up the generated credentials without further configuration. +You can configure the property names by setting +spring.cloud.vault.postgresql.username-property and +spring.cloud.vault.postgresql.password-property.

+
+
+
+
+
+
spring.cloud.vault:
+    postgresql:
+        enabled: true
+        role: readonly
+        backend: postgresql
+        username-property: spring.datasource.username
+        password-property: spring.datasource.username
+
+
+
+
+
+
    +
  • +

    enabled setting this value to true enables the PostgreSQL backend config usage

    +
    • +
  • +

    role sets the role name of the PostgreSQL role definition

    +
    • +
  • +

    backend sets the path of the PostgreSQL mount to use

    +
    • +
  • +

    username-property sets the property name in which the PostgreSQL username is stored

    +
    • +
  • +

    password-property sets the property name in which the PostgreSQL password is stored

    +
    • +
+
+
+

See also: Vault Documentation: Setting up PostgreSQL with Vault

+
+
+
+
+
+

Configure PropertySourceLocator behavior

+
+
+

Spring Cloud Vault uses property-based configuration to create PropertySources +for generic and discovered secret backends.

+
+
+

Discovered backends provide VaultSecretBackendDescriptor beans to describe the configuration +state to use secret backend as PropertySource. A SecretBackendMetadataFactory is required +to create a SecretBackendMetadata object which contains path, name and property transformation +configuration.

+
+
+

SecretBackendMetadata is used to back a particular PropertySource.

+
+
+

You can register an arbitrary number of beans implementing VaultConfigurer for customization. +Default generic and discovered backend registration is disabled if Spring Cloud Vault discovers +at least one VaultConfigurer bean. You can however enable default registration with +SecretBackendConfigurer.registerDefaultGenericSecretBackends() and SecretBackendConfigurer.registerDefaultDiscoveredSecretBackends().

+
+
+
+
+
+
public class CustomizationBean implements VaultConfigurer {
+
+    @Override
+    public void addSecretBackends(SecretBackendConfigurer configurer) {
+
+        configurer.add("secret/my-application");
+
+        configurer.registerDefaultGenericSecretBackends(false);
+        configurer.registerDefaultDiscoveredSecretBackends(true);
+    }
+}
+
+
+
+
+
+ + + + + +
+
Note
+		 +All customization is required to happen in the bootstrap context. Add your configuration +classes to META-INF/spring.factories at org.springframework.cloud.bootstrap.BootstrapConfiguration +in your application. +
+
+
+
+
+

Service Registry Configuration

+
+
+

You can use a DiscoveryClient (such as from Spring Cloud Consul) to locate +a Vault server by setting spring.cloud.vault.discovery.enabled=true (default false). +The net result of that is that your apps need a bootstrap.yml (or an environment variable) +with the appropriate discovery configuration. +The benefit is that the Vault can change its co-ordinates, as long as the discovery service +is a fixed point. The default service id is vault but you can change that on the client with +spring.cloud.vault.discovery.serviceId.

+
+
+

The discovery client implementations all support some kind of metadata map +(e.g. for Eureka we have eureka.instance.metadataMap). Some additional properties of the service +may need to be configured in its service registration metadata so that clients can connect +correctly. Service registries that do not provide details about transport layer security +need to provide a scheme metadata entry to be set either to https or http. +If no scheme is configured and the service is not exposed as secure service, then +configuration defaults to spring.cloud.vault.scheme which is https when it’s not set.

+
+
+
+
+
+
spring.cloud.vault.discovery:
+    enabled: true
+    service-id: my-vault-service
+
+
+
+
+
+
+
+

Vault Client Fail Fast

+
+
+

In some cases, it may be desirable to fail startup of a service if +it cannot connect to the Vault Server. If this is the desired +behavior, set the bootstrap configuration property +spring.cloud.vault.fail-fast=true and the client will halt with +an Exception.

+
+
+
+
+
+
spring.cloud.vault:
+    fail-fast: true
+
+
+
+
+
+
+
+

Vault Client SSL configuration

+
+
+

SSL can be configured declaratively by setting various properties. +You can set either javax.net.ssl.trustStore to configure +JVM-wide SSL settings or spring.cloud.vault.ssl.trust-store +to set SSL settings only for Spring Cloud Vault Config.

+
+
+
+
+
+
spring.cloud.vault:
+    ssl:
+        trust-store: classpath:keystore.jks
+        trust-store-password: changeit
+
+
+
+
+
+
    +
  • +

    trust-store sets the resource for the trust-store. SSL-secured Vault +communication will validate the Vault SSL certificate with the specified +trust-store.

    +
    • +
  • +

    trust-store-password sets the trust-store password

    +
    • +
+
+
+

Please note that configuring spring.cloud.vault.ssl.* can be only +applied when either Apache Http Components or the OkHttp client +is on your class-path.

+
+
+
+
+

Lease lifecycle management (renewal and revocation)

+
+
+

With every secret, Vault creates a lease: +metadata containing information such as a time duration, +renewability, and more.

+
+
+

Vault promises that the data will be valid for the given duration, +or Time To Live (TTL). Once the lease is expired, Vault can +revoke the data, and the consumer of the secret can no longer +be certain that it is valid.

+
+
+

Spring Cloud Vault maintains a lease lifecycle beyond +the creation of login tokens and secrets. That said, +login tokens and secrets associated with a lease +are scheduled for renewal just before the lease expires +until terminal expiry. +Application shutdown revokes obtained login tokens and renewable +leases.

+
+
+

Secret service and database backends (such as MongoDB or MySQL) +usually generate a renewable lease so generated credentials will +be disabled on application shutdown.

+
+
+ + + + + +
+
Note
+		 +Static tokens are not renewed or revoked. +
+
+
+

Lease renewal and revocation is enabled by default and can +be disabled by setting spring.cloud.vault.config.lifecycle.enabled +to false. This is not recommended as leases can expire and +Spring Cloud Vault cannot longer access Vault or services +using generated credentials and valid credentials remain active +after application shutdown.

+
+
+
+
+
+
spring.cloud.vault:
+    config.lifecycle.enabled: true
+
+
+
+
+
+

See also: Vault Documentation: Lease, Renew, and Revoke

+
+
+
+
+ + + + + \ No newline at end of file