Add reactive support to docs. Modify OAuth2 config properties for clarity.

This commit is contained in:
Scott Frederick
2018-11-29 14:18:01 -06:00
parent 71788b0a18
commit 73c0271e23
18 changed files with 219 additions and 42 deletions

View File

@@ -16,6 +16,7 @@
package org.springframework.credhub.configuration;
import io.netty.channel.ChannelOption;
import io.netty.handler.ssl.SslContextBuilder;
import io.netty.handler.ssl.SslProvider;
import org.springframework.credhub.support.ClientOptions;
@@ -48,20 +49,20 @@ public class ClientHttpConnectorFactory {
TrustManagerFactory trustManagerFactory =
sslCertificateUtils.createTrustManagerFactory(options.getCaCertFiles());
httpClient.secure(sslContextSpec -> sslContextSpec
httpClient = httpClient.secure(sslContextSpec -> sslContextSpec
.sslContext(SslContextBuilder.forClient()
.sslProvider(SslProvider.JDK)
.trustManager(trustManagerFactory)));
} else {
httpClient.secure(sslContextSpec -> sslContextSpec
httpClient = httpClient.secure(sslContextSpec -> sslContextSpec
.sslContext(SslContextBuilder.forClient()
.sslProvider(SslProvider.JDK)));
}
if (options.getConnectionTimeout() != null) {
// httpClient.sslHandshakeTimeout(options.getConnectionTimeout());
// httpClient.option(ChannelOption.CONNECT_TIMEOUT_MILLIS,
// Math.toIntExact(options.getConnectionTimeout().toMillis()));
httpClient = httpClient.tcpConfiguration(tcpClient ->
tcpClient.option(ChannelOption.CONNECT_TIMEOUT_MILLIS,
Math.toIntExact(options.getConnectionTimeout().toMillis())));
}
return new ReactorClientHttpConnector(httpClient);

View File

@@ -76,7 +76,7 @@ public class CredHubProperties {
* Properties containing OAuth2 credentials for CredHub connectivity.
*/
public static class OAuth2 {
private String clientId;
private String registrationId;
/**
* Create a new instance without initializing properties.
@@ -85,21 +85,21 @@ public class CredHubProperties {
}
/**
* Get the OAuth2 client ID used to authenticate with CredHub.
* Get the OAuth2 client registration ID used to authenticate with CredHub.
*
* @return the OAuth2 client ID
* @return the OAuth2 registration ID
*/
public String getClientId() {
return clientId;
public String getRegistrationId() {
return registrationId;
}
/**
* Set the OAuth2 client ID used to authentiate with CredHub.
* Set the OAuth2 client registration ID used to authentiate with CredHub.
*
* @param clientId the OAuth2 client ID
* @param registrationId the OAuth2 client registration ID
*/
public void setClientId(String clientId) {
this.clientId = clientId;
public void setRegistrationId(String registrationId) {
this.registrationId = registrationId;
}
}
}

View File

@@ -87,7 +87,7 @@ class CredHubRestTemplateFactory {
configureRestTemplate(restTemplate, properties.getUrl(), clientHttpRequestFactory);
configureOAuth2(restTemplate, clientHttpRequestFactory,
properties.getOauth2().getClientId(),
properties.getOauth2().getRegistrationId(),
clientRegistrationRepository,
authorizedClientService);

View File

@@ -82,7 +82,7 @@ class CredHubWebClientFactory {
return buildWebClient(properties.getUrl(), clientHttpConnector)
.filter(oauth)
.defaultRequest(requestHeadersSpec ->
requestHeadersSpec.attributes(clientRegistrationId(properties.getOauth2().getClientId())))
requestHeadersSpec.attributes(clientRegistrationId(properties.getOauth2().getRegistrationId())))
.build();
}

View File

@@ -40,6 +40,7 @@ public class ExceptionUtils {
* Helper method to return an appropriate error if a request to CredHub
* returns with an error code.
*
* @return the generated error
* @param response a {@link ClientResponse} returned from {@link WebClient}
*/
public static Mono<Throwable> buildError(ClientResponse response) {

View File

@@ -77,9 +77,12 @@ public class ReactiveCredHubTemplate implements ReactiveCredHubOperations {
/**
* Create a new {@link ReactiveCredHubTemplate} using the provided base URI and
* {@link ClientHttpRequestFactory}.
*
* @param credHubProperties connection properties for the CredHub server
* @param clientHttpConnector the {@link ClientHttpConnector} to use when
* creating new connections
* @param clientRegistrationRepository a repository of OAuth2 client registrations
* @param authorizedClientRepository a repository of authorized OAuth2 clients
*/
public ReactiveCredHubTemplate(CredHubProperties credHubProperties, ClientHttpConnector clientHttpConnector,
ReactiveClientRegistrationRepository clientRegistrationRepository,

View File

@@ -21,6 +21,7 @@ plugins {
dependencyManagement {
imports {
mavenBom "org.springframework.boot:spring-boot-dependencies:${springBootVersion}"
mavenBom "io.projectreactor:reactor-bom:${reactorVersion}"
}
}
@@ -30,6 +31,7 @@ apply plugin: 'org.asciidoctor.convert'
dependencies {
compile project(":spring-credhub-core")
compile("io.projectreactor:reactor-core")
}
asciidoctor {

View File

@@ -1,11 +1,12 @@
:credhub-api-mtls: {credhub-api-home}version/2.0/#mutual-tls
:credhub-api-oauth: {credhub-api-home}version/2.0/#uaa-oauth2
:spring-boot-oauth: https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#boot-features-security-oauth2
[[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.
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].
With the proper configuration properties, Spring CredHub will auto-configure a connection to a CredHub server.
=== Mutual TLS Authentication
@@ -24,15 +25,20 @@ An application running on Cloud Foundry can use the internal address `https://cr
=== 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:
OAuth2 can be used to authenticate via UAA to any CredHub server.
Spring CredHub supports client credentials grant tokens for authentication using the following Spring CredHub and Spring Security 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.
The ID provided in `spring.credhub.oauth2.registration-id` must refer to a client configured under `spring.security.oauth2.client.registration`.
See the {spring-boot-oauth}[Spring Boot documentation] for more information on Spring Boot OAuth2 client configuration.
The OAuth2 client specified in the Spring Security client registration must have CredHub scopes such as `credhub.read` or `credhub.write` to perform most operations.
See the {credhub-api-oauth}[CredHub documentation] for more information on OAuth2 authentication with UAA.

View File

@@ -1,3 +1,6 @@
:spring-webflux: https://docs.spring.io/spring-framework/docs/current/spring-framework-reference/web-reactive.html#spring-webflux
:spring-security: https://spring.io/projects/spring-security
[[getting-started]]
== Getting started
@@ -5,7 +8,7 @@ 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.
To include Spring CredHub in a Spring Boot application, add some dependencies to the project build file.
=== Maven Dependencies
@@ -19,6 +22,31 @@ Add the Spring CredHub starter to the `dependencies` section of the build file:
</dependency>
</dependencies>
To enable reactive support in Spring CredHub, add the following {spring-webflux}[Spring WebFlux] dependency to the build file:
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webflux</artifactId>
<version>5.1.0.RELEASE</version>
</dependency>
</dependencies>
To use OAuth2 authentication to CredHub, add the following {spring-security}[Spring Security] dependencies to the build file:
<dependencies>
<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-config</artifactId>
<version>5.1.0.RELEASE</version>
</dependency>
<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-oauth2-client</artifactId>
<version>5.1.0.RELEASE</version>
</dependency>
</dependencies>
=== Gradle Dependencies
Add the Spring CredHub starter to the `dependencies` section of the build file:
@@ -27,3 +55,16 @@ Add the Spring CredHub starter to the `dependencies` section of the build file:
compile('org.springframework.credhub:spring-credhub-starter:${version}')
}
To enable reactive support in Spring CredHub, add the following {spring-webflux}[Spring WebFlux] dependency to the build file:
dependencies {
compile("org.springframework.boot:spring-boot-starter-webflux:5.1.0.RELEASE")
}
To use OAuth2 authentication to CredHub, add the following {spring-security}[Spring Security] dependencies to the build file:
dependencies {
compile("org.springframework.security:spring-security-config:5.1.0.RELEASE")
compile("org.springframework.security:spring-security-oauth2-client:5.1.0.RELEASE")
}

View File

@@ -1,7 +1,7 @@
[[http-clients]]
== HTTP Client Support
Spring CredHub supports multiple HTTP client libraries to communicate with the CredHub API. The following libraries are supported:
Spring CredHub `CredHubOperations` supports multiple HTTP client libraries to communicate with the CredHub API. The following libraries are supported:
* Javas builtin `HttpURLConnection` (default)
* https://hc.apache.org/[Apache HttpComponents]
@@ -11,6 +11,8 @@ Spring CredHub supports multiple HTTP client libraries to communicate with the C
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.
Spring CredHub `ReactiveCredHubOperations` only supports the Netty HTTP client library.
=== Apache HttpComponents
To use Apache HttpComponents to communicate with CredHub, add the following dependency to the application:

View File

@@ -11,6 +11,12 @@ Scott Frederick;
:examples-dir: ../../test/java/com/example/credhub/
:credhub-home: https://docs.cloudfoundry.org/credhub/
:credhub-api-home: https://credhub-api.cfapps.io/
:credhub-api-credentials: {credhub-api-home}version/2.0/#credentials
:credhub-api-certificates: {credhub-api-home}version/2.0/#certificates
:credhub-api-permissions: {credhub-api-home}version/1.9/#permissions
:credhub-api-permissionsV2: {credhub-api-home}version/2.0/#permissions
:credhub-api-interpolation: {credhub-api-home}version/2.0/#interpolate-endpoint
:credhub-api-info: {credhub-api-home}version/2.0/#get-version
:cloudfoundry-home: https://www.cloudfoundry.org/
:apidocs-home: https://docs.spring.io/spring-credhub/docs/{revnumber}/api/index.html
@@ -29,4 +35,5 @@ toc::[]
include::getting-started.adoc[]
include::boot-configuration.adoc[]
include::operations.adoc[]
include::reactive-operations.adoc[]
include::http-clients.adoc[]

View File

@@ -5,17 +5,10 @@
:apidocs-interpolation: {apidocs-home}?org/springframework/credhub/core/interpolation/CredHubInterpolationOperations.html
:apidocs-info: {apidocs-home}?org/springframework/credhub/core/info/CredHubInfoOperations.html
:credhub-api-credentials: {credhub-api-home}version/2.0/#credentials
:credhub-api-certificates: {credhub-api-home}version/2.0/#certificates
:credhub-api-permissions: {credhub-api-home}version/1.9/#permissions
:credhub-api-permissionsV2: {credhub-api-home}version/2.0/#permissions
:credhub-api-interpolation: {credhub-api-home}version/2.0/#interpolate-endpoint
:credhub-api-info: {credhub-api-home}version/2.0/#get-version
[[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.
The interface `org.springframework.credhub.core.CredHubOperations` and the implementation `org.springframework.credhub.core.CredHubTemplate` are the central classes in Spring CredHub.
`CredHubOperations` provides access to additional operations interfaces that model the full CredHub API:
[source,java,%autofit]
@@ -74,7 +67,3 @@ Application classes can autowire an instance of this bean to interact with a Cre
----
include::{examples-dir}/CredHubService.java[]
----

View File

@@ -0,0 +1,69 @@
:apidocs-reactive-credentials: {apidocs-home}?org/springframework/credhub/core/credential/ReactiveCredHubCredentialOperations.html
:apidocs-reactive-certificates: {apidocs-home}?org/springframework/credhub/core/certificate/ReactiveCredHubCertificateOperations.html
:apidocs-reactive-permissions: {apidocs-home}?org/springframework/credhub/core/permission/ReactiveCredHubPermissionOperations.html
:apidocs-reactive-permissionsV2: {apidocs-home}?org/springframework/credhub/core/permissionV2/ReactiveCredHubPermissionV2Operations.html
:apidocs-reactive-interpolation: {apidocs-home}?org/springframework/credhub/core/interpolation/ReactiveCredHubInterpolationOperations.html
:apidocs-reactive-info: {apidocs-home}?org/springframework/credhub/core/info/ReactiveCredHubInfoOperations.html
[[reactive-operations]]
== Introduction to ReactiveCredHubOperations
The interface `org.springframework.credhub.core.ReactiveCredHubOperations` and the implementation `org.springframework.credhub.core.ReactiveCredHubTemplate` are the central classes in Spring CredHub reactive support.
`ReactiveCredHubOperations` provides access to additional operations interfaces that model the full CredHub API:
[source,java,%autofit]
----
/**
* Get the operations for saving, retrieving, and deleting credentials.
*/
ReactiveCredHubCredentialOperations credentials();
/**
* Get the operations for adding, retrieving, and deleting credential permissions.
*/
ReactiveCredHubPermissionOperations permissions();
/**
* Get the operations for adding, retrieving, and deleting credential permissions.
*/
ReactiveCredHubPermissionV2Operations permissionsV2();
/**
* Get the operations for retrieving, regenerating, and updating certificates.
*/
ReactiveCredHubCertificateOperations certificates();
/**
* Get the operations for interpolating service binding credentials.
*/
ReactiveCredHubInterpolationOperations interpolation();
/**
* Get the operations for retrieving CredHub server information.
*/
ReactiveCredHubInfoOperations info();
----
=== Mapping to CredHub API
Each method of the `Reactive...Operations` interfaces maps directly to one endpoint of the CredHub HTTP API.
The following table shows the mapping between the CredHub API and the appropriate Spring CredHub `Reactive...Operations` interface.
|=======
| {credhub-api-credentials}[CredHub Credentials API] | {apidocs-reactive-credentials}[ReactiveCredHubCredentialOperations]
| {credhub-api-permissions}[CredHub Permissions API] (v1) | {apidocs-reactive-permissions}[ReactiveCredHubPermissionOperations]
| {credhub-api-permissionsV2}[CredHub Permissions API] (v2) | {apidocs-reactive-permissionsV2}[ReactiveCredHubPermissionV2Operations]
| {credhub-api-certificates}[CredHub Certificates API] | {apidocs-reactive-certificates}[ReactiveCredHubCertificateOperations]
| {credhub-api-interpolation}[CredHub Interpolation API] | {apidocs-reactive-interpolation}[ReactiveCredHubInterpolationOperations]
| {credhub-api-info}[CredHub Information API] | {apidocs-reactive-info}[CredHubInfoOperations]
|=======
=== ReactiveCredHubOperations Auto-configuration
A `ReactiveCredHubOperations` Spring bean is created using Spring Boot auto-configuration when application properties are properly configured and the Spring WebFlux library is on the classpath.
Application classes can autowire an instance of this bean to interact with a CredHub server.
[source,java,%autofit]
----
include::{examples-dir}/ReactiveCredHubService.java[]
----

View File

@@ -0,0 +1,45 @@
package com.example.credhub;
import org.springframework.credhub.core.ReactiveCredHubOperations;
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;
import reactor.core.publisher.Mono;
@Component
public class ReactiveCredHubService {
private final ReactiveCredHubOperations credHubOperations;
private final SimpleCredentialName credentialName;
public ReactiveCredHubService(ReactiveCredHubOperations credHubOperations) {
this.credHubOperations = credHubOperations;
credentialName = new SimpleCredentialName("example", "password");
}
public Mono<String> generatePassword() {
PasswordParameters parameters = PasswordParameters.builder()
.length(12)
.excludeLower(false)
.excludeUpper(false)
.excludeNumber(false)
.includeSpecial(true)
.build();
return credHubOperations.credentials()
.generate(PasswordParametersRequest.builder()
.name(credentialName)
.parameters(parameters)
.build(),
PasswordCredential.class)
.map(password -> password.getValue().getPassword());
}
public Mono<String> getPassword() {
return credHubOperations.credentials()
.getByName(credentialName, PasswordCredential.class)
.map(password -> password.getValue().getPassword());
}
}

View File

@@ -2,6 +2,16 @@ spring:
credhub:
url: [CredHub server URL]
oauth2:
client-id: [OAuth2 client ID]
client-secret: [OAuth2 client secret]
access-token-uri: [OAuth2 token server endpoint]
registration-id: credhub-client
security:
oauth2:
client:
registration:
credhub-client:
provider: uaa
client-id: [OAuth2 client ID]
client-secret: [OAuth2 client secret]
authorization-grant-type: client_credentials
provider:
uaa:
token-uri: [UAA token server endpoint]

View File

@@ -50,7 +50,7 @@ import org.springframework.web.reactive.function.client.WebClient;
CredHubOAuth2AutoConfiguration.class,
OAuth2ClientAutoConfiguration.class,
ReactiveOAuth2ClientAutoConfiguration.class})
@ConditionalOnProperty("spring.credhub.oauth2.client-id")
@ConditionalOnProperty("spring.credhub.oauth2.registration-id")
public class CredHubOAuth2TemplateAutoConfiguration {
private final CredHubTemplateFactory credHubTemplateFactory = new CredHubTemplateFactory();

View File

@@ -38,13 +38,13 @@ public class CredHubAutoConfigurationTests {
"spring.credhub.url=https://localhost",
"spring.credhub.connection-timeout=30",
"spring.credhub.read-timeout=60",
"spring.credhub.oauth2.client-id=test-client"
"spring.credhub.oauth2.registration-id=test-client"
)
.run((context) -> {
assertThat(context).hasSingleBean(CredHubProperties.class);
CredHubProperties properties = context.getBean(CredHubProperties.class);
assertThat(properties.getUrl()).isEqualTo("https://localhost");
assertThat(properties.getOauth2().getClientId()).isEqualTo("test-client");
assertThat(properties.getOauth2().getRegistrationId()).isEqualTo("test-client");
assertThat(context).hasSingleBean(ClientOptions.class);
ClientOptions options = context.getBean(ClientOptions.class);

View File

@@ -47,7 +47,8 @@ public class CredHubOAuth2TemplateAutoConfigurationTests {
CredHubTemplateAutoConfiguration.class))
.withPropertyValues(
"spring.credhub.url=https://localhost",
"spring.credhub.oauth2.client-id=credhub-client",
"spring.credhub.oauth2.registration-id=credhub-client",
"spring.security.oauth2.client.registration.credhub-client.provider=uaa",
"spring.security.oauth2.client.registration.credhub-client.client-id=test-client",
"spring.security.oauth2.client.registration.credhub-client.client-secret=test-secret",