Dynamics 365 Business Central: using Azure Key Vault for your secrets

Azure Key Vault is a cloud service for securely storing and accessing secrets. A secret is anything that you want to tightly control access to, such as license keys, credentials, API keys, certificates and so on.

Starting form Dynamics 365 Business Central 2020 Wave 2 (version 17) you can start using Azure Key Vault service for storing your secrets and then retrieving them from AL code in a very easy way.

To start using Azure Key Vault from AL, you first need to have an instance created on an Azure subscription. When created, the Key Vault has an url like the following:

https://YourKeyVaultName.vault.azure.net/

Then you can insert secrets into your instance:

For each secret you need to create a name and a value, the you can optionally set an activation date (when it will become active) and an expiration date (when it will become inactive).

Now you need to grant Dynamics 365 Business Central to have access to your Azure Key Vault instance. Dynamics 365 Business Central is configured to use an Azure AD application for reading key vault secrets. The application is called Dynamics 365 Business Central ISV Key Vault Reader and:

1. The application must be provisioned into your Azure AD tenant
2. You need to grant the key vault reader application the permissions to read secrets from your key vaults

To provision the Dynamics 365 Business Central ISV Key Vault Reader application into your Azure AD tenant, you need to import the Azure AD Powershell Module and execute the following Powershell commands (with a user that has permissions to do so on the Azure AD):

Install-Module AzureAD
Import-Module AzureAD
#Connect to your Azure AD tenant (credentials required)
Connect-AzureAD
#Create an Azure AD service principal
New-AzureADServicePrincipal -AppId 7e97dcfb-bcdd-426e-8f0a-96439602627a

The last cmdlet creates an Azure AD service principal with the Application (client) ID of the Microsoft’s centralized Azure AD application:

Now you need to grant the Dynamics 365 Business Central ISV Key Vault Reader application the permission to read secrets from your key vaults. To do so, you need to access your Azure Key Vault resource via the Azure Portal, select Access policies and then Add access policy.

Here you need to create a new access policy as follows:

In the select principal box you need to select the Dynamics 365 Business Central ISV Key Vault Reader application from the available registered principals you have on your tenant.

Now there’s an extra step to make all working. To enable the Azure Key Vault integration you need to send an email to Microsoft at the  bcappkeyvaultonboard(AT)microsoft.com address for a manual verification step that verifies that you own the AAD tenant that contains the key vaults.

When all is done and configured, you can now use the Azure Key Vault integration from your extension’s code as explained above.

The first step to do is to add your Azure Key Vault url to the app.json file of your extension. You can do this by specifying the new keyVaultUrls property as follows:

Here you can specify up to two key vaults instances (useful if you want to have a backup key vault instance, maybe deployed in a different region that the first instance, for a step more in your security).

Then, in your code you can use the Key Vault secrets by calling the new App Key Vault Secret Provider codeunit. As an example, here I have a method that connects to the Azure Key Vault instance and then retrieves a secret called LicenseKey:

The TryInitializeFromCurrentApp method is used to retrieve the Azure Key Vault instance connected to the app.json file of the current extension. Then the GetSecret method permits you to retrieve a specific secret by name.

Please always remember an important thing: secrets must always be secrets 🙂 It’s absolutely recommended to use secrets retrieved from Azure Key Vault (but not only from it, see this as a general guideline for every secrets you have) in a method declared as [NonDebuggable]. In this way you’re sure that debugging cannot inspect the values on this method and then someone cannot retrieve these secrets.

Remember also that if you’re using Application Insights for collecting telemetry data of your Dynamics 365 Business Central tenant, the Azure Key Vault integration emits two events (initialization and retrieval) related to the success or the failure of the secret retrievals from the key vault.