Writing Client Applications

Refer to the “Cook” sample application to follow along with the code in this topic.

To use a Spring Boot app as a client for a Config Server instance, you must add the dependencies listed below.

Important: Ensure that the ordering of the Maven BOM dependencies listed below is preserved in your application’s build file. Dependency resolution is affected in both Maven and Gradle by the order in which dependencies are declared.

To work with Spring Cloud Services service instances, your client application must include the following BOMs:

  • spring-cloud-services-dependencies
  • spring-cloud-dependencies
  • spring-boot-dependencies, unless you use spring-boot-starter-parent (with Maven) or the Spring Boot Gradle plugin (with Gradle)

See the following sections for how to construct a build file for your use case.

General Dependencies

Construct your build file using one of the examples below, for either Maven or Gradle. Replace [BOOT], [CLOUD], and [SCS] according to your Spring Boot and Spring Cloud version. Refer to the following table:

If using… …use [BOOT] …use [CLOUD] …use [SCS]
Boot 2, Cloud Finchley 2.0.3.RELEASE Finchley.RELEASE 2.0.1.RELEASE
Boot 1.5, Cloud Edgware 1.5.13.RELEASE Edgware.SR3 1.6.1.RELEASE

For Maven

If using Maven, include in pom.xml:

    <relativePath/> <!-- lookup parent from repository -->


If not using the spring-boot-starter-parent, include in the <dependencyManagement> block of pom.xml:


        <!-- ... -->


For Gradle

If using Gradle, you will also need to use the Gradle dependency management plugin.

Include in build.gradle:

buildscript {
    repositories {
    dependencies {

apply plugin: "java"
apply plugin: "org.springframework.boot"
apply plugin: "io.spring.dependency-management"

dependencyManagement {
    imports {
        mavenBom "org.springframework.cloud:spring-cloud-dependencies:[CLOUD]"
        mavenBom "io.pivotal.spring.cloud:spring-cloud-services-dependencies:[SCS]"

repositories {
    maven {
        url "https://repo.spring.io/plugins-release"

If not using the Spring Boot Gradle plugin, include in the dependencyManagement block of build.gradle:

dependencyManagement {
    imports {
        mavenBom "org.springframework.boot:spring-boot-dependencies:[BOOT]"
Your app must also declare the Spring Cloud Services Config Server starter as a dependency.

If using Maven, include in pom.xml:


If using Gradle, include in build.gradle:

dependencies {

Important: Because of a dependency on Spring Security, the Spring Cloud® Config Client starter will by default cause all application endpoints to be protected by HTTP Basic authentication. If you wish to disable this, please see Disable HTTP Basic Authentication below.

## Use Configuration Values When the application requests a configuration from the Config Server, it will use a path containing the application name (as described in the Configuration Clients section of the Background Information topic). You can declare the application name in `bootstrap.properties`, `bootstrap.yml`, `application.properties`, or `application.yml`. In `bootstrap.yml`: “`yml spring: application: name: cook ”` This application will use a path with the application name `cook`, so the Config Server will look in its configuration source for files whose names begin with `cook`, and return configuration properties from those files. Now you can (for example) inject a configuration property value using the `@Value` annotation. The Menu class reads the value of `special` from the `cook.special` configuration property. “`java @RefreshScope @Component public class Menu { @Value(”${cook.special}“) String special; //… public String getSpecial() { return special; } //… } ”` The `Application` class is a [`@RestController`](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/bind/annotation/RestController.html). It has an injected `menu` and returns the `special` (the value of which will be supplied by the Config Server) in its `restaurant()` method, which it maps to `/restaurant`. “`java @RestController @SpringBootApplication public class Application { @Autowired private Menu menu; @RequestMapping(”/restaurant") public String restaurant() { return String.format(“Today’s special is: %s”, menu.getSpecial()); } //… “` ## Vary Configurations Based on Profiles You can provide configurations for multiple profiles by including appropriately-named `.yml` or `.properties` files in the Config Server instance’s configuration source (the Git repository). Filenames follow the format `{application}-{profile}.{extension}`, as in `cook-production.yml`. (See the [The Config Server](/spring-cloud-services/config-server/background-information.html#the-config-server) section of the [Background Information](/spring-cloud-services/config-server/background-information.html) topic.) The application will request configurations for any active profiles. To set profiles as active, you can use the `SPRING_PROFILES_ACTIVE` environment variable, set for example in `manifest.yml`. ”`yml applications: - name: cook host: cookie services: - config-server env: SPRING_PROFILES_ACTIVE: production “` The sample configuration source cook-config contains the files `cook.properties` and `cook-production.properties`. With the active profile set to `production` as in `manifest.yml` above, the application will make a request of the Config Server using the path `/cook/production`, and the Config Server will return properties from both `cook-production.properties` (the profile-specific configuration) and `cook.properties` (the default configuration); for example: ”` { “name”:“cook”, “profiles”:[ “production” ], “label”:“master”, “propertySources”:[ { “name”:“https://github.com/spring-cloud-services-samples/cook-config/cook-production.properties”, “source”: { “cook.special”:“Cake a la mode” } }, { “name”:“https://github.com/spring-cloud-services-samples/cook-config/cook.properties”, “source”: { “cook.special”:“Pickled Cactus” } } ] } “` As noted in the [Configuration Clients](/spring-cloud-services/config-server/background-information.html#configuration-clients) section of the [Background Information](/spring-cloud-services/config-server/background-information.html) topic, the application must decide what to do when the server returns multiple values for a configuration property, but a Spring application will take the first value for each property. In the example response above, the configuration for the specified profile (`production`) is first in the list, so the Boot sample application will use values from that configuration. ## View Client Application Configuration Spring Boot Actuator adds an `env` endpoint to the application and maps it to `/env`. This endpoint displays the application’s profiles and property sources from the Spring ”`ConfigurableEnvironment`“. (See ["Endpoints”](http://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-endpoints.html) in the “Spring Boot Actuator” section of the Spring Boot Reference Guide.) In the case of an application which is bound to a Config Server service instance, `env` will display properties provided by the instance. To use Actuator, you must add the `spring-boot-starter-actuator` dependency to your project. If using Maven, add to `pom.xml`: “`xml org.springframework.boot spring-boot-starter-actuator ”` If using Gradle, add to `build.gradle`: “`groovy compile("org.springframework.boot:spring-boot-starter-actuator”) “` You can now visit `/env` to see the application environment’s properties (the following shows an excerpt of an example response):
$ curl http://cookie.apps.wise.com/env
    "cook.special":"Pickled Cactus"

Refresh Client Application Configuration

Spring Boot Actuator also adds a refresh endpoint to the application. This endpoint is mapped to /refresh, and a POST request to the refresh endpoint refreshes any beans which are annotated with @RefreshScope. You can thus use @RefreshScope to refresh properties which were initialized with values provided by the Config Server.

The Menu.java class is marked as a @Component and also annotated with @RefreshScope.

import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.stereotype.Component;

public class Menu {

  String special;

This means that after you change values in the configuration source repository, you can update the special on the Application class’s menu with a refresh event triggered on the application:

$ curl http://cookie.apps.wise.com/restaurant
Today's special is: Pickled Cactus

$ git commit -am "new special"
[master 3c9ff23] new special
 1 file changed, 1 insertion(+), 1 deletion(-)

$ git push

$ curl -X POST http://cookie.apps.wise.com/refresh

$ curl http://cookie.apps.wise.com/restaurant
Today's special is: Birdfeather Tea

Use Client-Side Decryption

On the Config Server, the decryption features are disabled, so encrypted property values from a configuration source are delivered to client applications unmodified. You can use the decryption features of Spring Cloud Config Client to perform client-side decryption of encrypted values.

To use the decryption features in a client application, you must use a Java buildpack which contains the Java Cryptography Extension (JCE) Unlimited Strength policy files. These files are contained in the Cloud Foundry Java buildpack from version 3.7.1.

If you cannot use version 3.7.1 or later, you can add the JCE Unlimited Strength policy files to an earlier version of the Cloud Foundry Java buildpack. Fork the buildpack on GitHub, then download the policy files from Oracle and place them in the buildpack’s resources/open_jdk_jre/lib/security directory. Follow the instructions in the Managing Custom Buildpacks topic to add this buildpack to Pivotal Cloud Foundry. Be sure that it has the lowest position of all enabled Java buildpacks.

You must also include Spring Security RSA as a dependency.

If using Maven, include in pom.xml:


If using Gradle, include in build.gradle:


Encrypted values must be prefixed with the string {cipher}. If using YAML, enclose the entire value in single quotes, as in '{cipher}vALuE'; if using a properties file, do not use quotes. The configuration source for the Cook application has a secretMenu property in its cook-encryption.properties:


Put the key on the client application classpath. You can either add the keystore to the buildpack’s resources/open_jdk_jre/lib/security directory (as described above for the JCE policy files) or include it with the source for the application. In the Cook application, the key is placed in src/main/resources.

└── src
    └── main
        └── resources
            ├── application.yml
            ├── bootstrap.yml
            └── server.jks

Important: Cook is an example application, and the key is packaged with the application source for example purposes. If at all possible, use the buildpack for keystore distribution.

Specify the key location and credentials in bootstrap.properties or bootstrap.yml using the encrypt.keyStore properties:

    location: classpath:/server.jks
    password: letmein
    alias: mytestkey
    secret: changeme

The Menu class has a String property secretMenu.

  String secretMenu;


  public String getSecretMenu() {
    return secretMenu;

A default value for secretMenu is in bootstrap.yml:

secretMenu: Animal Crackers

In the Application class, the method secretMenu() is mapped to /restaurant/secret-menu. It returns the value of the secretMenu property.

    public String secretMenu() {
      return menu.getSecretMenu();

After making the key available to the application and installing the JCE policy files in the Java buildpack, you can cause the Config Server to serve properties from the cook-encryption.properties file by activating the encryption profile on the application, e.g. by running cf set-env to set the SPRING_PROFILES_ACTIVE environment variable:

$ cf set-env cook SPRING_PROFILES_ACTIVE dev,encryption
Setting env variable 'SPRING_PROFILES_ACTIVE' to 'dev,encryption' for app cook in org myorg / space development as user...
TIP: Use 'cf restage' to ensure your env variable changes take effect

$ cf restage cook

The application will decrypt the encrypted property after receiving it from the Config Server. You can view the property value by visiting /restaurant/secret-menu on the application.

Use Plain Text Configuration Files

You can use the Config Server to serve files from plain text files in a Git repository. The Spring Cloud Services Config Client library adds a PlainTextConfigClient that can read in a text file and make its contents available to a client application.

The PlainTextConfigClient provides a getConfigFile() method which accepts an application profile, a label, and a filename. You can use this method to retrieve a Spring Resource. The Cook application takes the InputStream from the retrieved Resource and uses the copyToString() method of Spring’s StreamUtils to return a String.

PlainTextConfigClient configClient;


String dessertMenu() throws IOException {
  InputStream input = configClient.getConfigFile("cloud", "master", "dessert.json").getInputStream();
  return StreamUtils.copyToString(input, Charset.defaultCharset());

Use a HashiCorp Vault Server

You can configure the Config Server to use a HashiCorp Vault server as a configuration source, as described in the Configuring with Vault topic. To consume configuration from the Vault server via the service instance, your client application must be given a Vault token. You can give the token to an application by setting the SPRING_CLOUD_CONFIG_TOKEN environment variable on the application. The Spring Cloud Services Connectors for Config Server will automatically renew the application’s token for as long as the application is running.

Important: If the application is entirely stopped (i.e., no instances continue to run) and its Vault token expires, you will need to create a new token for the application and re-set the SPRING_CLOUD_CONFIG_TOKEN environment variable.

To generate a token for use in the application, you can run the vault token-create command, providing a Time To Live (TTL) that is long enough for the application to be restaged after you have set the environment variable. The following command creates a token with a TTL of one hour:

$ vault token-create -ttl="1h"

After generating the token, set the environment variable on your client application and then restage the application for the environment variable setting to take effect:

$ cf set-env cook SPRING_CLOUD_CONFIG_TOKEN c3432ef5-6a78-8673-ea23-5528c26849e4
Setting env variable 'SPRING_CLOUD_CONFIG_TOKEN' to 'c3432ef5-6a78-8673-ea23-5528c26849e4' for app cook in org myorg / space development as user...
TIP: Use 'cf restage cook' to ensure your env variable changes take effect

$ cf restage cook

The Spring Cloud Services Connectors for Config Server renew the application token for as long as the application continues to run. For more information about the token renewal performed by the connectors, see the HashiCorp Vault Token Renewal section of the Spring Cloud Connectors topic.

Renew Vault Token Manually

After creating a Vault token for an application, you can renew the token manually using the Config Server service instance bound to the application.

Note: The following procedure uses the jq command-line JSON processing tool.

Run cf env, giving the name of an application that is bound to the service instance:

$ cf services
Getting services in org myorg / space development as admin...

name             service           plan        bound apps   last operation
config-server    p-config-server   standard    vault-app    create succeeded

$ cf env vault-app
Getting env variables for app vault-app in org myorg / space development as admin...

  "p-config-server": [
    "credentials": {
     "access_token_uri": "https://p-spring-cloud-services.uaa.cf.wise.com/oauth/token",
     "client_id": "p-config-server-876cd13b-1564-4a9a-9d44-c7c8a6257b73",
     "client_secret": "rU7dMUw6bQjR",
     "uri": "https://config-86b38ce0-eed8-4c01-adb4-1a651a6178e2.apps.wise.com"

Then create a Bash script that accesses the Vault token renewal endpoint on the service instance backing application:

-d grant_type=client_credentials | jq -r .access_token); \
curl -H "Authorization: bearer $TOKEN" -H "X-VAULT-Token: [VAULT_TOKEN]" \
-H "Content-Type: application/json" -X POST \
[URI]/vault/v1/auth/token/renew-self -d '{"increment": [INTERVAL]}'

This script retrieves an access token using an OAuth 2.0 credential exchange with Cloud Foundry’s UAA service. After being given an authorization token, it uses this token to make a call to the service instance’s API endpoints.

Replace the following placeholders in the script with values from the cf env command above:

  • [ACCESS_TOKEN_URI] with the value of p-config-server.credentials.access_token_uri
  • [CLIENT_ID] with the value of p-config-server.credentials.client_id
  • [CLIENT_SECRET] with the value of p-config-server.credentials.client_secret
  • [URI] with the value of p-config-server.credentials.uri

Replace the following placeholders with the relevant values:

  • [VAULT_TOKEN] with the Vault token string
  • [INTERVAL] with the number of seconds to set as the Vault token’s Time To Live (TTL)

After renewing the token, you can view its TTL by looking it up using the Vault command line. Run vault token-lookup [TOKEN], replacing [TOKEN] with the Vault token string:

$ vault token-lookup 72ec7ca0-de41-b2dc-8fe4-d74c4c9a4e75
Key                  Value
---                  -----
accessor             436db91b-6bfb-9eec-7bfb-913260488ce8
creation_time        1493360487
creation_ttl         3600
display_name         token
explicit_max_ttl     0
id                   72ec7ca0-de41-b2dc-8fe4-d74c4c9a4e75
last_renewal_time    1493360718
num_uses             0
orphan               false
path                 auth/token/create
policies             [root]
renewable            true
ttl                  997

Disable HTTP Basic Authentication

The Spring Cloud Config Client starter has a dependency on Spring Security. Unless your application has other security configuration, this will cause all application endpoints to be protected by HTTP Basic authentication.

If you do not yet want to address application security, you can disable Basic authentication. See below for information about doing this in your app’s version of Spring Boot.

Using Spring Boot 1.5

If you are using Spring Boot 1.5, you can disable HTTP Basic authentication by setting the security.basic.enabled property to false. In application.yml or bootstrap.yml:

    enabled: false

You might make this setting specific to a profile (such as the dev profile if you want Basic authentication disabled only for development):

  profiles: dev

    enabled: false

For more information, see "Security” in the Spring Boot 1.5 Reference Guide.

Note: Because of the Spring Security dependency, HTTPS Basic authentication will also be enabled for Spring Boot Actuator endpoints. If you wish to disable that as well, you must also set the management.security.enabled property to false. See “Customizing the management server port” in the Spring Boot 1.5 Reference Guide.

Using Spring Boot 2.0

If you are using Spring Boot 2.0, you can disable HTTP Basic authentication using a class that extends Spring Security’s WebSecurityConfigurerAdapter and is annotated with the Spring @Configuration annotation. To do so, you must include the Spring Boot Security starter in your build file.

Using Maven:


Using Gradle:


The following class disables all default security for the development profile only, using the @Profile annotation:

import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;

public class SecurityConfiguration extends WebSecurityConfigurerAdapter {

    protected void configure(HttpSecurity http) throws Exception {


For more information, see “Security” in the Spring Boot 2.0 Reference Guide.

Create a pull request or raise an issue on the source for this page in GitHub