Java application demo

Once you have learned the fundamentals of Vault, the next step is to integrate your systems and applications with Vault to secure your organization's secrets.

This tutorial is a companion to a webinar that includes a live demo of how to manage secrets, access, and encryption in the public cloud with Vault.

Challenge

Incidents of data breaches which expose sensitive information make headlines more often than you would like to hear. It becomes more and more important to protect data by encrypting it whether the data is in-transit or at-rest. However, creating a highly secure and sophisticated solution by yourself requires time and resources which are in demand when an organization is facing a constant threat.

Solution

Vault centralizes management of cryptographic services used to protect your data. Your system can communicate with Vault easily through the Vault API to encrypt and decrypt your data, and the encryption keys never have to leave the Vault.

Prerequisites

This lab was tested on macOS using an x86_64 based processor. If you are running macOS on an Apple silicon-based processor, use a x86_64 based Linux virtual machine in your preferred cloud provider.

To perform the tasks described in this tutorial you must have:

• HashiCorp Vagrant installed
• tree installed
• git installed

Review the demo application implementation

Retrieve the configuration by cloning or downloading the hashicorp-education/learn-vault-spring-cloud repository from GitHub.

1. Clone the repository.

   $ git clone https://github.com/hashicorp-education/learn-vault-spring-cloud
   

   Copy

   Or download the repository.

   

   The repository contains supporting content for this Java application tutorial.

2. Review the demo application's source code directory structure.

   $ tree learn-vault-spring-cloud/src/main
   .
   ├── java
   │   └── com
   │       └── hashicorp
   │           └── vault
   │               └── spring
   │                   └── demo
   │                       ├── BeanUtil.java
   │                       ├── Order.java
   │                       ├── OrderAPIController.java
   │                       ├── OrderRepository.java
   │                       ├── Secret.java
   │                       ├── SecretController.java
   │                       ├── TransitConverter.java
   │                       └── VaultDemoOrderServiceApplication.java
   └── resources
       └── application.yaml
   
   8 directories, 9 files
   

   Copy

   The Java application in this demo leverages the Spring Cloud Vault library which provides lightweight client-side support for connecting to Vault in a distributed environment.

   In the TransitConverter class, the convertToDatabaseColumn method on line 11 invokes a Vault operation to encrypt the order. Similarly, the convertToEntityAttribute method on line 19 decrypts the order data.

   TransitConverter.java

   1 2 3 4 5 6 7 8 9 1011121314151617181920212223242526package com.hashicorp.vault.spring.demo;
   
   import javax.persistence.AttributeConverter;
   import org.springframework.vault.core.VaultOperations;
   import org.springframework.vault.support.Ciphertext;
   import org.springframework.vault.support.Plaintext;
   
   public class TransitConverter implements AttributeConverter<String, String> {
   
           @Override
           public String convertToDatabaseColumn(String customer) {
                   VaultOperations vaultOps = BeanUtil.getBean(VaultOperations.class);
                   Plaintext plaintext = Plaintext.of(customer);
                   String cipherText = vaultOps.opsForTransit().encrypt("order", plaintext).getCiphertext();
                   return cipherText;
           }
   
           @Override
           public String convertToEntityAttribute(String customer) {
                   VaultOperations vaultOps = BeanUtil.getBean(VaultOperations.class);
                   Ciphertext ciphertext = Ciphertext.of(customer);
           String plaintext = vaultOps.opsForTransit().decrypt("order", ciphertext).asString();
                   return plaintext;
           }
   
   }
   

   The VaultDemoOrderServiceApplication class defines the main method.

   VaultDemoOrderServiceApplication.java

   1 2 3 4 5 6 7 8 9 10111213141516171819202122232425262728293031323334353637package com.hashicorp.vault.spring.demo;
   
   import javax.annotation.PostConstruct;
   
   import org.slf4j.Logger;
   import org.slf4j.LoggerFactory;
   import org.springframework.beans.factory.annotation.Autowired;
   import org.springframework.beans.factory.annotation.Value;
   import org.springframework.boot.SpringApplication;
   import org.springframework.boot.autoconfigure.SpringBootApplication;
   import org.springframework.vault.authentication.SessionManager;
   
   @SpringBootApplication
   public class VaultDemoOrderServiceApplication  {
   
           private static final Logger logger = LoggerFactory.getLogger(VaultDemoOrderServiceApplication.class);
   
           @Autowired
           private SessionManager sessionManager;
   
           @Value("${spring.datasource.username}")
           private String dbUser;
   
           @Value("${spring.datasource.password}")
           private String dbPass;
   
           public static void main(String[] args) {
                   SpringApplication.run(VaultDemoOrderServiceApplication.class, args);
           }
   
           @PostConstruct
           public void initIt() throws Exception {
                   logger.info("Got Vault Token: " + sessionManager.getSessionToken().getToken());
                   logger.info("Got DB User: " + dbUser);
                   //logger.info("Got DB Pass: " + dbPass);
           }
   }
   

   The OrderAPIController class defines the API endpoint (api/orders).

   OrderAPIController.java

   1 2 3 4 5 6 7 8 9 101112131415161718192021222324252627282930313233343536package com.hashicorp.vault.spring.demo;
   
   import org.springframework.http.HttpStatus;
   import org.springframework.http.ResponseEntity;
   import org.springframework.web.bind.annotation.*;
   import javax.inject.Inject;
   import java.util.Collection;
   
   @RestController
   @RequestMapping("/api/orders")
   public class OrderAPIController {
   
           private OrderRepository repository;
   
           @Inject
           public void setRepository(OrderRepository repository) {
                   this.repository = repository;
   
           }
   
           @RequestMapping(method = RequestMethod.POST)
           public ResponseEntity<?> addOrder(@RequestBody Order order) {
                   return new ResponseEntity<>(repository.save(order), HttpStatus.CREATED);
           }
   
           @RequestMapping(method = RequestMethod.GET)
           public ResponseEntity<Collection<Order>> getAllOrders() {
                   return new ResponseEntity<>(repository.findAll(), HttpStatus.OK);
           }
   
           @RequestMapping(method = RequestMethod.DELETE)
           public void deleteAllOrders() {
                   repository.deleteAll();
           }
   
   }
   

Deploy and review the demo environment

For this tutorial, you will provision a Linux machine locally using Vagrant. The GitHub repository provides supporting files to provision the environment demonstrated in the webinar.

The learn-vault-spring-cloud/vagrant-local directory contains a Vagrantfile that starts a Linux machine and configures the demo environment.

1. Change the working directory to vagrant-local.

   $ cd learn-vault-spring-cloud/vagrant-local
   

   Copy

2. Run vagrant up to start the demo environment. This takes about 3 minutes.

   $ vagrant up
   Bringing machine 'demo' up with 'virtualbox' provider...
   ...snip...
   demo: Success! Data written to: database/roles/order
   demo: Success! Enabled the transit secrets engine at: transit/
   demo: Success! Data written to: transit/keys/order
   demo: Success! Data written to: secret/spring-vault-demo
   

   Copy

3. Verify the virtual machine was successfully created and running.

   $ vagrant status
   Current machine states:
   demo                      running (virtualbox)
   ...
   

   Copy

4. Connect to the demo Vagrant virtual machine.

   $ vagrant ssh demo
   

   Copy

5. Review the demo environment.

   $ docker ps
   CONTAINER ID        IMAGE                  COMMAND                  ...    NAMES
   cd629a609847        spring                 "java -Djava.secur..."   ...    spring
   623217149b68        hashicorp/vault:latest "docker-entrypoint..."   ...    vault
   32ff06ac02da        postgres:14-bullseye   "docker-entrypoint..."   ...    postgres
   

   Copy

   There are 3 Docker containers running on the machine: spring, vault, and postgres.

Examine the Vault environment

During the demo machine provisioning, the /scripts/vault.sh script was executed to perform the following:

• Created a policy named order
• Enabled the transit secrets engine and created an encryption key named order
• Enabled the database secrets engine and created a role named order

1. View the vault log.

   $ docker logs vault
   
   ==> Vault server configuration:
                Api Address: http://0.0.0.0:8200
                        Cgo: disabled
            Cluster Address: https://0.0.0.0:8201
                 Listener 1: tcp (addr: "0.0.0.0:8200", cluster address: "0.0.0.0:8201", max_request_duration: "1m30s", max_request_size: "33554432", tls: "disabled")
                  Log Level: info
                      Mlock: supported: true, enabled: false
              Recovery Mode: false
                    Storage: inmem
                    Version: Vault v1.3.1
   WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
   and starts unsealed with a single unseal key. The root token is already
   authenticated to the CLI, so you can immediately begin using Vault.
   You may need to set the following environment variable:
       $ export VAULT_ADDR='http://0.0.0.0:8200'
   The unseal key and root token are displayed below in case you want to
   seal/unseal the Vault or re-authenticate.
   Unseal Key: Wgx++e73Y/htvXYzSZHAQ/3iE+Q0cuaBvTsM4ujn2xA=
   Root Token: root
   

   Copy

   The log indicates that the Vault server is running in the dev mode, and the root token is root.

2. Visit the Vault UI at http://localhost:8200/ui. Enter root and click Sign In.

3. Select the transit/ secrets engine, and you should find an encryption key named order.

4. Click Policies, then click order to view the policy.

   The order policy is for the application. It permits read on the database/creds/order path so that the demo app can get a dynamically generated database credential from Vault. Therefore the PostgreSQL credentials are not hard-coded anywhere.

   path "database/creds/order"
   {
     capabilities = ["read"]
   }
   

   The update permission for the transit secrets engine allows the app to request data encryption and decryption using the order encryption key in Vault.

   ## ...snip...
   path "transit/decrypt/order" {
     capabilities = ["update"]
   }
   
   path "transit/encrypt/order" {
     capabilities = ["update"]
   }
   ## ...snip...
   

Examine the Spring container

1. Review the VaultDemoOrderServiceApplication class.

   @PostConstruct
       public void initIt() throws Exception {
           logger.info("Got Vault Token: " + sessionManager.getSessionToken().getToken());
           logger.info("Got DB User: " + dbUser);
       // ...
   }
   

   The VaultDemoOrderServiceApplication class logs messages during the successful execution of initIt().

2. Verify that the log indicates that the demo app obtained a database credentials from Vault successfully.

   $ docker logs spring | grep Got
   
   ...VaultDemoOrderServiceApplication : Got Vault Token: root
   ...VaultDemoOrderServiceApplication : Got DB User: v-token-order-rywqz61432yyx2x27w8r-1524067226
   

   Copy

3. Create a new shell session in the spring container.

   $ docker exec -it spring sh
   / #
   

   Copy

4. Review the bootstrap.yaml file.

   $ cat bootstrap.yaml
   spring.application.name: spring-vault-demo
   spring.cloud.vault:
     authentication: TOKEN
     token: ${VAULT_TOKEN}
     host: localhost
     port: 8200
     scheme: http
     fail-fast: true
     config.lifecycle.enabled: true
     generic:
       enabled: true
       backend: secret
     database:
       enabled: true
       role: order
       backend: database
   spring.datasource:
     url: jdbc:postgresql://localhost:5432/postgres
   

   Copy

   The client token was injected into the spring container as an environment variable (VAULT_TOKEN) by Vagrant.

5. Close the shell session in the spring container.

   $ exit
   

   Copy

Examine the PostgreSQL database

1. Connect to the postgres container.

   $ docker exec -it postgres psql -U postgres -d postgres
   psql (14.9 (Debian 14.9-1.pgdg110+1))
   Type "help" for help.
   
   postgres=#
   

   Copy

2. Review the orders table.

   $ \d orders
                                             Table "public.orders"
       Column     |            Type             | Collation | Nullable |              Default
   ---------------+-----------------------------+-----------+----------+------------------------------------
    id            | bigint                      |           | not null | nextval('orders_id_seq'::regclass)
    customer_name | character varying(60)       |           | not null |
    product_name  | character varying(20)       |           | not null |
    order_date    | timestamp without time zone |           | not null |
   Indexes:
       "orders_pkey" PRIMARY KEY, btree (id)
   

   Copy

3. List the existing database roles.

   $ \du
                                                        List of roles
                      Role name                   |                         Attributes                         | Member of
   -----------------------------------------------+------------------------------------------------------------+-----------
    postgres                                      | Superuser, Create role, Create DB, Replication, Bypass RLS | {}
    v-token-order-rywqz61432yyx2x27w8r-1524067226 | Password valid until 2018-04-18 20:56:31+00                | {}
   

   Copy

   The role name starting with v-token-order- was dynamically created by the database secrets engine.

   Note

   To learn more about the database secrets engine, read the Secrets as a Service: Dynamic Secrets tutorial.

4. Exit the psql session.

   $ \q
   

   Copy

Run the demo application

You have verified in the spring log that the demo app successfully retrieved a database credential from the Vault server during its initialization.

1. Create a file payload.json with the following contents.

   $ tee payload.json <<EOF
   {
     "customerName": "John",
     "productName": "Nomad"
   }
   EOF
   

   Copy

2. Send a new order request via the demo app's orders API (http://localhost:8080/api/orders).

   $ curl --request POST --header "Content-Type: application/json" \
          --data @payload.json http://localhost:8080/api/orders | jq
   

   Copy

   Example output:

   {
     "id": 1,
     "customerName": "John",
     "productName": "Nomad",
     "orderDate": "2018-04-18T22:07:42.916+0000"
   }
   

   The order data you sent gets encrypted by Vault. The database only sees the ciphertext.

   Note

   Alternately, you can use tool such as Postman instead of cURL to invoke the API.

   

3. Connect to the PostgreSQL container.

   $ docker exec -it postgres psql -U postgres -d postgres
   

   Copy

4. Verify that the order information stored in the database is encrypted.

   $ select * from orders;
    id |                     customer_name                     | product_name |       order_date
   ----+-------------------------------------------------------+--------------+-------------------------
     1 | vault:v1:UwL3HnyqTUac5ElS5WYAuNg3NdIMFtd6vvwukL+FaKun | Nomad        | 2018-04-18 22:07:42.916
   (1 rows)
   

   Copy

   In this demo, Vault encrypts the customer names; therefore the values in the customer_name column do not display the names in a human readable manner ("John").

5. Close the shell session in the postgres container.

   $ exit
   

   Copy

6. Retrieve the order data via the orders API.

   $ curl --header "Content-Type: application/json" \
          http://localhost:8080/api/orders | jq
   

   Copy

   Example output:

   [
     {
       "id": 1,
       "customerName": "John",
       "productName": "Nomad",
       "orderDate": "2018-04-18T22:07:42.916+0000"
     }
   ]
   

   The customer names should be readable. Remember that the order policy permits the demo app to encrypt and decrypt data using the order encryption key in Vault.

Web UI

You can also use the Vault web UI to decrypt the data.

Reload the static secrets

Test another API endpoint, api/secret, provided by the demo app. A Java object, Secret defines a get method for key and value. The SecretController.java defines an API endpoint, api/secret.

// SecretController.java
package com.hashicorp.vault.spring.demo;
// ...

@RefreshScope
@RestController
public class SecretController {

  @Value("${secret:n/a}")
  String secret;

  @RequestMapping("/api/secret")
  public Secret secret() {
    return new Secret("secret", secret);
  }
}

The order policy grants permissions on the secret/spring-vault-demo path.

path "secret/spring-vault-demo" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

The demo app retrieves the secret from secret/spring-vault-demo and has a local copy. If someone (or perhaps another app) updates the secret, it makes the secret held by the demo app obsolete.

Spring offers Spring Boot Actuator which can be used to facilitate the reloading of the static secret.

Read the secret

The initial key-value was set by Vagrant during the provisioning. (See the Vagrantfile at line 48.)

1. Invoke the demo app's secret API (api/secret).

   $ curl -s http://localhost:8080/api/secret | jq
   

   Copy

   Example output:

   {
     "key": "secret",
     "value": "hello-vault"
   }
   

   This is the secret that the demo app knows about.

Update the secrets

1. Update the secret stored in Vault using the API.

   $ curl --header "X-Vault-Token: root" \
          --request POST \
          --data '{ "secret": "my-api-key" }' \
          http://127.0.0.1:8200/v1/secret/spring-vault-demo
   

   Copy

2. Verify that the secret value was updated.

   $ curl --header "X-Vault-Token: root" \
          http://127.0.0.1:8200/v1/secret/spring-vault-demo | jq
   

   Copy

   Example output:

   {
     "request_id": "514601e4-a790-3dc6-14b0-537d6982a6c6",
     "lease_id": "",
     "renewable": false,
     "lease_duration": 2764800,
     "data": {
       "secret": "my-api-key"
     }
   }
   

Refresh the secret on the demo app

1. Run the demo app's secret API again.

   $ curl -s http://localhost:8080/api/secret | jq
   

   Copy

   Example output:

   {
     "key": "secret",
     "value": "hello-vault"
   }
   

   The current value stored in Vault is now my-api-key; however, the demo app still holds hello-vault.

   Spring provides an actuator which can be leveraged to refresh the secret value. At line 54 of the vault-guides/secrets/spring-cloud-vault/pom.xml, you see that the actuator was added to the project.

   <!-- ... -->
   <dependency>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-actuator</artifactId>
   </dependency>
   <!-- ... -->
   

2. Refresh the secret using the actuator.

   $ curl -s --request POST http://localhost:8080/actuator/refresh | jq
   [
     "secret"
   ]
   

   Copy

   Example output:

   [
     "spring.datasource.username",
     "secret",
     "spring.datasource.password"
   ]
   

3. Read back the secret from the demo app.

   $ curl -s http://localhost:8080/api/secret | jq
   {
     "key": "secret",
     "value": "my-api-key"
   }
   

   Copy

   It should display the correct value.

Clean up

1. Disconnect from the demo virtual machine.

   $ exit
   

   Copy

2. When you are done exploring the demo implementation, destroy the virtual machine.

   $ vagrant destroy
   
   demo: Are you sure you want to destroy the 'demo' VM? [y/N] y
   ==> demo: Forcing shutdown of VM...
   ==> demo: Destroying VM and associated drives...
   

   Copy

3. Remove the sample repository.

   $ rm -rf learn-vault-spring-cloud
   

   Copy

In the webinar, the demo environment was running in a public cloud, and Nomad and Consul were also installed and configured. If you wish to build a similar environment using Kubernetes, the assets in the vault-guides/secrets/spring-cloud-vault/kubernetes folder provides you with some guidance.

Help and reference

• Manage secrets, access, and encryption in the public cloud with Vault
• Spring Cloud Vault
• Transit Secrets Engine