diff --git a/build.gradle b/build.gradle index 67a5a91..bf263e0 100644 --- a/build.gradle +++ b/build.gradle @@ -22,8 +22,9 @@ buildscript { } dependencies { classpath 'io.spring.gradle:propdeps-plugin:0.0.10.RELEASE' + classpath 'io.spring.gradle:dependency-management-plugin:1.0.5.RELEASE' classpath 'io.spring.gradle:spring-io-plugin:0.0.8.RELEASE' - classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.3' + classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.8' } } @@ -153,7 +154,7 @@ configure(rootProject) { destinationDir = new File(buildDir, "api") } - task docsZip(type: Zip) { + task docsZip(type: Zip, dependsOn: [':spring-credhub-docs:asciidoctor']) { group = 'Distribution' classifier = 'docs' description = "Builds -${classifier} archive containing api and reference " + @@ -162,16 +163,19 @@ configure(rootProject) { from(api) { into 'api' } + from(project.tasks.findByPath(':spring-credhub-docs:asciidoctor')) { + into 'reference' + } } artifacts { archives docsZip } -} -task dist(dependsOn: assemble) { - group = 'Distribution' - description = 'Builds -dist and -docs distribution archives.' + task dist(dependsOn: assemble) { + group = "Distribution" + description = "Builds -dist and -docs distribution archives." + } } wrapper { diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties index 115e6ac..a7017c3 100644 --- a/gradle/wrapper/gradle-wrapper.properties +++ b/gradle/wrapper/gradle-wrapper.properties @@ -1,5 +1,6 @@ +#Fri Oct 26 14:49:19 CDT 2018 distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists -distributionUrl=https\://services.gradle.org/distributions/gradle-4.10-bin.zip zipStoreBase=GRADLE_USER_HOME zipStorePath=wrapper/dists +distributionUrl=https\://services.gradle.org/distributions/gradle-4.10-all.zip diff --git a/settings.gradle b/settings.gradle index 1ec6a73..fd156d2 100644 --- a/settings.gradle +++ b/settings.gradle @@ -4,8 +4,10 @@ include ':spring-credhub-core' include ':spring-credhub-cloud-connector' include ':spring-credhub-starter' include ':spring-credhub-integration-tests' +include ':spring-credhub-docs' project(':spring-credhub-core').projectDir = "$rootDir/spring-credhub-core" as File project(':spring-credhub-cloud-connector').projectDir = "$rootDir/spring-credhub-cloud-connector" as File project(':spring-credhub-starter').projectDir = "$rootDir/spring-credhub-starter" as File project(':spring-credhub-integration-tests').projectDir = "$rootDir/spring-credhub-integration-tests" as File +project(':spring-credhub-docs').projectDir = "$rootDir/spring-credhub-docs" as File diff --git a/spring-credhub-demo/src/main/java/org/springframework/credhub/demo/CredHubDemoController.java b/spring-credhub-demo/src/main/java/org/springframework/credhub/demo/CredHubDemoController.java index ab2e81e..b85e15c 100644 --- a/spring-credhub-demo/src/main/java/org/springframework/credhub/demo/CredHubDemoController.java +++ b/spring-credhub-demo/src/main/java/org/springframework/credhub/demo/CredHubDemoController.java @@ -24,7 +24,6 @@ import java.util.Map; import java.util.UUID; import com.fasterxml.jackson.databind.ObjectMapper; -import org.springframework.beans.factory.annotation.Value; import org.springframework.credhub.core.CredHubOperations; import org.springframework.credhub.core.credential.CredHubCredentialOperations; import org.springframework.credhub.core.interpolation.CredHubInterpolationOperations; diff --git a/spring-credhub-docs/build.gradle b/spring-credhub-docs/build.gradle new file mode 100644 index 0000000..62305b1 --- /dev/null +++ b/spring-credhub-docs/build.gradle @@ -0,0 +1,35 @@ +/* + * Copyright 2016-2018 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +plugins { + id 'org.asciidoctor.convert' +} + +description = "Spring CredHub Documentation" + +apply plugin: 'org.asciidoctor.convert' + +dependencies { + compile project(":spring-credhub-core") +} + +asciidoctor { + sourceDir = file('src/docs/asciidoc') + attributes 'revnumber': project.version, + 'branch-or-tag': project.version.endsWith('SNAPSHOT') ? 'master' : "v${project.version}", + 'nofooter': true, + 'allow-uri-read': '' +} diff --git a/spring-credhub-docs/src/docs/asciidoc/boot-configuration.adoc b/spring-credhub-docs/src/docs/asciidoc/boot-configuration.adoc new file mode 100644 index 0000000..f2620c4 --- /dev/null +++ b/spring-credhub-docs/src/docs/asciidoc/boot-configuration.adoc @@ -0,0 +1,32 @@ +[[boot-configuration]] +== Spring Boot Configuration + +When using the Spring CredHub starter dependency, Spring CredHub can be configured with https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html#boot-features-external-config-application-property-files[Spring Boot application properties file]. +With the proper configuration, Spring CredHub will auto-configure a connection to a CredHub server. + +=== Mutual TLS Authentication + +An application running on Cloud Foundry can authenticate to a CredHub server deployed to the same platform using https://github.com/cloudfoundry-incubator/credhub/blob/master/docs/mutual-tls.md[mutual TLS]. +Mutual TLS is the default authentication scheme when no other authentication credentials are provided. +To use mutual TLS authentication to a CredHub server, simply provide the URL of the CredHub server as an application property: + +[source,properties,%autofit] +---- +include::{examples-dir}/config-minimal.yml[] +---- + +An application running on Cloud Foundry can use the internal address `https://credhub.service.cf.internal:8844` to communicate with a CredHub server deployed to the same platform. + +=== OAuth2 Authentication + +OAuth2 can be used to authenticate via UAA to any CredHub server via UAA. +Spring CredHub supports client credentials grant tokens for authentication with the following configuration: + +[source,properties,%autofit] +---- +include::{examples-dir}/config-oauth2.yml[] +---- + +The OAuth2 client identified by the `client-id` must have CredHub scopes such as `credhub.read` or `credhub.write` to perform most operations. + + diff --git a/spring-credhub-docs/src/docs/asciidoc/getting-started.adoc b/spring-credhub-docs/src/docs/asciidoc/getting-started.adoc new file mode 100644 index 0000000..41d0f38 --- /dev/null +++ b/spring-credhub-docs/src/docs/asciidoc/getting-started.adoc @@ -0,0 +1,29 @@ +[[getting-started]] +== Getting started + +Spring CredHub supports CredHub server version 1.x and 2.x. +This library is intended to provide full coverage of the CredHub API - all operations on all credential types. + +Spring CredHub has been optimized to work with Spring Boot applications. +To include Spring CredHub in a Spring Boot application, add a dependency to the project build file. + +=== Maven dependencies + +Add the Spring CredHub starter to the `dependencies` section of the build file: + + + + org.springframework.credhub + spring-credhub-starter + ${version} + + + +=== Gradle dependencies + +Add the Spring CredHub starter to the `dependencies` section of the build file: + + dependencies { + compile('org.springframework.credhub:spring-credhub-starter:${version}') + } + diff --git a/spring-credhub-docs/src/docs/asciidoc/http-clients.adoc b/spring-credhub-docs/src/docs/asciidoc/http-clients.adoc new file mode 100644 index 0000000..4982b7b --- /dev/null +++ b/spring-credhub-docs/src/docs/asciidoc/http-clients.adoc @@ -0,0 +1,48 @@ +[[http-clients]] +== HTTP Client Support + +Spring CredHub supports multiple HTTP client libraries to communicate with the CredHub API. The following libraries are supported: + +* Java’s builtin `HttpURLConnection` (default) +* https://hc.apache.org/[Apache HttpComponents] +* http://square.github.io/okhttp/[OkHttp 3] +* https://netty.io/[Netty] + +Choosing a specific client library requires the appropriate dependency to be available on the application classpath. +The application classpath will be inspected for each client library in the order listed above. + +=== Apache HttpComponents + +To use Apache HttpComponents to communicate with CredHub, add the following dependency to the application: + +[source,xml,%autofit] +---- + + org.apache.httpcomponents + httpclient + +---- + +=== OkHttp 3 + +To use OkHttp 3 to communicate with CredHub, add the following dependency to the application: + +[source,xml,%autofit] +---- + + com.squareup.okhttp3 + okhttp + +---- + +=== Netty + +To use Netty to communicate with CredHub, add the following dependency to the application: + +[source,xml,%autofit] +---- + + io.netty + netty-all + +---- diff --git a/spring-credhub-docs/src/docs/asciidoc/index.adoc b/spring-credhub-docs/src/docs/asciidoc/index.adoc new file mode 100644 index 0000000..dfdb034 --- /dev/null +++ b/spring-credhub-docs/src/docs/asciidoc/index.adoc @@ -0,0 +1,31 @@ += Spring CredHub +Scott Frederick; +:revdate: {localdate} +:doctype: book +:icons: font +:source-highlighter: highlightjs +:toc: left +:toclevels: 3 +:sectlinks: + +:examples-dir: ../../test/java/com/example/credhub/ +:credhub-home: https://docs.cloudfoundry.org/credhub/ +:credhub-api: https://credhub-api.cfapps.io/ +:cloudfoundry-home: https://www.cloudfoundry.org/ + +(C) 2017-2018 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._ + +[[abstract]] + +Spring CredHub provides client-side support for storing, retrieving, and deleting credentials from a {credhub-home}[CredHub] server running in a {cloudfoundry-home}[Cloud Foundry] platform. + +CredHub provides an {credhub-api}[HTTP API] to securely store, generate, retrieve, and delete credentials of various types. Spring CredHub provides a Java binding for the CredHub API, making it easy to integrate Spring applications with CredHub. + +toc::[] + +include::getting-started.adoc[] +include::boot-configuration.adoc[] +include::operations.adoc[] +include::http-clients.adoc[] diff --git a/spring-credhub-docs/src/docs/asciidoc/operations.adoc b/spring-credhub-docs/src/docs/asciidoc/operations.adoc new file mode 100644 index 0000000..205fb9a --- /dev/null +++ b/spring-credhub-docs/src/docs/asciidoc/operations.adoc @@ -0,0 +1,43 @@ +[[operations]] +== Introduction to CredHubOperations + +The interface `org.springframework.credhub.core.CredHubOperations` and the implementation `org.springframework.credhub.core.CredHubTemplate` are the central class in Spring CredHub. +A Spring bean of this type is created using Spring Boot auto-configuration when application properties are properly configured. +Application classes can autowire an instance of this bean to interact with a CredHub server. + +[source,java,%autofit] +---- +include::{examples-dir}/CredHubService.java[] +---- + +`CredHubOperations` provides access to additional operations interfaces that model the full CredHub API: + +[source,java,%autofit] +---- +/** + * Get the operations for saving, retrieving, and deleting credentials. + */ +CredHubCredentialOperations credentials(); + +/** + * Get the operations for adding, retrieving, and deleting credential permissions. + */ +CredHubPermissionOperations permissions(); + +/** + * Get the operations for retrieving, regenerating, and updating certificates. + */ +CredHubCertificateOperations certificates(); + +/** + * Get the operations for interpolating service binding credentials. + */ +CredHubInterpolationOperations interpolation(); + +/** + * Get the operations for retrieving CredHub server information. + */ +CredHubInfoOperations info(); +---- + + diff --git a/spring-credhub-docs/src/test/java/com/example/credhub/CredHubService.java b/spring-credhub-docs/src/test/java/com/example/credhub/CredHubService.java new file mode 100644 index 0000000..cd2f475 --- /dev/null +++ b/spring-credhub-docs/src/test/java/com/example/credhub/CredHubService.java @@ -0,0 +1,46 @@ +package com.example.credhub; + +import org.springframework.credhub.core.CredHubOperations; +import org.springframework.credhub.support.CredentialDetails; +import org.springframework.credhub.support.SimpleCredentialName; +import org.springframework.credhub.support.password.PasswordCredential; +import org.springframework.credhub.support.password.PasswordParameters; +import org.springframework.credhub.support.password.PasswordParametersRequest; +import org.springframework.stereotype.Component; + +@Component +public class CredHubService { + private final CredHubOperations credHubOperations; + private final SimpleCredentialName credentialName; + + public CredHubService(CredHubOperations credHubOperations) { + this.credHubOperations = credHubOperations; + + credentialName = new SimpleCredentialName("example", "password"); + } + + public String generatePassword() { + PasswordParameters parameters = PasswordParameters.builder() + .length(12) + .excludeLower(false) + .excludeUpper(false) + .excludeNumber(false) + .includeSpecial(true) + .build(); + + CredentialDetails password = credHubOperations.credentials() + .generate(PasswordParametersRequest.builder() + .name(credentialName) + .parameters(parameters) + .build()); + + return password.getValue().getPassword(); + } + + public String getPassword() { + CredentialDetails password = credHubOperations.credentials() + .getByName(credentialName, PasswordCredential.class); + + return password.getValue().getPassword(); + } +} diff --git a/spring-credhub-docs/src/test/java/com/example/credhub/config-minimal.yml b/spring-credhub-docs/src/test/java/com/example/credhub/config-minimal.yml new file mode 100644 index 0000000..7395e79 --- /dev/null +++ b/spring-credhub-docs/src/test/java/com/example/credhub/config-minimal.yml @@ -0,0 +1,3 @@ +spring: + credhub: + url: [CredHub server URL] \ No newline at end of file diff --git a/spring-credhub-docs/src/test/java/com/example/credhub/config-oauth2.yml b/spring-credhub-docs/src/test/java/com/example/credhub/config-oauth2.yml new file mode 100644 index 0000000..baedcc6 --- /dev/null +++ b/spring-credhub-docs/src/test/java/com/example/credhub/config-oauth2.yml @@ -0,0 +1,7 @@ +spring: + credhub: + url: [CredHub server URL] + oauth2: + client-id: [OAuth2 client ID] + client-secret: [OAuth2 client secret] + access-token-uri: [OAuth2 token server endpoint] \ No newline at end of file