diff --git a/src/main/asciidoc/reference/authentication.adoc b/src/main/asciidoc/reference/authentication.adoc index 37a24f33..e2a5665b 100644 --- a/src/main/asciidoc/reference/authentication.adoc +++ b/src/main/asciidoc/reference/authentication.adoc @@ -41,6 +41,7 @@ NOTE: Spring allows multiple ways to obtain `Environment`. When using `VaultProp See https://github.com/spring-projects/spring-vault/blob/master/spring-vault-core/src/test/java/org/springframework/vault/demo/SecurePropertyUsage.java[`SecurePropertyUsage.java`] for a sample on referencing properties in components and other property sources. +[[vault.authentication.token]] == Token authentication Tokens are the core method for authentication within Vault. @@ -184,6 +185,7 @@ public class MyUserIdMechanism implements AppIdUserIdMechanism { See also: https://www.vaultproject.io/docs/auth/app-id.html[Vault Documentation: Using the App ID auth backend] +[[vault.authentication.approle]] == AppRole authentication https://www.vaultproject.io/docs/auth/app-id.html[AppRole] allows machine @@ -222,6 +224,7 @@ class AppConfig extends AbstractVaultConfiguration { See also: https://www.vaultproject.io/docs/auth/approle.html[Vault Documentation: Using the AppRole auth backend] +[[vault.authentication.awsec2]] == AWS-EC2 authentication The https://www.vaultproject.io/docs/auth/aws-ec2.html[aws-ec2] @@ -271,6 +274,7 @@ it in `AwsEc2AuthenticationOptions`. See also: https://www.vaultproject.io/docs/auth/aws-ec2.html[Vault Documentation: Using the AWS-EC2 auth backend] +[[vault.authentication.clientcert]] == TLS certificate authentication The `cert` auth backend allows authentication using SSL/TLS client @@ -302,6 +306,7 @@ class AppConfig extends AbstractVaultConfiguration { See also: https://www.vaultproject.io/docs/auth/cert.html[Vault Documentation: Using the Cert auth backend] +[[vault.authentication.cubbyhole]] == Cubbyhole authentication Cubbyhole authentication uses Vault primitives to provide a secured authentication diff --git a/src/main/asciidoc/reference/dependencies.adoc b/src/main/asciidoc/reference/dependencies.adoc index 62fc186f..81828b2e 100644 --- a/src/main/asciidoc/reference/dependencies.adoc +++ b/src/main/asciidoc/reference/dependencies.adoc @@ -11,15 +11,15 @@ defined. In a Maven project you would declare this dependency in the [source, xml, subs="verbatim,attributes"] ---- - - - org.springframework.vault - spring-vault-dependencies - {version} - import - pom - - + + + org.springframework.vault + spring-vault-dependencies + {version} + import + pom + + ---- ==== @@ -39,10 +39,10 @@ pattern: `$\{version\}-$\{release\}` where release can be one of the following: [source, xml] ---- - - org.springframework.vault - spring-vault-core - + + org.springframework.vault + spring-vault-core + ---- ==== diff --git a/src/main/asciidoc/reference/getting-started.adoc b/src/main/asciidoc/reference/getting-started.adoc index 6ba397dc..238ba240 100644 --- a/src/main/asciidoc/reference/getting-started.adoc +++ b/src/main/asciidoc/reference/getting-started.adoc @@ -2,14 +2,14 @@ === Getting Started Spring Vault support requires Vault 0.5 or higher and Java SE 6 or higher. -An easy way to bootstrap setting up a working environment is to create a +An easy way to bootstrap setting up a working environment is to create a Spring based project in http://spring.io/tools/sts[STS]. -First you need to set up a running Vault server. +First you need to set up a running Vault server. Refer to the https://www.vaultproject.io/intro/[Vault] for an explanation on how to startup a Vault instance. -To create a Spring project in STS go to File -> New -> -Spring Template Project -> Simple Spring Utility Project -> +To create a Spring project in STS go to File -> New -> +Spring Template Project -> Simple Spring Utility Project -> press Yes when prompted. Then enter a project and a package name such as `org.spring.vault.example`. Then add the following to `pom.xml` dependencies section. @@ -20,30 +20,30 @@ Then add the following to `pom.xml` dependencies section. ---- - + - - org.springframework.vault - spring-vault-core - {version} - + + org.springframework.vault + spring-vault-core + {version} + ---- ==== -You will also need to add the location of the Spring Milestone repository for maven to your +You will also need to add the location of the Spring Milestone repository for maven to your `pom.xml` which is at the same level of your `` element. ==== [source,xml] ---- - - spring-milestone - Spring Maven MILESTONE Repository - http://repo.spring.io/libs-milestone - + + spring-milestone + Spring Maven MILESTONE Repository + http://repo.spring.io/libs-milestone + ---- ==== @@ -113,7 +113,7 @@ Even in this simple example, there are few things to take notice of * You can instantiate the central class of Spring Vault, <>, using the `org.springframework.vault.client.VaultClient` -object and the `ClientAuthentication`. +object and the `ClientAuthentication`. You are not required to spin up a Spring Context to use Spring Vault. * Vault is expected to be configured with a root token of `00000000-0000-0000-0000-000000000000` to run this application. @@ -132,7 +132,7 @@ is the central class of the Spring's Vault support providing a rich feature set interact with Vault. The template offers convenience operations to read, write and delete data in Vault and provides a mapping between your domain objects and Vault data. -NOTE: Once configured, `VaultTemplate` is thread-safe and can be reused across +NOTE: Once configured, `VaultTemplate` is thread-safe and can be reused across multiple instances. The mapping between Vault documents and domain classes is done by delegating to @@ -145,17 +145,17 @@ who are used to the API and CLI. For example, you will find methods such as "write", "delete", "read", and "revoke". The design goal was to make it as easy as possible to transition between the use of the Vault API and `VaultOperations`. A major difference in between -the two APIs is that `VaultOperations` can be passed domain objects instead of +the two APIs is that `VaultOperations` can be passed domain objects instead of JSON Key-Value pairs. -NOTE: The preferred way to reference the operations on `VaultTemplate` instance +NOTE: The preferred way to reference the operations on `VaultTemplate` instance is via its interface `VaultOperations`. While there are many convenience methods on `VaultTemplate` to help you easily perform common tasks if you should need to access the Vault API directly to access functionality not explicitly exposed by the `VaultTemplate` you can use one of several execute callback methods to access underlying APIs. The execute callbacks -will give you a reference to either a `RestTemplate` or a `VaultClient` object. +will give you a reference to either a `RestTemplate` or a `VaultClient` object. Please see the section <> for more information. Now let's look at a examples of how to work with Vault in the context of the Spring container. @@ -172,12 +172,12 @@ instances across your application. Spring Vault comes with a supporting configuration class that provides bean definitions for use inside a Spring context. Application configuration -classes typically extend from `AbstractVaultConfiguration` and are required to +classes typically extend from `AbstractVaultConfiguration` and are required to provide additional details that are environment specific. Extending from `AbstractVaultConfiguration` requires to implement ` VaultEndpoint vaultEndpoint()` and `ClientAuthentication clientAuthentication()` -methods. +methods. .Registering Spring Vault objects using Java based bean metadata ==== @@ -193,7 +193,7 @@ public class AppConfig extends AbstractVaultConfiguration { public VaultEndpoint vaultEndpoint() { return new VaultEndpoint(); <1> } - + /** * Configure a client authentication. * Please consider a more secure authentication method @@ -206,7 +206,7 @@ public class AppConfig extends AbstractVaultConfiguration { } ---- <1> Create a new `VaultEndpoint` that points by default to `https://localhost:8200`. -<2> This sample uses `TokenAuthentication` to get started quickly. +<2> This sample uses `TokenAuthentication` to get started quickly. See <> for details on supported authentication methods. ==== @@ -219,7 +219,7 @@ public class AppConfig extends AbstractVaultConfiguration { @Value("${vault.uri}") URI vaultUri; - + /** * Specify an endpoint that was injected as URI. */ @@ -227,9 +227,9 @@ public class AppConfig extends AbstractVaultConfiguration { public VaultEndpoint vaultEndpoint() { return VaultEndpoint.from(vaultUri); <1> } - + /** - * Configure a Client Certificate authentication. + * Configure a Client Certificate authentication. * {@link VaultClient} can be obtained from {@link #vaultClient()}. */ @Override @@ -247,18 +247,18 @@ public class AppConfig extends AbstractVaultConfiguration { [[vault.core.template.sessionmanagement]] === Session Management -Spring Vault requires a `ClientAuthentication` to login and access Vault. -See <> on details regarding authentication. -Vault login should not occur on each authenticated Vault interaction but -must be reused throughout a session. This aspect is handled by a -`SessionManager` implementation. A `SessionManager` decides how often it +Spring Vault requires a `ClientAuthentication` to login and access Vault. +See <> on details regarding authentication. +Vault login should not occur on each authenticated Vault interaction but +must be reused throughout a session. This aspect is handled by a +`SessionManager` implementation. A `SessionManager` decides how often it obtains a token, about revocation and renewal. Spring Vault comes with two implementations: -* `SimpleSessionManager`: Just obtains tokens from the supplied +* `SimpleSessionManager`: Just obtains tokens from the supplied `ClientAuthentication` without refresh and revocation -* `LifecycleAwareSessionManager`: This `SessionManager` schedules token -renewal if a token is renewable and revoke a login token on disposal. -Renewal is scheduled with an `AsyncTaskExecutor`. `LifecycleAwareSessionManager` +* `LifecycleAwareSessionManager`: This `SessionManager` schedules token +renewal if a token is renewable and revoke a login token on disposal. +Renewal is scheduled with an `AsyncTaskExecutor`. `LifecycleAwareSessionManager` is configured by default if using `AbstractVaultConfiguration`. [[vault.client-ssl]] @@ -295,19 +295,19 @@ is on your class-path. [[vault.core.propertysupport]] == Vault Property Source Support -Vault can be used in many different ways. One specific use-case is using -Vault to store encrypted properties. Spring Vault supports Vault as property +Vault can be used in many different ways. One specific use-case is using +Vault to store encrypted properties. Spring Vault supports Vault as property source to obtain configuration properties using Spring's http://docs.spring.io/spring-framework/docs/current/spring-framework-reference/html/beans.html#beans-property-source-abstraction[PropertySource abstraction]. NOTE: You can reference properties stored inside Vault in other property sources or use value injection with `@Value(…)`. Special attention is required when bootstrapping beans that require data stored inside of Vault. A `VaultPropertySource` must be initialized at that time to retrieve properties from Vault. - + NOTE: Spring Boot/Spring Cloud users can benefit from https://github.com/spring-cloud-incubator/spring-cloud-vault-config[Spring Cloud Vault]'s configuration integration that initializes various property sources during application startup. === Registering `VaultPropertySource` -Spring Vault provides a `VaultPropertySource` to be used with Vault to obtain -properties. It uses the nested `data` element to expose properties stored and +Spring Vault provides a `VaultPropertySource` to be used with Vault to obtain +properties. It uses the nested `data` element to expose properties stored and encrypted in Vault. ==== @@ -321,22 +321,22 @@ sources.addFirst(new VaultPropertySource(vaultTemplate, "secret/my-application") In the code above, `VaultPropertySource` has been added with highest precedence in the search. If it contains a ´foo` property, it will be detected and returned -ahead of any `foo` property in any other `PropertySource`. -`MutablePropertySources` exposes a number of methods that allow for precise +ahead of any `foo` property in any other `PropertySource`. +`MutablePropertySources` exposes a number of methods that allow for precise manipulation of the set of property sources. === @VaultPropertySource -The `@VaultPropertySource` annotation provides a convenient and declarative +The `@VaultPropertySource` annotation provides a convenient and declarative mechanism for adding a `PropertySource` to Spring’s `Environment`. To be used in conjunction with @Configuration classes. Example usage -Given a Vault path `secret/my-application` containing the configuration data -pair `database.password=mysecretpassword`, the following `@Configuration` -class uses `@VaultPropertySource` to contribute `secret/my-application` to +Given a Vault path `secret/my-application` containing the configuration data +pair `database.password=mysecretpassword`, the following `@Configuration` +class uses `@VaultPropertySource` to contribute `secret/my-application` to the `Environment`'s set of `PropertySources`. ==== @@ -358,37 +358,37 @@ public class AppConfig { ---- ==== -In certain situations, it may not be possible or practical to tightly control -property source ordering when using `@VaultPropertySource` annotations. -For example, if the @Configuration classes above were registered via -component-scanning, the ordering is difficult to predict. -In such cases - and if overriding is important - it is recommended that the -user fall back to using the programmatic PropertySource API. -See http://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/env/ConfigurableEnvironment.html[`ConfigurableEnvironment`] and +In certain situations, it may not be possible or practical to tightly control +property source ordering when using `@VaultPropertySource` annotations. +For example, if the @Configuration classes above were registered via +component-scanning, the ordering is difficult to predict. +In such cases - and if overriding is important - it is recommended that the +user fall back to using the programmatic PropertySource API. +See http://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/env/ConfigurableEnvironment.html[`ConfigurableEnvironment`] and http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/core/env/MutablePropertySources.html[`MutablePropertySources`] for details. [[vault.core.executioncallback]] == Execution callbacks -One common design feature of all Spring template classes is that all functionality -is routed into one of the templates execute callback methods. This helps ensure -that exceptions and any resource management that maybe required are performed -consistency. While this was of much greater need in the case of JDBC and JMS -than with Vault, it still offers a single spot for access and logging to occur. -As such, using the execute callback is the preferred way to access the Vault API +One common design feature of all Spring template classes is that all functionality +is routed into one of the templates execute callback methods. This helps ensure +that exceptions and any resource management that maybe required are performed +consistency. While this was of much greater need in the case of JDBC and JMS +than with Vault, it still offers a single spot for access and logging to occur. +As such, using the execute callback is the preferred way to access the Vault API to perform uncommon operations that we've not exposed as methods on `VaultTemplate`. Here is a list of execute callback methods. -* ` T` *doWithVault* `(ClientCallback clientCallback)` Executes the given +* ` T` *doWithVault* `(ClientCallback clientCallback)` Executes the given `ClientCallback`, allows to interact with Vault using `VaultClient` without requiring a session. -* ` T` *doWithVault* `(SessionCallback sessionCallback)` Executes the given +* ` T` *doWithVault* `(SessionCallback sessionCallback)` Executes the given `SessionCallback`, allows to interact with Vault in an authenticated session. -* ` T` *doWithRestTemplate* `(String pathTemplate, Map variables, RestTemplateCallback callback)` -Expands the `pathTemplate` to an `java.net.URI` and allows low-level interaction +* ` T` *doWithRestTemplate* `(String pathTemplate, Map variables, RestTemplateCallback callback)` +Expands the `pathTemplate` to an `java.net.URI` and allows low-level interaction with the underlying `org.springframework.web.client.RestTemplate`. diff --git a/src/main/asciidoc/reference/vault.adoc b/src/main/asciidoc/reference/vault.adoc index 3b4edae7..ce4e37a6 100644 --- a/src/main/asciidoc/reference/vault.adoc +++ b/src/main/asciidoc/reference/vault.adoc @@ -22,4 +22,3 @@ include::getting-started.adoc[] include::client-support.adoc[] include::authentication.adoc[] -