Configure MicroProfile with Azure Key Vault

This tutorial will demonstrate how to configure a MicroProfile application to retrieve secrets from Azure Key Vault using the MicroProfile Config APIs to create a direct connection to Azure Key Vault. By using the MicroProfile Config APIs, developers benefit from a standard API for retrieving and injecting configuration data into their microservices.

Before we dive in, lets quickly take a look at what a combination of Azure Key Vault and the MicroProfile Config API enables us to write in our code. Here's a code snippet of a field in a class that has been annotated with @Inject and @ConfigProperty. The name specified in the annotation is the name of the property to look up in Azure Key Vault, and the defaultValue is what will be set if the key isn't discovered. The end result is that the value stored in Azure Key Vault, or the default value, will be injected automatically into the field at runtime, simplifying the life of developers as they no longer need to pass values around in constructors and setter methods, instead leaving it to MicroProfile to handle.

@ConfigProperty(name = "key-name", defaultValue = "Unknown")
String keyValue;

It's also possible to access the MicroProfile config directly, to request secrets as necessary, for example:

public class DemoClass {
    Config config;

    public void method() {
        System.out.println("Hello: " + config.getValue("key-name", String.class));

This sample makes use of Payara Micro and MicroProfile to create a tiny Java war file that you can run locally on your machine. The sample doesn't demonstrate how to containerize or push the code to Azure, but the links section at the end of this tutorial has links to other useful tutorials that explain this.

This sample makes use of a free and open source library that creates a config source (using the MicroProfile Config API) for Azure Key Vault. You can learn more about this library, and review the code, on the project GitHub page. By using this library, the code in this tutorial can focus on configuration of the library, followed by injecting keys into your code, and we don't need to write any Azure-specific code.

Here are the steps required to run this code on your local machine, starting with creating an Azure Key Vault resource.

Creating an Azure Key Vault resource

We'll use the Azure CLI to create the Azure Key Vault resource and populate it with one secret.

First, create an Azure service principal to provide the client ID and key we need to access Key Vault:

az login
az account set --subscription <subscription_id>

az ad sp create-for-rbac --name <service_principal_name> \
    --role Contributor \
    --scopes /subscriptions/<subscription_id>

Let's say we use microprofile-keyvault-service-principal for the service principal name in the previous step. The response from Azure for doing this will be in the following, slightly censored, form:

  "appId": "5292398e-XXXX-40ce-XXXX-d49fXXXX9e79",
  "displayName": "microprofile-keyvault-service-principal",
  "name": "http://microprofile-keyvault-service-principal",
  "password": "9b217777-XXXX-4954-XXXX-deafXXXX790a",
  "tenant": "72f988bf-XXXX-41af-XXXX-2d7cd011db47"

Of particular note is the appID and password values - these are what we will use later on as client ID and key, respectively.

Now that we've created a service principal, we can optionally create a resource group (if you already have one you want to use, you can skip this step). Note that to get a list of resource group locations, you can call az account list-locations and use the name value from that list to specify where the resource group should be created.

# For this tutorial, the author chose to use `westus`
# and `jg-test` for the resource group name.
az group create -l <resource_group_location> -n <resource_group_name>

We now create an Azure Key Vault resource. Note that the Key Vault name is what you will use to reference the key vault later, so choose something memorable.

az keyvault create --name <your_keyvault_name>            \
                   --resource-group <your_resource_group> \
                   --location <location>                  \
                   --enabled-for-deployment true          \
                   --enabled-for-disk-encryption true     \
                   --enabled-for-template-deployment true \
                   --sku standard

We also need to grant the appropriate permissions to the service principal we created earlier, so that it may access the Key Vault secrets. Note that the appID value is the appId value from above where we created the service principal (that is, 5292398e-XXXX-40ce-XXXX-d49fXXXX9e79 - but use the value from your terminal output).

az keyvault set-policy --name <your_keyvault_name>   \
                       --secret-permission get list  \
                       --spn <your_sp_appId_created_in_step1>

We're now at the point where we can push a secret into Key Vault. Lets use the key name demo-key, and set the value of the key to be demo-value:

az keyvault secret set --name demo-key      \
                       --value demo-value   \
                       --vault-name <your_keyvault_name>  

That's it! We now have Key Vault running in Azure with a single secret. We can now clone this repo and configure it to use this resource in our app.

Getting up and running locally

This example is based on a sample application available on GitHub, so we'll clone that and then step through the code. Follow the steps below to get the code cloned onto your machine:

  1. git clone

  2. cd microprofile-configsource-keyvault

  3. Navigate to src/main/resources/META-INF/ and change the properties in file with details from above.

  4. Try running the server using mvn clean package payara-micro:start

  5. Try accessing http://localhost:8080/keyvault-configsource/api/config in your web browser - you should see a simple response that demonstrates values being read from Azure Key Vault.


This sample application bakes together the MicroProfile Config API, Azure Key Vault, and the free and open source microprofile-config-keyvault library to enable easy injection of configuration data and secrets into our MicroProfile web services.