spring-cloud-azure/azure-spring-cloud-appconfiguration.md

---
title: Azure Spring Cloud App Configuration
description: An in-depth guide on the Azure Spring Cloud App Configuration Library
services: azure-app-configuration
documentationcenter: ''
author: mrm9084
editor: ''
ms.service: azure-app-configuration
ms.topic: guide
ms.date: 09/16/2021
ms.custom: devx-track-java
ms.author: mametcal

# Customer intent: As a Java Spring developer, know how to setup, authenticate, and select keys using the library.
---
# Azure Spring Cloud App Configuration Client Library

The Azure Spring Cloud App Configuration Client Library loads configurations and feature flags from the Azure App Configuration service. The client library generates `PropertySource` abstractions, to match those already being generated by the Spring environment such as; Environment Variables, Command-line configurations, local configuration files, and so on.

## Setting up your App Configuration Store

To create your Azure App Configuration store, you can use:

```azurecli
az appconfig create --resource-group <your-resource-group> --name <name-of-your-new-store> --sku Standard
```

This command will create you a new empty configuration store. You can upload you configurations using the import command:

```azurecli
az appconfig kv import -n <name-of-your-new-store> -s file --path <location-of-your-properties-file> --format properties --prefix /application/
```

It will have you confirm your configurations before loading them. You can upload yaml files by changing the format to yaml. The prefix field is important as it is the default prefix loaded by the client library.

## Client Usage

To use the feature in an application, you can build it as a Spring Boot application. The most convenient way to add the dependency is with our Spring Boot starter `com.azure.spring:azure-spring-cloud-starter-appconfiguration-config`. The following example `pom.xml` file uses Azure App Configuration:

```xml
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>{spring-boot-version}</version>
    <relativePath />
</parent>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>{spring-cloud-version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.azure.spring</groupId>
        <artifactId>azure-spring-cloud-starter-appconfiguration-config</artifactId>
        <version>{azure-appconfiguration-version}</version>
    </dependency>
</dependencies>
<build>
    <plugins>
           <plugin>
               <groupId>org.springframework.boot</groupId>
               <artifactId>spring-boot-maven-plugin</artifactId>
           </plugin>
    </plugins>
</build>
```

A basic Spring Boot application using App Configuration:

```java
@SpringBootApplication
@RestController
public class Application {

    @RequestMapping("/")
    public String home() {
        return "Hello World!";
    }

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}
```

with `bootstrap.properties` containing:

```properties
spring.cloud.azure.appconfiguration.stores[0].connection-string=${CONFIG_STORE_CONNECTION_STRING}
```

where `CONFIG_STORE_CONNECTION_STRING` is an Environment Variable with the connection string to your Azure App Configuration Store. You can access your connection string by running:

```azurecli
az appconfig credential list --name <name-of-your-store>
```

By default, if no configurations are set, then the configurations starting with `/application/` are loaded with a default label of `(No Label)` unless a Spring Profile is set in which case the default label is your Spring Profile. Because the store is empty no configurations are loaded, but the Azure App Configuration Property Source is still generated.

A property source named `/application/https://<name-of-your-store>.azconfig.io/` is created containing the properties of that store.The label used in the request is appended to the end of the name, if no label is set the character `\0` is there, as an empty space.

## Loading Configuration

The library supports the loading of one or multiple App Configuration stores. This allows for complex configuration scenarios, such as loading of configurations from multiple stores at once or having fallbacks for added resilience. In the situation where a key is duplicated across multiple stores, loading all stores will result in the highest priority, last one wins, stores configuration being loaded. Example:

```properties
spring.cloud.azure.appconfiguration.stores[0].connection-string=[first-store-connection-string]
spring.cloud.azure.appconfiguration.stores[1].connection-string=[second-store-connection-string]
```

In the example, if both the first and second stores have the same configuration, the configuration in the second store has the highest priority, last one wins.

### Selecting Configurations

Configurations are loaded by their key and label. By default, the configurations that start with the key `/application/` are loaded. The default label is `${spring.profiles.active}`. If `${spring.profiles.active}` is not set then configuration with the null label seen as `(No Label)` in the portal are loaded.

The configurations that are loaded can be configured by selecting different key and label filters.

```properties
spring.cloud.azure.appconfiguration.stores[0].selects[0].key-filter=[my-key]
spring.cloud.azure.appconfiguration.stores[0].selects[0].label-filter=[my-label]
```

`key-filter` supports the following filters:

| Key Filter | Effect |
| -- | -- |
|`*`|Matches **any** key|
|`abc`|Matches a key named  **abc**|
|`abc*`|Matches key names that start with **abc**|
|`abc,xyz`|Matches key names **abc** or **xyz** (limited to 5 CSV)|

`label-filter` supports the following filters:

| Label | Description |
|---|---|
| `*` | Matches **any** label, which includes `\0` |
| `\0` | Matches `null` labels, seen as `(No Label)` in the portal |
| `1.0.0` | Matches label **1.0.0** exactly |
| `1.0.*` | Matches labels that start with **1.0.** |
| `,1.0.0` | Matches labels `null` or **1.0.0**, limited to five CSVs |

If you are using yaml with label filters and need to start with `null`, then the label filter needs to be surrounded by single quotes.

```yml
spring:
  cloud:
    azure:
      appconfiguration:
        stores:
         -
           selects:
             -
              label-filter: ',1.0.0'
```

> [!NOTE]
> You are unable to combine `*` with `,` in filters. In that case you need to use an additional select.

### Spring Profiles

By default, `spring.profiles.active` is set as the default `label-filter` for all selected configurations. This functionality can be overridden by the `label-filter`. The Spring Profiles can be used in the `label-filter` by using `${spring.profiles.active}` in the `label-filter`.

```properties
spring.cloud.azure.appconfiguration.stores[0].selects[0].label-filter=,${spring.profiles.active}
spring.cloud.azure.appconfiguration.stores[0].selects[1].label-filter=${spring.profiles.active}_local
```

In the first `label-filter`, all configurations with `null` label are loaded, then all configurations matching the Spring Profiles. Spring Profiles have priority over the `null` configurations, because they are at the end.

In the second `label-filter`, the string `_local` is appended to the end of the Spring Profiles, though only to the last Spring Profile.

### Disabled Stores

Using the configuration `spring.cloud.azure.appconfiguration.enabled` you can disable loading all configuration stores. With the `spring.cloud.azure.appconfiguration.stores[0].enabled` configuration, you can disable an individual store.

In addition to disabling all stores, stores can be configured to be disabled if they fail to load using the `spring.cloud.azure.appconfiguration.stores[0].fail-fast`. When `fail-fast` is enabled, set to `true`, a `RuntimeException` that would result in the application not starting up will instead have the store disabled with no configurations from it loaded. If a configuration store is disabled on startup it will not be checked for changes with refresh, or attempted to be loaded from if configurations are updated.

If, an error resulting in a `RuntimeException` happens during a refresh check or a reload of configuration the refresh attempt is ended and will be retried after the `refresh-interval` has passed.

## Authentication

The client library supports all forms of Identity supported by the [Azure Identity Library](https://github.com/Azure/azure-sdk-for-java/tree/azure-identity_1.3.6/sdk/identity/azure-identity). Authentication can be done through configuration for Connection Strings and Managed Identity. All other forms of Identity can be done by using the `TokenCredentialProvider`.

### Connection String

Authentication through connection string is the simplest form to setup. You can access a stores connection strings using:

```azurecli
az appconfig credential list --name <name-of-your-store>
```

The connection string can be then set to the property `spring.cloud.azure.appconfiguration.stores[0].connection-string`. It is highly recommended that the connection string in the local configuration file should be a placeholder value, which should map to an Environment Variable to avoid having it added to source control.

### User Assigned Identity

If you already don't have one, you can create a new Managed Identity using:

```azurecli
az identity create -g myResourceGroup -n myUserAssignedIdentity
```

Connecting to Azure app configuration with any authentication method other connection string requires three steps to setup.

1. Adding the Identity to the resource connecting to your App Configuration store
1. Adding the required information to your client application.
1. Authorizing the Identity to use App Configuration.

For user assigned, the identity needs to be added to the azure resource. How the user assigned identity is added varies between resources so you will need to check the specific docs of that resource.

Configuration of the client application just needs two values to be set.

```properties
spring.cloud.azure.appconfiguration.managed-identity.client-id= <your client id>
spring.cloud.azure.appconfiguration.stores[0].endpoint= <URI of your Configuration Store>
```

The first property tells us which of the configured User Assigned identities to use. The second is which configuration store we are connecting to. With this method, all configuration stores need to use the same User Assigned Identity.

Next, the User Assigned Identity needs to be setup in your configuration store. Setup can be done through IAM in the Azure Portal or using the cli:

```azurecli
az role assignment  create --role "App Configuration Data Reader" --assignee <your client id> --scope /subscriptions/<your subscription>/resourceGroups/<your stores resource group>/providers/Microsoft.AppConfiguration/configurationStores/<name of your Configuration Store>
```

### System Assigned Identity

Setting up System Assigned Identity involves enabling it on the azure resource. How the identity is enabled depends on the resource, so you will need to check the documentation for that resource. Once it is enabled, you need to configure your client application to use it.

```properties
spring.cloud.azure.appconfiguration.stores[0].endpoint= <URI of your Configuration Store>
```

You will then need to assign the System Assigned Identity to read configurations.

```azurecli
az role assignment  create --role "App Configuration Data Reader" --assignee <your client id> --scope /subscriptions/<your subscription>/resourceGroups/<your stores resource group>/providers/Microsoft.AppConfiguration/configurationStores/<name of your Configuration Store>
```

### Token Credential

To authenticate with any other method supported by the [Azure Identity Library](https://github.com/Azure/azure-sdk-for-java/tree/azure-identity_1.3.6/sdk/identity/azure-identity), you can use `AppConfigurationCredentialProvider`. `AppConfigurationCredentialProvider` allows you to dynamically return any `TokenCredential` for any given URI to connect to your Configuration stores.

```java
@Bean
public AppConfigurationCredentialProvider appConfigurationCredentialProvider() {
    return new AppConfigurationCredentialProvider() {
        
        @Override
        public TokenCredential getAppConfigCredential(String uri) {
            
            ...
            
            return myTokenCredential;
        }
    };
}
```

You will also need to configure the endpoints that you will be connecting too.

```properties
spring.cloud.azure.appconfiguration.stores[0].endpoint= <URI of your Configuration Store>
```

> [!NOTE]
> Only 1 authentication method can be defined per endpoint; Connection String, User Assigned Identity, Token Credential. If you need to mix and match you can have `AppConfigurationCredentialProvider` return `null` for stores that use a different method.

## For more information

See [Starter Readme](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/appconfiguration/azure-spring-cloud-starter-appconfiguration-config) for more details and compete documentation of all settings.