Azure Cloud Config Source

The Azure cloud config source takes configuration properties from Azure Key Vault Secrets.

Register Azure AD Application and Create Service Principle

If you haven’t already, you will need to register an Azure Active Directory (Azure AD) application and create a service principal, so that the Microsoft identity platform can provide authentication and authorisation services. You can use the Azure portal to register your application and create a service principle.

  1. Once you have signed in to your Azure portal, search and select Azure Active Directory

  2. Select App registrations under the Manage section

  3. Click New registration

If you have access to multiple tenants and want to select a specific tenant to register with your application, use the Directory + subscription filter in the top menu.

Application Registration

Then on the Register an application page:

  1. Specify a name for your application

  2. Select the appropriate account types

  3. Click Register to complete your application registration

Once the application registration is completed, the service principal is automatically created in your home tenant.

Application Registration Configuration

Application API Permissions

You will need to allow your application full access to the Azure Key Vault service to enable it to retrieve secrets from the vault. To do this, you will need to configure your application’s API permissions. You can learn more about permissions and consent here.

  1. Select your application

  2. Select API permissions under the Manage section

  3. Click Add a permission

  4. Select Azure Key Vault for the list of Microsoft APIs

  5. Under the types of permissions, select Delegated permissions

  6. Tick the user_impersonation checkbox

  7. Click Add permissions

    API Permissions

Add Credentials

Credentials allow your application to authenticate as itself. Azure supports two options as credentials: client secret (a string) and certificate (public key). Currently, Payara Platform only supports certificate as they provide a higher level of assurance than client secrets. You can upload your certificate for authentication using the following steps:

  1. Select your application

  2. Select Certificates & Secrets under the Manage section

  3. Click Upload certificate

  4. Choose a certificate

  5. Click Add

Once the certificate is successfully uploaded, it should generate a Thumbprint, which will be required when we configure the Azure Config Source.

Certificate Upload

Supported Private Key formats

In this step, only an X.509 certificate is needed but the corresponding private key is needed when we configure the Payara MicroProfile Configuration Source. Currently, only an RSA private key in the PKCS8 unencrypted PEM format is supported. We have an issue open to also support an encrypted key and other formats. The OpenSSL commands to generate this private key and certificate are:

openssl req -x509 -newkey rsa:4096 -keyout demo-application.pem -out cert-demo-application.pem -days 365
openssl pkcs8 -in demo-application.pem -out demo-application.key

The first command will ask for the Subject DN parts of the certificate and the passphrase to encrypt the private key (written into the file demo-application.pem)

The second command will convert this encrypted private key file to the unencrypted equivalent which we require for the Payara configuration later on.

Create a Key Vault

To store your secrets securely, you will need to create a key vault.

  1. Search for key vaults and select it

  2. Click Add

  3. Provide relevant information on the Create key vault page

  4. Click Review + create

Although key vault allows storing of keys, secrets, and certificates, the Payara Azure Config Source currently only supports secrets.

Key Vault Creation

In the above diagram, the Basic section has been configured and the remaining sections have been left to their default settings. You can configure other sections, such as Access policy and Networking, to fit your requirements.

Configure access policies on Key Vault

To give your application access to the secrets in a key vault, you will need to add the application to the key vault’s access policies.

  1. Navigate to your key vault

  2. Select Access policies under the Settings section

  3. Click Add Access Policy

  4. Under Configure from template, select Secret Management, as we don’t require the other options

  5. Select the service principal that you created previously

  6. Click Add

  7. Click Save to commit your changes

Access Policy Configuration

Add a Secret to Key Vault

To add a secret to the key vault:

  1. Select the key vault you want to add your secret to

  2. Click on Secrets under the Settings section

  3. Click Generate/Import

  4. Provide relevant information on the Create a secret page

  5. Click Create

Secret Creation

Configuration in Payara Server

You can configure Azure Secrets either via the admin console or the asadmin utility. You will need the name of your key vault, tenant ID and client ID of your application, your private key file and thumbprint generated by your application after you uploaded your certificate.

Your private key file will be copied into ${PAYARA_DOMAIN}/config.

From the Admin Console

To configure the config source from the admin console, go to Configs → your-config → MicroProfile → Config → Azure Secrets.

Payara Server Administration Console configuration route

From here, you can pass the name of the key vault, tenant ID and client ID of the application, absolute path to the private key file and thumbprint of the certificate. You can also decide whether to apply these changes dynamically or on the next server restart. If the config source is enabled or disabled dynamically, it will take effect across the server immediately.

From the Command Line

To configure the Azure Config Source from the command line, use the set-azure-config-source-configuration asadmin command, specifying the required parameters like this:

asadmin> set-azure-config-source-configuration --dynamic true --enabled true --keyVaultName demo-secret-key-vault --tenantID 22b3bb26-e046-42df-9c96-65dbd72c1c81 --clientID 22b3bb26-e046-42df-9c96-65dbd72c1c81 --thumbprint 84E05C1D98BCE3A5421D225B140B36E86A3D5534 --privateKeyPath path/to/privatekey.pem

You can use the --enabled and --dynamic options to enable or disable the Azure Config Source on demand.

Also, you can retrieve the current configuration for the Azure Config Source using the get-azure-config-source-configuration asadmin command:

asadmin> get-azure-config-source-configuration

Enabled Tenant ID Client ID Key VaultName Private Key Path Thumbprint
true 22b3bb26-e046-42df-9c96-65dbd72c1c81 22b3bb26-e046-42df-9c96-65dbd72c1c81 demo-secret-key-vault path/to/privatekey.pem 84E05C1D98BCE3A5421D225B140B36E86A3D5534

Usage

Provided that all of the above sections are configured correctly, the secrets can be injected into any applicable MicroProfile Config injection point as with any other Config Source. The secrets can also be fetched, created and deleted from the asadmin utility.

To fetch a secret from a Key Vault:

asadmin> get-config-property --source cloud --sourceName azure --propertyName demo-secret
demo-secret-value

To create or change a secret in a Key Vault:

asadmin> set-config-property --source cloud --sourceName azure --propertyName mysecret --propertyValue secretvalue

To delete a secret from a Key Vault:

asadmin> delete-config-property --source cloud --sourceName azure --propertyName mysecret