Secret Management

Hashicorp Vault

Hashicorp Vault allows you to manage your application secrets in an external and central location. If enabled and configured, the connector fetches dynamically secrets from Hashicorp Vault and applies them to the connector.

Installation

Follow the installation guide at Install Vault. The connector authenticates towards Hashicorp Vault using an authentication token to retrieve and resolve secrets store in Vault kv store. The connector requires only read access to the kv store, hence it is recommended to define a read-only policy for the path where secrets are stored and assign the policy to your vault token.

KV Secret Engine

Manage Secrets

Retrieve the property key for the target secret from Connector Configuration. In order to e.g. manage the Database Credentials in Hashicorp Vault, put or patch your kv store, execute one of the following CLI commands:

Set or update secrets by replacing and overwritting all existing secrets in the kv store.
$ vault kv put secret/my-connector spring.datasource.username=your-username spring.datasource.password=your-password
Set or update secrets without ovewritting existing secrets.
$ vault kv path secret/my-connector spring.datasource.username=your-username spring.datasource.password=your-password

Manage Policy

The policy for the KV Secret Engine requires read and list access for the directory secret/data. Use the Vault CLI and create the policy which defines read-only access to the connector path:

$ vault policy write connector-read-only ./connector.hcl

Define the read access according to the path of your secrets:

connector.hcl for KV Secret Engine
path "secret/data/<my-connector>*" {
  capabilities = ["read", "list"]
}
The value for <my-connector> should be adjusted according to the properties spring.application.name and spring.cloud.config.server.composite[*].defaultKey.
Make sure include the wildcard *

Token Authentication

Create a read-only token for the connector by referencing the policy created in previous step:

$ vault token create -policy=connector-read-only

In order to use Token Authentication set the following properties inside the bootstrap.properties:

bootstrap.properties
spring.cloud.config.server.vault.authentication=TOKEN
spring.cloud.config.server.vault.token=${TOKEN}
TIP: The token can be placed in the bootstrap.properties or can be set via environment variable, in this case TOKEN to be referenced in the bootstrap properties with the pattern ${NAME_OF_ENV_VARIABLE}.

AppRole Authentication

Instead of providing the token directly, the connector can be also configured to use AppRole authentication which will dynamically fetches the token considering the role and policies attached to the role. In order to enable and configure the AppRole for your Vault instance, follow the steps below:

If not done, enable the AppRole feature via CLI:

Eanble AppRole
$ vault auth enable approle

Create a named role with the previously created policy attached to it:

Create Role
$ vault write auth/approle/role/my-role policies=connector-read-only

Retrieve the Role and Secret ID for the newly created role. The IDs are mandatory for the connector

Retrieve Role ID
$ vault read auth/approle/role/my-role/role-id
Retrieve Secret ID
$ vault write -f auth/approle/role/my-role/secret-id

Configure the retrieved IDs in the bootstrap.properties to enable AppRole authentication in the connector.

bootstrap.properties
spring.cloud.config.server.vault.authentication=APPROLE
spring.cloud.config.server.vault.app-role.role-id=<ROLE-ID>
spring.cloud.config.server.vault.app-role.secret-id=<SECRET-ID>
The Secret ID can be placed in the bootstrap.properties or can be set via environment variable to be referenced in the bootstrap properties with the pattern ${NAME_OF_ENV_VARIABLE}.

bootstrap.properties for KV Secret Engine

Once you adjusted the connection settings according to your Vault instance, you can have to specify the Vault engine to be integrated into the connector. For the KV engine, introduce the following properties into your bootstrap.properties.

bootstrap.properties
spring.application.name=my-connector
spring.profiles.active=composite
spring.cloud.config.server.bootstrap=true
spring.cloud.config.server.vault.authentication=TOKEN
spring.cloud.config.server.vault.token={cipher}your-encrypted-token
spring.cloud.config.server.vault.scheme=http
spring.cloud.config.server.vault.host=127.0.0.1
spring.cloud.config.server.vault.port=8200

spring.cloud.config.server.composite[0].type=vault
spring.cloud.config.server.composite[0].kv-version=2
spring.cloud.config.server.composite[0].defaultKey=my-connector

  • spring.application.name, spring.cloud.config.server.composite[0].defaultKey: This property identifies the path to the secrets and properties inside Hashicorp Vault. If you uploaded your secret under secret/my-connector, the value has to be set to my-connector.

KV Secret Engine with App Role Authentication
bootstrap.properties
spring.application.name=my-connector
spring.profiles.active=composite
spring.cloud.config.server.bootstrap=true
spring.cloud.config.server.vault.authentication=APPROLE
spring.cloud.config.server.vault.app-role.role-id=<ROLE-ID>
spring.cloud.config.server.vault.app-role.secret-id=<SECRET-ID>
spring.cloud.config.server.vault.scheme=http
spring.cloud.config.server.vault.host=127.0.0.1
spring.cloud.config.server.vault.port=8200

spring.cloud.config.server.composite[0].type=vault
spring.cloud.config.server.composite[0].kv-version=2
spring.cloud.config.server.composite[0].defaultKey=my-connector

Active Directory Secret Engine

Enable AD Secret Engine

Enable Active Directory Secret Engine
$ vault secrets enable ad
Configure LDAP Server
$ vault write ad/config binddn=$USERNAME bindpass=$PASSWORD url=ldaps://138.91.247.105 userdn='dc=example,dc=com'

Link Active Directory Account

Link a role to the respective AD account. The connector uses the linked role to fetch the password from the AD Secret Engine.

$ vault write ad/roles/my-application \
    service_account_name="my-application@example.com"

Manage Policy

For the AD Secret Engine, the policy requires read access to the mount path of the engine which points to ad by default. Create the respective policy using the CLI:

$ vault policy write connector-read-only ./connector.hcl

Define the read and update access according to the path of your mount path:

connector.hcl for KV Secret Engine
path "ad/*" {
  capabilities = ["read", "list", "update"]
}

Token Authentication

Create a read-only token for the connector by referencing the policy created in previous step:

$ vault token create -policy=connector-read-only

In order to use Token Authentication set the following properties inside the bootstrap.properties:

bootstrap.properties
spring.cloud.config.server.vault.authentication=TOKEN
spring.cloud.config.server.vault.token=${TOKEN}
The token can be placed in the bootstrap.properties or can be set via environment variable, in this case TOKEN to be referenced in the bootstrap properties with the pattern ${NAME_OF_ENV_VARIABLE}.

AppRole Authentication

Instead of providing the token directly, the connector can be also configured to use AppRole authentication which will dynamically fetches the token considering the role and policies attached to the role. In order to enable and configure the AppRole for your Vault instance, follow the steps below:

If not done, enable the AppRole feature via CLI:

Eanble AppRole
$ vault auth enable approle

Create a named role with the previously created policy attached to it:

Create Role
$ vault write auth/approle/role/my-role policies=connector-read-only

Retrieve the Role and Secret ID for the newly created role. The IDs are mandatory for the connector

Retrieve Role ID
$ vault read auth/approle/role/my-role/role-id
Retrieve Secret ID
$ vault write -f auth/approle/role/my-role/secret-id

Configure the retrieved IDs in the bootstrap.properties to enable AppRole authentication in the connector.

bootstrap.properties
spring.cloud.config.server.vault.authentication=APPROLE
spring.cloud.config.server.vault.app-role.role-id=<ROLE-ID>
spring.cloud.config.server.vault.app-role.secret-id=<SECRET-ID>
The Secret ID can be placed in the bootstrap.properties or can be set via environment variable to be referenced in the bootstrap properties with the pattern ${NAME_OF_ENV_VARIABLE}.

bootstrap.properties for AD Secret Engine

bootstrap.properties
spring.application.name=my-connector
spring.profiles.active=composite
spring.cloud.config.server.bootstrap=true
spring.cloud.config.server.vault.authentication=TOKEN
spring.cloud.config.server.vault.token={cipher}your-encrypted-token
spring.cloud.config.server.vault.scheme=http
spring.cloud.config.server.vault.host=127.0.0.1
spring.cloud.config.server.vault.port=8200

spring.cloud.config.server.composite[0].type=ad
spring.cloud.config.server.composite[0].mount=ad
spring.cloud.config.server.composite[0].secrets[0].role=<ROLE-NAME>
spring.cloud.config.server.composite[0].secrets[0].key=<PROPERTY-KEY>
spring.cloud.config.server.composite[0].secrets[1].role=<ROLE-NAME_2>
spring.cloud.config.server.composite[0].secrets[1].key=<PROPERTY-KEY_2>

  • spring.cloud.config.server.composite[0].mount=ad: Mount path of the AD Secret Engine extension. Default points to ad.

  • spring.cloud.config.server.composite[0].secrets[*].role: Name of the role associated to the credential managed by the AD engine in step Link Active Directory Account.

  • spring.cloud.config.server.composite[0].secrets[*].key: Property Key of the property which should be loaded from the AD Secret Engine. You can retrieve the properties key defined in the connector from Connector Configuration.

AD Secret Engine with App Role Authentication
bootstrap.properties
spring.application.name=my-connector
spring.profiles.active=composite
spring.cloud.config.server.bootstrap=true
spring.cloud.config.server.vault.authentication=APPROLE
spring.cloud.config.server.vault.app-role.role-id=<ROLE-ID>
spring.cloud.config.server.vault.app-role.secret-id=<SECRET-ID>
spring.cloud.config.server.vault.scheme=http
spring.cloud.config.server.vault.host=127.0.0.1
spring.cloud.config.server.vault.port=8200

spring.cloud.config.server.composite[0].type=ad
spring.cloud.config.server.composite[0].mount=ad
spring.cloud.config.server.composite[0].secrets[0].role=<ROLE-ID>
spring.cloud.config.server.composite[0].secrets[0].key=<PROPERTY-KEY>
KV and AD Secret Engine Combined
bootstrap.properties
spring.application.name=my-connector
spring.profiles.active=composite
spring.cloud.config.server.bootstrap=true
spring.cloud.config.server.vault.authentication=TOKEN
spring.cloud.config.server.vault.token={cipher}your-encrypted-token
spring.cloud.config.server.vault.scheme=http
spring.cloud.config.server.vault.host=127.0.0.1
spring.cloud.config.server.vault.port=8200

spring.cloud.config.server.composite[0].type=vault
spring.cloud.config.server.composite[0].kv-version=2
spring.cloud.config.server.composite[0].defaultKey=my-connector

spring.cloud.config.server.composite[1].type=ad
spring.cloud.config.server.composite[1].mount=ad
spring.cloud.config.server.composite[1].secrets[0].role=<ROLE-ID>
spring.cloud.config.server.composite[1].secrets[0].key=<PROPERTY-KEY>

Advanced Configuration

Enable SSL

If Hashicorp Vault is deployed on a HTTPS port, you can enable client SSL by introducing following properties into your bootstrap.properties.

SSL properties bootstrap.properties
spring.cloud.config.server.vault.scheme=https
# Adjust the port if needed
spring.cloud.config.server.vault.port=8400

# Disable SSL validation if needed
spring.cloud.config.server.vault.skip-ssl-validation=true

  • spring.cloud.config.server.vault.scheme: Adjust this value to https if your vault instance is deployed on HTTPS port.

  • spring.cloud.config.server.vault.skip-ssl-validation: You can disable SSL validation (not recommended) by setting this value to true.

Proxy Support

In order to connect to your Hashicorp Vault instance through an HTTP proxy, introduce the following properties into your bootstrap.properties.

Proxy properties bootstrap.properties
spring.cloud.config.server.vault.proxy.http.host=<your-proxy-host>
spring.cloud.config.server.vault.proxy.http.port=<your-proxy-port>