Azure App Configuration Python Provider client library for Python

Azure App Configuration is a managed service that helps developers centralize their application configurations simply and securely. This provider adds additional functionality above the azure-sdk-for-python.

Using the provider enables loading sets of configurations from an Azure App Configuration store in a managed way.

Getting started

Get credentials

Use the Azure CLI snippet below to get the connection string from the Configuration Store.

az appconfig credential list --name <config-store-name>

Alternatively, get the connection string from the Azure Portal.

Creating a provider

You can create a client with a connection string:

import os
from azure.appconfiguration.provider import load

connection_string = os.environ["APPCONFIGURATION_CONNECTION_STRING"]

# Connecting to Azure App Configuration using connection string
config = load(connection_string=connection_string, **kwargs)

or with Entra ID:

import os
from azure.appconfiguration.provider import load
from azure.identity import DefaultAzureCredential

endpoint = os.environ["APPCONFIGURATION_ENDPOINT_STRING"]
credential = DefaultAzureCredential()

# Connecting to Azure App Configuration using Entra ID
config = load(endpoint=endpoint, credential=credential, **kwargs)

these providers will by default load all configurations with (No Label) from your configuration store into a dictionary of key/values.

Features

Currently the Azure App Configuration Provider enables:

Connecting to an App Configuration Store using a connection string or Entra ID.
Selecting multiple sets of configurations using SettingSelector.
Filtering by tags using tag_filters on SettingSelector.
Loading from snapshots using snapshot_name on SettingSelector.
Loading Feature Flags
Dynamic Refresh
Geo-Replication support with replica discovery and load balancing.
Trim prefixes off key names.
Resolving Key Vault References, requires Entra ID.
Secret Resolver, resolve Key Vault References locally without connecting to Key Vault.
Periodic Key Vault secret refresh via secret_refresh_interval.
Json Content Type
Configuration mapper for transforming settings during load.
Configurable startup timeout with retry.
Async support via azure.appconfiguration.provider.aio.

Examples

Selecting configurations

You can refine or expand the configurations loaded from your store by using SettingSelectors. Setting selectors provide a way to pass a key filter and label filter into the provider.

from azure.appconfiguration.provider import load, SettingSelector

# Connection to Azure App Configuration using SettingSelector
selects = [SettingSelector(key_filter="message*")]
config = load(
    endpoint=endpoint,
    credential=credential,
    selects=selects,
    feature_flag_enabled=True,
    feature_flag_selectors=None,
    **kwargs,
)

In this example, configuration settings with keys matching message* are loaded. Feature flags are also enabled, so the default feature flags (those with no label) will be loaded.

Filtering by Tags

You can filter configuration settings by tags using the tag_filters parameter on SettingSelector. Tag filters must follow the format "tagName=tagValue".

from azure.appconfiguration.provider import load, SettingSelector

# Filtering by tags
selects = [SettingSelector(key_filter="*", tag_filters=["env=prod"])]
config = load(endpoint=endpoint, credential=credential, selects=selects, **kwargs)

Loading from Snapshots

You can load configuration settings from a snapshot by providing snapshot_name on SettingSelector. When snapshot_name is specified, all configuration settings from the snapshot are loaded. Note that snapshot_name cannot be used together with key_filter, label_filter, or tag_filters. In the examples below, endpoint, credential, and snapshot_name are assumed to be defined. See the snapshot sample for complete setup.

from azure.appconfiguration.provider import load, SettingSelector

# Step 2: Loading configuration settings from the snapshot
snapshot_selects = [SettingSelector(snapshot_name=snapshot_name)]
config = load(endpoint=endpoint, credential=credential, selects=snapshot_selects, **kwargs)

You can also mix snapshot selectors with regular selectors. Later selectors take precedence when there are duplicate keys.

# Step 3: Combine snapshot with regular selectors (later selectors take precedence)
mixed_selects = [
    SettingSelector(snapshot_name=snapshot_name),  # Load all settings from snapshot
    SettingSelector(key_filter="override.*", label_filter="prod"),  # Also load specific override settings
]
config_mixed = load(endpoint=endpoint, credential=credential, selects=mixed_selects, **kwargs)

Dynamic Refresh

The provider can be configured to refresh configurations from the store on a set interval. This is done by providing a refresh_on to the provider, which is a list of key(s) that will be watched for changes, and when they do change a refresh can happen. refresh_interval is the period of time in seconds between refreshes. on_refresh_success is a callback that will be called only if a change is detected and no error happens. on_refresh_error is a callback that will be called when a refresh fails.

import os
from azure.appconfiguration.provider import load, WatchKey

connection_string = os.environ["APPCONFIGURATION_CONNECTION_STRING"]

config = load(
    endpoint=endpoint,
    credential=credential,
    refresh_on=[WatchKey("Sentinel")],
    refresh_interval=60,
    **kwargs,
)

In this example, the sentinel key will be checked for changes no sooner than every 60 seconds. In order to check for changes, the provider's refresh method needs to be called.

config.refresh()

Once the provider is refreshed, the configurations can be accessed as normal. And if any changes have been made it will be updated with the latest values. If the refresh_interval hasn't passed since the last refresh check, the provider will not check for changes.

For additional info check out Dynamic Refresh on MS Learn.

Trimming Keys

You can trim the prefix off of keys by providing a list of trimmed key prefixes to the provider. For example, if you have the key(s) like /application/message in your configuration store, you could trim /application/ from them.

from azure.appconfiguration.provider import load

# Connecting to Azure App Configuration using Entra ID and trim key prefixes
trimmed = ["test."]
config = load(endpoint=endpoint, credential=credential, trim_prefixes=trimmed, **kwargs)

Resolving Key Vault References

Key Vault References can be resolved by providing credentials to your key vault to the provider.

With Credentials

You can provide a keyvault_credential and all key vault references will be resolved with it. The provider will attempt to connect to any key vault referenced with the credential provided.

from azure.appconfiguration.provider import load, SettingSelector

# Connection to Azure App Configuration using Entra ID and Resolving Key Vault References
selects = [SettingSelector(key_filter="*", label_filter="prod")]

config = load(endpoint=endpoint, credential=credential, keyvault_credential=credential, selects=selects, **kwargs)

With Client Configs

You can provide keyvault_client_configs with a mapping of Key Vault URIs to client configurations. This is useful when different Key Vaults require different credentials.

from azure.appconfiguration.provider import load, SettingSelector

# Connection to Azure App Configuration using Entra ID with Provided Client
client_configs = {key_vault_uri: {"credential": credential}}
selects = [SettingSelector(key_filter="*", label_filter="prod")]
config = load(
    endpoint=endpoint,
    credential=credential,
    keyvault_client_configs=client_configs,
    selects=selects,
    **kwargs,
)

Secret Resolver

If no credentials or client configs are provided, a secret_resolver can be used. Secret resolver provides a way to return any value you want for a key vault reference.

from azure.appconfiguration.provider import load


def secret_resolver(uri):
    return "From Secret Resolver"


config = load(endpoint=endpoint, credential=credential, secret_resolver=secret_resolver, **kwargs)

Secret Refresh Interval

When using Key Vault references, the provider can periodically refresh resolved secrets. If you set the secret_refresh_interval parameter, secrets are refreshed at that interval (minimum 1 second).

from azure.appconfiguration.provider import load

# Refresh Key Vault secrets every 120 seconds
config = load(
    endpoint=endpoint,
    credential=credential,
    keyvault_credential=credential,
    secret_refresh_interval=120,
    **kwargs,
)

Geo Replication

The Azure App Configuration Provider library will automatically discover the provided configuration store's replicas and use the replicas if any issue arises. From more information see Geo-Replication.

Replica discovery is enabled by default. If you want to disable it, you can set replica_discovery_enabled to False.

from azure.appconfiguration.provider import load

# Disabling replica discovery
config = load(endpoint=endpoint, credential=credential, replica_discovery_enabled=False, **kwargs)

You can also enable load balancing to distribute requests across replicas by setting load_balancing_enabled to True.

from azure.appconfiguration.provider import load

# Enabling load balancing across replicas
config = load(endpoint=endpoint, credential=credential, load_balancing_enabled=True, **kwargs)

Loading Feature Flags

Feature Flags can be loaded from config stores using the provider. Feature flags are loaded as a list of feature flag objects stored in the provider under feature_management, then feature_flags.

from azure.appconfiguration.provider import load

config = load(endpoint=endpoint, credential=credential, feature_flag_enabled=True, **kwargs)
feature_flags = config["feature_management"]["feature_flags"]
alpha = next(flag for flag in feature_flags if flag["id"] == "Alpha")
print(alpha["enabled"])

By default all feature flags with no label are loaded when feature_flag_enabled is set to True. If you want to load feature flags with a specific label you can use SettingSelector to filter the feature flags.

from azure.appconfiguration.provider import load, SettingSelector

config = load(
    endpoint=endpoint,
    credential=credential,
    feature_flag_enabled=True,
    feature_flag_selectors=[SettingSelector(key_filter="*", label_filter="dev")],
    **kwargs,
)
feature_flags = config["feature_management"]["feature_flags"]
alpha = next(flag for flag in feature_flags if flag["id"] == "Alpha")
print(alpha["enabled"])

To enable refresh for feature flags you need to enable refresh. This will allow the provider to refresh feature flags the same way it refreshes configurations. Unlike configurations, all loaded feature flags are monitored for changes and will cause a refresh. Refresh of configuration settings and feature flags are independent of each other. Both are trigged by the refresh method, but a feature flag changing will not cause a refresh of configurations and vice versa. Also, if refresh for configuration settings is not enabled, feature flags can still be enabled for refresh.

import os
from azure.appconfiguration.provider import load, WatchKey

connection_string = os.environ["APPCONFIGURATION_CONNECTION_STRING"]

config = load(
    endpoint=endpoint,
    credential=credential,
    refresh_on=[WatchKey("message")],
    refresh_on_feature_flags=True,
    refresh_interval=60,
    feature_flag_enabled=True,
    feature_flag_refresh_enabled=True,
    **kwargs,
)

JSON Content Type

Configuration settings with a JSON content type (e.g., application/json) are automatically deserialized into their corresponding Python objects when loaded by the provider.

from azure.appconfiguration.provider import load

# Settings with JSON content type are automatically deserialized
config = load(endpoint=endpoint, credential=credential, **kwargs)
app_config = config["app/config"]  # Returns a dict if the value is JSON
print(app_config["timeout"])

Configuration Mapper

You can provide a configuration_mapper callback to transform configuration settings before they are added to the provider.

from azure.appconfiguration.provider import load


def my_mapper(setting):
    # Transform the setting as needed
    setting.value = setting.value.strip()


config = load(endpoint=endpoint, credential=credential, configuration_mapper=my_mapper, **kwargs)

Startup Timeout

The provider supports configurable startup timeout with automatic retry. By default, the provider allows 100 seconds for the initial load from Azure App Configuration. You can customize this with the startup_timeout parameter.

from azure.appconfiguration.provider import load

config = load(endpoint=endpoint, credential=credential, startup_timeout=200, **kwargs)

Async Support

The provider includes full async support via the azure.appconfiguration.provider.aio module.

from azure.appconfiguration.provider.aio import load

# Connecting to Azure App Configuration using Entra ID
config = await load(endpoint=endpoint, credential=credential, **kwargs)
print(config["message"])

await credential.close()
await config.close()

Key concepts

The AzureAppConfigurationProvider is the main object returned by load(). It implements the Mapping interface, so it can be used like a read-only dictionary. Call refresh() (or await refresh() for async) to pull the latest values from the store.

Key types used:

SettingSelector — Filters which configuration settings to load by key, label, tags, or snapshot name.
WatchKey — Identifies a sentinel key (and optional label) used to trigger configuration refresh.
AzureAppConfigurationKeyVaultOptions — Groups Key Vault credential, per-vault client configs, and secret resolver options.

Troubleshooting

Logging

This library uses the standard logging library for logging. Information about configuration loading, refresh, and Key Vault resolution is logged at the DEBUG level.

Common Issues

Key Vault references not resolving — Ensure you have provided credentials via key_vault_options or keyvault_credential. Key Vault resolution requires Entra ID authentication.
Configuration not refreshing — Make sure you are calling config.refresh() periodically (e.g., before each request in a web app). The provider does not auto-refresh in the background.
Startup failures — If the store is unreachable during startup, the provider will retry until startup_timeout (default 100 seconds) is exceeded. Increase this value if your store is expected to have high latency.

Next steps

Check out our Django and Flask examples to see how to use the provider in a web application.

Django

Flask

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Release History

2.5.0 (2026-05-22)

Features Added

Added refresh_enabled parameter to the load method. Defaults to True if refresh_on is set. When set to True without refresh_on keys, all selected key-values are monitored for changes. When set to False, calling refresh will be a no-op.
Added the ability to monitor all selected key-values for refresh with the refresh_enabled kwarg. When this kwarg is set to True, and refresh_on is not specified, changes to any selected key-values will trigger configuration reload.

Other Changes

Switched feature flag refresh to use page-based etag checking instead of per-flag etag checking, reducing the number of requests needed to detect changes.

2.4.0 (2026-02-17)

Features Added

Added startup retry, if the initial load fails, the provider will retry until the startup timeout is reached. By default the retry period is 100s, and can be configured via the startup_timeout kwarg on the load method.
Adds support for adding audience to the kwargs for load allowing it to specify the audience for the request.
Added support for snapshot references. Configuration settings that reference a snapshot are automatically resolved and expanded during load.

Bugs Fixed

Fixes a bug where feature_flag_selects could be passed in as None which resulted in an exception on load, doing this now results in loading the default feature flags.
Fixes a bug where feature_flag_selects couldn't load snapshots.

2.3.1 (2025-11-13)

Bugs Fixed

Fixed a bug where calling the refresh method would always trigger it.

2.3.0 (2025-11-12)

Features Added

Added support for Azure App Configuration Snapshots, SettingSelector now has a snapshot_name parameter.
Added support for forced refresh of configurations when using Key Vault references. Adds secret_refresh_interval to the AzureAppConfigurationProvider load method. This allows the provider to refresh Key Vault secrets at a specified interval. Is set to 60 seconds by default, and can only be set if using Key Vault references.
Added support for async on_refresh_success.
Added support for Configuration Setting Mapping, new configuration_mapper parameter to the load method, allows for a callback to be added to modify configurations.

Bugs Fixed

Fixed a bug where feature flags were using the configuration refresh timer instead of the feature flag refresh timer.
When loading duplicate configurations only the priority configuration will be processed.

Other Changes

Updated Request Tracing

2.2.0 (2025-08-08)

Features Added

Added tag_filters in SettingSelector to filter settings by tags.
Added support for JSON comments in the load method, when a configuration setting has the json content type.

2.1.0 (2025-04-28)

Features Added

Added AllocationId to the feature flag telemetry metadata when the feature flag has telemetry enabled.

2.0.2 (2025-04-17)

Other Changes

Updates telemetry for JSON usage.

2.1.0b1 (2025-04-10)

Bugs Fixed

Updates the feature flag telemetry to use the provided endpoint instead of the endpoint of the store the feature flag was loaded from.
Removes FeatureFlagId from feature flag telemetry.

2.0.1 (2025-03-07)

Bugs Fixed

Updates the failure to load from a config store from a debug level log to a warning level log.
Fixes an issue where the stack trace from the azure sdk wasn't being logged on startup.
Fixes a bug where feature flags could be loaded as configurations.

Other Changes

Bumped minimum dependency on azure-core to >=1.30.0
Bumped minimum dependency on azure-appconfiguration to >=1.6.1

2.0.0 (2025-01-06)

Features Added

Added support for load balancing between replicas.
Added support for adding telemetry information to feature flags.

2.0.0b3 (2024-11-13)

Breaking Changes

Allocation Id value changed so other providers can match the value.

2.0.0b2 (2024-10-11)

Feature Added

Added AllocationId to the feature flag telemetry metadata when the feature flag has telemetry enabled.

Bugs Fixed

Fixed a number of cases where snake case was used instead of pascal case for feature flag telemetry.
- etag -> ETag
- feature_flag_reference -> FeatureFlagReference
- feature_flag_id -> FeatureFlagId

2.0.0b1 (2024-09-11)

Features Added

Added support for feature flag telemetry.

1.3.0 (2024-09-09)

Features Added

Added support for auto failover between replicas.
Added support for auto discovery of replicas.

1.2.0 (2024-05-24)

Features Added

Enable loading of feature flags with feature_flag_enabled
Select Feature Flags to load with feature_flag_selectors
Enable/Disable Feature Flag Refresh with feature_flag_refresh_enabled

Bugs Fixed

Fixes issue where loading configurations were slower due to returning a copy of the configurations.

1.1.0 (2024-01-29)

Features Added

New API for Azure App Configuration Provider, refresh, which can be used to refresh the configuration from the Azure App Configuration service. refresh by default can check every 30 seconds for changes to specified sentinel keys. If a change is detected then all configurations are reloaded. Sentinel keys can be set by passing a list of SentinelKey's to refresh_on.
Added new options on_refresh_success and on_refresh_failure callbacks to the load method. These callbacks are called when the refresh method successfully refreshes the configuration or fails to refresh the configuration.

Bugs Fixed

Verifies that the refresh_interval is at least 1 second.

1.1.0b3 (2023-12-19)

Features Added

Added on_refresh_success callback to load method. This callback is called when the refresh method successfully refreshes the configuration.
Added minimum up time. This is the minimum amount of time the provider will try to be up before throwing an error. This is to prevent quick restart loops.

Bugs Fixed

Fixes issue where the refresh timer only reset after a change was found.

Other Changes

Renamed the type SentinelKey to be WatchKey.

1.1.0b2 (2023-09-29)

Features Added

Added support for keyvault_credential, keyvault_client_configs, and secret_resolver as kwargs instead of using AzureAppConfigurationKeyVaultOptions.

Bugs Fixed

Fixes issue where user_agent was required to be set.
Fixes issue where correlation context info is wrong on refresh.

1.1.0b1 (2023-09-13)

Features Added

New API for Azure App Configuration Provider, refresh, which can be used to refresh the configuration from the Azure App Configuration service. refresh by default can check every 30 seconds for changes to specified sentinel keys. If a change is detected then all configurations are reloaded. Sentinel keys can be set by passing a list of SentinelKey's to refresh_on.
Added support for customer provided user agent prefix.

Other Changes

Updated to use AZURE_APP_CONFIGURATION_TRACING_DISABLED environment variable to disable tracing.
Changed the maximum number of retries to 2 from the default of 3 retries.
Changed the maximum back off time between retries to 1 minute from the default of 2 minutes.
Bumped minimum dependency on azure-core to >=1.25.0

1.0.0 (2023-03-09)

Breaking Changes

Renamed load_provider to load
Added AzureAppConfigurationKeyVaultOptions to take in a client_configs a Mapping of endpoints to client kwargs instead of taking in the whole client.
Removed AzureAppConfigurationKeyVaultOptions secret_clients, client_configs should be used instead.
Made key_filter and label_filter kwargs for Setting Selector
Renamed trimmed_key_prefixes to trim_prefixes

Other Changes

Made EMPTY_LABEL a constant. i.e. "\0"

1.0.0b2 (2023-02-15)

Features Added

Added Async Support
Added missing methods for Mapping API
Made load method properties unordered.

Breaking Changes

Changes how load works. Moves if from AzureAppConfigurationProvider.load to load_provider.
Removed custom Key Vault Error
Removed unneeded repr and copy methods.
All Feature Flags are added to there own key and have there prefix removed

Bugs Fixed

Fixed Issue where Key Vault Clients couldn't be set in some situations

Other Changes

Updated method docs
Fixed load doc that used selector instead of selects.
Fixed CLI link in Readme.

1.0.0b1 (2022-10-13)

New Azure App Configuration Provider

Provides additional support above the Azure App Configuration SDK. Enables:

Connecting to an Azure App Configuration store
Selecting multiple keys using Setting Selector
Resolve Key Vault References when supplied AzureAppConfigurationKeyVaultOptions

The Azure App Configuration Provider once loaded returns a dictionary of key/value pairs to use in configuration.

endpoint = "https://<your-store>.azconfig.io"
default_credential = DefaultAzureCredential()
config = AzureAppConfigurationProvider.load(
    endpoint=endpoint, credential=default_credential)
print(config["message"])

Version Diff