Spring CredHub

Spring CredHub provides client-side support for storing, retrieving, and deleting credentials from a CredHub server running in a Cloud Foundry platform.

Quick Start
Fork me on GitHub

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.

Features

  • Storing, retrieving, and deleting all CredHub credential types - user, password, certificate, RSA, SSH, value (arbitrary string), and JSON.
  • Generating credential types user, password, certificate, RSA, and SSH.
  • Interpolating Cloud Foundry service binding credentials that contain CredHub references.

Quick Start

Download

The recommended way to get started using spring-credhub in your project is with a dependency management system – the snippet below can be copied and pasted into your build. Need help? See our getting started guides on building with Maven and Gradle.

Configure CredHubTemplate

The class org.springframework.credhub.core.CredHubTemplate is the central class of Spring CredHub. The template offers convenience operations to write, retrieve, and delete credentials in CredHub and provides a mapping between client application domain objects and CredHub credentials.

Spring CredHub is initialized by providing Java Spring config like the following:

@Configuration
@Import(CredHubConfiguration.class)
public class AppConfig {
}

Inject and Use CredHubTemplate

This configuration will result in a CredHubTemplate bean being configured and added to the Spring application context. The CredHubTemplate can be 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.

Spring CredHub currently supports mutual TLS authentication with applications deployed to Cloud Foundry using 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.