© 2017-2018 The original authors.

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 CredHub provides client-side support for storing, retrieving, and deleting credentials from a CredHub server running in a Cloud Foundry platform.

CredHub provides an 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.

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:

<dependencies>
    <dependency>
        <groupId>org.springframework.credhub</groupId>
        <artifactId>spring-credhub-starter</artifactId>
        <version>${version}</version>
    </dependency>
</dependencies>

Gradle Dependencies

Add the Spring CredHub starter to the dependencies section of the build file:

dependencies {
    compile('org.springframework.credhub:spring-credhub-starter:${version}')
}

Spring Boot Configuration

When using the Spring CredHub starter dependency, Spring CredHub can be configured with 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 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:


  
1
2
3


  
spring:
  credhub:
    url: [CredHub server URL]

See the CredHub documentation for more information on mutual TLS authentication.

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:


  
1
2
3
4
5
6
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]

The OAuth2 client identified by the client-id must have CredHub scopes such as credhub.read or credhub.write to perform most operations. See the CredHub documentation for more information on OAuth2 authentication with UAA.

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. CredHubOperations provides access to additional operations interfaces that model the full CredHub API:


  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


  
/**
 * 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 adding, retrieving, and deleting credential permissions.
 */
CredHubPermissionV2Operations permissionsV2();

/**
 * 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();

Mapping to CredHub API

Each method of the 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 Operations interface.

CredHub Credentials API

CredHubCredentialOperations

CredHub Permissions API (v1)

CredHubPermissionOperations

CredHub Permissions API (v2)

CredHubPermissionV2Operations

CredHub Certificates API

CredHubCertificateOperations

CredHub Interpolation API

CredHubInterpolationOperations

CredHub Information API

CredHubInfoOperations

CredHubOperations Auto-configuration

A CredHubOperations Spring bean 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.


  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
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<PasswordCredential> password = credHubOperations.credentials()
                                .generate(PasswordParametersRequest.builder()
                                                .name(credentialName)
                                                .parameters(parameters)
                                                .build());

                return password.getValue().getPassword();
        }

        public String getPassword() {
                CredentialDetails<PasswordCredential> password = credHubOperations.credentials()
                                .getByName(credentialName, PasswordCredential.class);

                return password.getValue().getPassword();
        }
}

HTTP Client Support

Spring CredHub supports multiple HTTP client libraries to communicate with the CredHub API. The following libraries are supported:

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:


  
1
2
3
4


  
<dependency>
  <groupId>org.apache.httpcomponents</groupId>
  <artifactId>httpclient</artifactId>
</dependency>

OkHttp 3

To use OkHttp 3 to communicate with CredHub, add the following dependency to the application:


  
1
2
3
4


  
<dependency>
  <groupId>com.squareup.okhttp3</groupId>
  <artifactId>okhttp</artifactId>
</dependency>

Netty

To use Netty to communicate with CredHub, add the following dependency to the application:


  
1
2
3
4


  
<dependency>
  <groupId>io.netty</groupId>
  <artifactId>netty-all</artifactId>
</dependency>