Add authentication to quickstart guide.

Fixes gh-30.
spring-cloud · Dec 14, 2016 · 501e701 · 501e701
1 parent 59541f0
commit 501e701
Show file tree

Hide file tree

Showing 3 changed files with 80 additions and 39 deletions.
diff --git a/README.adoc b/README.adoc
@@ -1,7 +1,7 @@
 // Do not edit this file (e.g. go instead to docs/src/main/asciidoc)
 
 
-Spring Cloud Vault Config provides client-side support for externalized configuration in a distributed system. With https://www.vaultproject.io[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.
+Spring Cloud Vault Config provides client-side support for externalized configuration in a distributed system. With https://www.vaultproject.io[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.
 
 == Features
 
@@ -51,6 +51,7 @@ $ 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`.
 
+[[quickstart.vault.start]]
 *Start Vault server*
 
 ----
@@ -119,43 +120,43 @@ 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
+Boot application that depends on `spring-cloud-vault-config` (e.g. see
 the test cases). Example Maven configuration:
 
 .pom.xml
 ====
-[source,xml,indent=0]
+[source,xml,indent=0,subs="verbatim,quotes,attributes"]
 ----
-    <parent>
+<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>{spring-cloud-version}</version>
+    </dependency>
+    <dependency>
         <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>
+        <artifactId>spring-boot-starter-test</artifactId>
+        <scope>test</scope>
+    </dependency>
+</dependencies>
+
+<build>
+    <plugins>
+        <plugin>
             <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 -->
+            <artifactId>spring-boot-maven-plugin</artifactId>
+        </plugin>
+    </plugins>
+</build>
+
+<!-- repositories also needed for snapshots and milestones -->
 ----
 ====
 
@@ -176,7 +177,6 @@ public class Application {
     public static void main(String[] args) {
         SpringApplication.run(Application.class, args);
     }
-
 }
 ----
 ====
@@ -220,14 +220,34 @@ chapters in the
 https://github.com/spring-cloud/spring-cloud-vault-config/blob/master/docs/src/main/asciidoc/spring-cloud-vault-config.adoc[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.
+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 https://www.vaultproject.io/docs/concepts/auth.html[authentication mechanism] to https://www.vaultproject.io/docs/concepts/tokens.html[authorize client requests].
+
+Spring Cloud Vault Config supports multiple http://cloud.spring.io/spring-cloud-vault-config/spring-cloud-vault-config.html#vault.config.authentication[authentication mechanisms] to authenticate applications with Vault.
+
+For a quickstart, use the root token printed by the <<quickstart.vault.start,Vault initialization>>.
+
+.bootstrap.yml
+====
+[source,yaml]
+----
+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.
+
 == Building
 
-==== Build requirements for Vault
+=== Build requirements for Vault
 
 Spring Cloud Vault Config requires SSL certificates and a running
 Vault instance listening on `localhost:8200`. Certificates and the Vault
@@ -306,11 +326,11 @@ a modified file in the correct place. Just commit it and push the change.
 If you don't have an IDE preference we would recommend that you use
 http://www.springsource.com/developer/sts[Spring Tools Suite] or
 http://eclipse.org[Eclipse] when working with the code. We use the
-http://eclipse.org/m2e/[m2eclipe] eclipse plugin for maven support. Other IDEs and tools
+http://eclipse.org/m2e/[m2eclipse] eclipse plugin for maven support. Other IDEs and tools
 should also work without issue as long as they use Maven 3.3.3 or better.
 
 ==== Importing into eclipse with m2eclipse
-We recommend the http://eclipse.org/m2e/[m2eclipe] eclipse plugin when working with
+We recommend the http://eclipse.org/m2e/[m2eclipse] eclipse plugin when working with
 eclipse. If you don't already have m2eclipse installed it is available from the "eclipse
 marketplace".
 

diff --git a/docs/src/main/asciidoc/README.adoc b/docs/src/main/asciidoc/README.adoc
@@ -31,7 +31,7 @@ include::quickstart.adoc[]
 
 == Building
 
-==== Build requirements for Vault
+=== Build requirements for Vault
 
 Spring Cloud Vault Config requires SSL certificates and a running
 Vault instance listening on `localhost:8200`. Certificates and the Vault

diff --git a/docs/src/main/asciidoc/quickstart.adoc b/docs/src/main/asciidoc/quickstart.adoc
@@ -20,6 +20,7 @@ $ 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`.
 
+[[quickstart.vault.start]]
 *Start Vault server*
 
 ----
@@ -88,7 +89,7 @@ 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
+Boot application that depends on `spring-cloud-vault-config` (e.g. see
 the test cases). Example Maven configuration:
 
 .pom.xml
@@ -188,7 +189,27 @@ chapters in the
 https://github.com/spring-cloud/spring-cloud-vault-config/blob/master/docs/src/main/asciidoc/spring-cloud-vault-config.adoc[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.
+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 https://www.vaultproject.io/docs/concepts/auth.html[authentication mechanism] to https://www.vaultproject.io/docs/concepts/tokens.html[authorize client requests].
+
+Spring Cloud Vault Config supports multiple http://cloud.spring.io/spring-cloud-vault-config/spring-cloud-vault-config.html#vault.config.authentication[authentication mechanisms] to authenticate applications with Vault.
+
+For a quickstart, use the root token printed by the <<quickstart.vault.start,Vault initialization>>.
+
+.bootstrap.yml
+====
+[source,yaml]
+----
+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.