Spring CredHub

Overview
Learn

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 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.

Inject and Use CredHubTemplate

The CredHubTemplate is used to interact with CredHub, typically used through its CredHubOperations interface.

The following is an example of setting a new credential in CredHub:

public class MyApp {
  @Autowired
  CredHubOperations credHubOperations;

  public void writeAndDeleteCredential() {
    PasswordCredentialRequest request =
      PasswordCredentialRequest.builder()
        .overwrite(true)
        .name(new SimpleCredentialName("spring-credhub", "demo"))
        .value(new PasswordCredential("secret"))
        .build();

    CredentialDetails<PasswordCredential> storedCredential =
        credHubOperations.write(request);

    CredentialDetails<PasswordCredential> retrievedCredential =
        credHubOperations.getById(storedCredential.getId());

    credHubOperations.deleteByName(storedCredential.getName());
  }
}

The following is an example of generating a new credential in CredHub:

public class MyApp {
  @Autowired
  CredHubOperations credHubOperations;

  public void generateCredential() {
    PasswordParametersRequest request =
      PasswordParametersRequest.builder()
        .overwrite(true)
        .name(new SimpleCredentialName("spring-credhub", "demo"))
        .parameters(PasswordParameters.builder()
            .length(20)
            .excludeLower(false)
            .excludeUpper(false)
            .excludeNumber(false)
            .includeSpecial(true)
            .build())
        .build();

    CredentialDetails<PasswordCredential> credential =
        credHubOperations.generate(request);
  }
}

Authentication

CredHub supports two authentication methods: mutual TLS and OAuth2.

Mutual TLS

Mutual TLS is the default authentication scheme used when no other authentication configuration is provided.

Mutual TLS support on Cloud Foundry requires the the Container Security Provider feature of the Java Buildpack. Applications using Spring CredHub should be deployed to Cloud Foundry using Java Buildpack 3.17 or greater, or 4.1 or greater.

OAuth2

The following configuration can be provided in a Spring Boot application using Spring CredHub (e.g. in application.yml) to enable OAuth2 authentication to a CredHub server.

spring:
  credhub:
    oauth2:
      client-id: [OAuth2 client ID]
      client-secret: [OAuth2 client secret]
      access-token-uri: [OAuth2 token server endpoint]

Spring Boot Config

The recommended way to get started using Spring CredHub in your project is with a dependency management system. One of the snippets below can be copied and pasted into your build.

With Maven:

<dependencies>
    <dependency>
        <groupId>org.springframework.credhub</groupId>
        <artifactId>spring-credhub-starter</artifactId>
        <version>1.0.1.RELEASE</version>
    </dependency>
</dependencies>

With Gradle:

dependencies {
  compile('org.springframework.credhub:spring-credhub-starter:1.0.1.RELEASE')
}

Spring CredHub will auto configure a CredHubTemplate if you provide the spring.credhub.url property to your Spring Boot application.

Quick start

Bootstrap your application with Spring Initializr.

Documentation

Each Spring project has its own; it explains in great details how you can use project features and what you can achieve with them.

2.0.0 M1 PRE	Reference Doc.	API Doc.
2.0.0 SNAPSHOT	Reference Doc.	API Doc.
1.0.1 GA	Reference Doc.	API Doc.