Service Registry Configuration

You can use a DiscoveryClient (such as from Spring Cloud Consul) to locate a Vault server by setting spring.cloud.vault.discovery.enabled=true (default false). The net result of that is that your apps need a application.yml (or an environment variable) with the appropriate discovery configuration. The benefit is that the Vault can change its co-ordinates, as long as the discovery service is a fixed point. The default service id is vault but you can change that on the client with spring.cloud.vault.discovery.serviceId.

The discovery client implementations all support some kind of metadata map (e.g. for Eureka we have eureka.instance.metadataMap). Some additional properties of the service may need to be configured in its service registration metadata so that clients can connect correctly. Service registries that do not provide details about transport layer security need to provide a scheme metadata entry to be set either to https or http. If no scheme is configured and the service is not exposed as secure service, then configuration defaults to spring.cloud.vault.scheme which is https when it’s not set.

spring.cloud.vault.discovery:
    enabled: true
    service-id: my-vault-service

Vault Client Fail Fast

In some cases, it may be desirable to fail startup of a service if it cannot connect to the Vault Server. If this is the desired behavior, set the bootstrap configuration property spring.cloud.vault.fail-fast=true and the client will halt with an Exception.

spring.cloud.vault:
    fail-fast: true

Vault Enterprise Namespace Support

Vault Enterprise allows using namespaces to isolate multiple Vaults on a single Vault server. Configuring a namespace by setting spring.cloud.vault.namespace=… enables the namespace header X-Vault-Namespace on every outgoing HTTP request when using the Vault RestTemplate or WebClient.

Please note that this feature is not supported by Vault Community edition and has no effect on Vault operations.

spring.cloud.vault:
    namespace: my-namespace

See also: Vault Enterprise: Namespaces

Vault Client SSL configuration

SSL can be configured declaratively by setting various properties. You can set either javax.net.ssl.trustStore to configure JVM-wide SSL settings or spring.cloud.vault.ssl.trust-store to set SSL settings only for Spring Cloud Vault Config.

spring.cloud.vault:
    ssl:
        trust-store: classpath:keystore.jks
        trust-store-password: changeit
        trust-store-type: JKS
        enabled-protocols: TLSv1.2,TLSv1.3
        enabled-cipher-suites: TLS_AES_128_GCM_SHA256

  • trust-store sets the resource for the trust-store. SSL-secured Vault communication will validate the Vault SSL certificate with the specified trust-store.

  • trust-store-password sets the trust-store password

  • trust-store-type sets the trust-store type. Supported values are all supported KeyStore types including PEM.

  • enabled-protocols sets the list of enabled SSL/TLS protocols (since 3.0.2).

  • enabled-cipher-suites sets the list of enabled SSL/TLS cipher suites (since 3.0.2).

Please note that configuring spring.cloud.vault.ssl.* can be only applied when either Apache Http Components or the OkHttp client is on your class-path.

Lease lifecycle management (renewal and revocation)

With every secret, Vault creates a lease: metadata containing information such as a time duration, renewability, and more.

Vault promises that the data will be valid for the given duration, or Time To Live (TTL). Once the lease is expired, Vault can revoke the data, and the consumer of the secret can no longer be certain that it is valid.

Spring Cloud Vault maintains a lease lifecycle beyond the creation of login tokens and secrets. That said, login tokens and secrets associated with a lease are scheduled for renewal just before the lease expires until terminal expiry. Application shutdown revokes obtained login tokens and renewable leases.

Secret service and database backends (such as MongoDB or MySQL) usually generate a renewable lease so generated credentials will be disabled on application shutdown.

Static tokens are not renewed or revoked.

Lease renewal and revocation is enabled by default and can be disabled by setting spring.cloud.vault.config.lifecycle.enabled to false. This is not recommended as leases can expire and Spring Cloud Vault cannot longer access Vault or services using generated credentials and valid credentials remain active after application shutdown.

spring.cloud.vault:
    config.lifecycle:
    	enabled: true
    	min-renewal: 10s
    	expiry-threshold: 1m
    	lease-endpoints: Legacy

  • enabled controls whether leases associated with secrets are considered to be renewed and expired secrets are rotated. Enabled by default.

  • min-renewal sets the duration that is at least required before renewing a lease. This setting prevents renewals from happening too often.

  • expiry-threshold sets the expiry threshold. A lease is renewed the configured period of time before it expires.

  • lease-endpoints sets the endpoints for renew and revoke. Legacy for vault versions before 0.8 and SysLeases for later.

  • lease-strategy sets the LeaseStrategy (DropOnError, RetainOnError, RetainOnIoError) to control error handling on lease renewal.

See also: Vault Documentation: Lease, Renew, and Revoke

Session token lifecycle management (renewal, re-login and revocation)

A Vault session token (also referred to as LoginToken) is quite similar to a lease as it has a TTL, max TTL, and may expire. Once a login token expires, it cannot be used anymore to interact with Vault. Therefore, Spring Vault ships with a SessionManager API for imperative and reactive use.

Spring Cloud Vault maintains the session token lifecycle by default. Session tokens are obtained lazily so the actual login is deferred until the first session-bound use of Vault. Once Spring Cloud Vault obtains a session token, it retains it until expiry. The next time a session-bound activity is used, Spring Cloud Vault re-logins into Vault and obtains a new session token. On application shut down, Spring Cloud Vault revokes the token if it was still active to terminate the session.

Session lifecycle is enabled by default and can be disabled by setting spring.cloud.vault.session.lifecycle.enabled to false. Disabling is not recommended as session tokens can expire and Spring Cloud Vault cannot longer access Vault.

spring.cloud.vault:
    session.lifecycle:
        enabled: true
        refresh-before-expiry: 10s
        expiry-threshold: 20s

  • enabled controls whether session lifecycle management is enabled to renew session tokens. Enabled by default.

  • refresh-before-expiry controls the point in time when the session token gets renewed. The refresh time is calculated by subtracting refresh-before-expiry from the token expiry time. Defaults to 5 seconds.

  • expiry-threshold sets the expiry threshold. The threshold represents a minimum TTL duration to consider a session token as valid. Tokens with a shorter TTL are considered expired and are not used anymore. Should be greater than refresh-before-expiry to prevent token expiry. Defaults to 7 seconds.

See also: Vault Documentation: Token Renewal