A Guide to Spring CredHub

1. Overview

In this tutorial, we’ll implement Spring CredHub, a Spring abstraction of CredHub, to store secrets with access control rules that map credential resources to users and operations. Please note that before running the code, we need to make sure that we have our application running in the Cloud Foundry platform that has CredHub installed.

2. Maven Dependencies

First, we need to install the spring-credhub-starter dependency:

<dependency>
    <groupId>org.springframework.credhub</groupId>
    <artifactId>spring-credhub-starter</artifactId>
    <version>2.2.0</version>
</dependency>

3. Why Is Credential Management Important?

Credential management is the process of securely and centrally handling credentials throughout their lifecycle, which mainly includes generation, creation, rotation, and revocation. Even though the application and information technology environments of each company are very different from one another, there is one thing that is consistent: a credential, which is required by every application to get access to other apps, databases, or tools.

Credential management is vital for data security, as it gives users and applications access to sensitive information. Therefore, keeping them secured both in transit and at rest is important. One of the best strategies is to replace hardcoded credentials and their manual management with an API call to dedicated credential management tools like CredHub to retrieve them programmatically.

4. CredHub APIs

4.1. Authentication

There are two ways to authenticate CredHub APIs: UAA(OAuth2) and mutual TLS.

By default, CredHub provides integrated mutual TLS authentication. To use this scheme, specify the CredHub server’s URL in the application property:

spring:
  credhub:
    url: <CredHub URL>

Another method for authenticating APIs is via UAA, which requires client credentials grant token to obtain an access token:

spring:
  credhub:
    url: <CredHub URL>
    oauth2:
      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>

The access token can then be passed to the authorization header.

4.2. Credentials API

With the CredHubCredentialOperations interface, we can call CredHub APIs to create, update, retrieve, and delete credentials. The credential types that CredHub supports are:

• value – a string for a single configuration
• json – a JSON object for static configurations
• user – 3 strings – username, password, and password hash
• password – a string for passwords and other string credentials
• certificate – an object containing root CA, certificate, and private key
• rsa – an object containing a public key and private key
• ssh – an object containing SSH-formatted public key and private key

4.2. Permissions API

Permissions are provided when a credential is written to control what users can access, update or retrieve. Spring CredHub provides the CredHubPermissionV2Operations interface to create, update, retrieve and delete permissions. The operations that a user is allowed to perform on the credentials are: read, write, and delete.

5. CredHub Integration

We’ll now implement a Spring Boot application that returns Order details and will demonstrate a few examples to explain the complete lifecycle of credential management.

5.1. CredHubOperations Interface

The CredHubOperations interface is located in the org.springframework.credhub.core package. It is a central class of Spring’s CredHub, supporting a rich feature set to interact with CredHub. It provides access to interfaces that model entire CredHub APIs and maps between domain objects and CredHub data:

public class CredentialService {
    private final CredHubCredentialOperations credentialOperations;
    private final CredHubPermissionV2Operations permissionOperations;

    public CredentialService(CredHubOperations credHubOperations) {
        this.credentialOperations = credHubOperations.credentials();
        this.permissionOperations = credHubOperations.permissionsV2();
    }
}

5.2. Credential Creation

Let’s start with creating a new credential of type password, which is constructed using PasswordCredentialRequest:

SimpleCredentialName credentialName = new SimpleCredentialName(credential.getName());
PasswordCredential passwordCredential = new PasswordCredential((String) value.get("password"));
PasswordCredentialRequest request = PasswordCredentialRequest.builder()
  .name(credentialName)
  .value(passwordCredential)
  .build();
credentialOperations.write(request);

Similarly, other implementations of CredentialRequest can be used to build different credential types, such as ValueCredentialRequest for value credentials, RsaCredentialRequest for rsa credentials, and so on:

ValueCredential valueCredential = new ValueCredential((String) value.get("value"));
request = ValueCredentialRequest.builder()
  .name(credentialName)
  .value(valueCredential)
  .build();

RsaCredential rsaCredential = new RsaCredential((String) value.get("public_key"), (String) value.get("private_key"));
request = RsaCredentialRequest.builder()
  .name(credentialName)
  .value(rsaCredential)
  .build();

5.3. Credential Generation

Spring CredHub also provides an option to dynamically generate credentials to avoid the efforts involved in managing them on the application side. This, in turn, enhances data security. Let’s see how we can implement this functionality:

SimpleCredentialName credentialName = new SimpleCredentialName("api_key");
PasswordParameters parameters = PasswordParameters.builder()
  .length(24)
  .excludeUpper(false)
  .excludeLower(false)
  .includeSpecial(true)
  .excludeNumber(false)
  .build();

CredentialDetails<PasswordCredential> generatedCred = credentialOperations.generate(PasswordParametersRequest.builder()
  .name(credentialName)
  .parameters(parameters)
  .build());

String password = generatedCred.getValue().getPassword();

5.4. Credential Rotation and Revocation

Another important stage of credential management is rotating credentials. The code below demonstrates how we can achieve that with password credential type:

CredentialDetails<PasswordCredential> newPassword = credentialOperations.regenerate(credentialName, PasswordCredential.class);

CredHub also let certificate credential type have multiple active versions at the same time so that they can be rotated without any downtime. The final and most crucial phase of credential management is the revocation of credentials which can be implemented as below:

credentialOperations.deleteByName(credentialName);

5.5. Credential Retrieval

Now that we have an understanding of the complete credential management lifecycle. We’ll see how we can retrieve the most recent version of the password credential for Orders API authentication:

public ResponseEntity<Collection<Order>> getAllOrders() {
    try {
        String apiKey = credentialService.getPassword("api_key");
        return new ResponseEntity<>(getOrderList(apiKey), HttpStatus.OK);
    } catch (Exception e) {
        return new ResponseEntity<>(HttpStatus.FORBIDDEN);
    }
}

public String getPassword(String name) {
    SimpleCredentialName credentialName = new SimpleCredentialName(name);
    return credentialOperations.getByName(credentialName, PasswordCredential.class)
      .getValue()
      .getPassword();
}

5.6. Control Access to Credentials

Permission can be attached to a credential to limit access. For instance, a permission that grants access to a credential to a single user and enables that user to perform all the operations on a credential. Another permission can be attached that allows all the users to perform just the READ operation on a credential.

Let’s see an example of adding a permission to a credential that allows a user u101 to perform READ and WRITE operations:

Permission permission = Permission.builder()
  .app(UUID.randomUUID().toString())
  .operations(Operation.READ, Operation.WRITE)
  .user("u101")
  .build();
permissionOperations.addPermissions(name, permission);

Spring CredHub provides support for several other operations in addition to READ and WRITE, which allows the user(s) to:

• READ – Get a credential by id and name
• WRITE – Set, generate, and regenerate a credential by name
• DELETE – Delete a credential by name
• READ_ACL – Get ACL(Access Control List) by credential name
• WRITE_ACL – Add and delete an entry to credential ACL

6. Conclusion

In this tutorial, we’ve shown how to integrate CredHub with Spring Boot using the Spring CredHub library. We centralized the credential management for an Order application, covering two crucial aspects: credential lifecycle and permissions.