Set up app key vaults for Business Central online

APPLIES TO: Business Central 2020 release wave 2 and later

AppSource apps for Business Central can be developed to get secrets from Azure keys vaults. The app key vault feature is readily available for use on the service by all AppSource apps. However, there are some onboarding tasks required.

Learn more about developing extensions with key vaults in Using key vault secrets in Business Central extensions.

Create the Azure key vault with secrets

In this task, you create a key vault in Azure, and add the secrets that you want to make available to your extensions. An extension can use up to two key vaults, so you can create more than one.

There are different ways to create an Azure key vault. For example, you can use the Azure portal, Azure CLI, and more.

The easiest way is to use the Azure portal. Learn more in Quickstart: Set and retrieve a secret from Azure key vault using the Azure portal.

For using other methods, learn more in Azure key vault Developer's Guide.

Provision the key reader application in your Microsoft Entra tenant

Your Business Central online solution is configured to use a Microsoft Entra application for reading key vault secrets. The application is called Dynamics 365 Business Central ISV key vault Reader. Microsoft manages the key vault reader application, however, there are a couple tasks that you have to do to enable it. First, the application must be provisioned on your Microsoft Entra tenant, as described here.

To provision the key vault reader application, use the Microsoft Entra ID PowerShell module.

1. Open Windows PowerShell as an administrator.

2. Install the Microsoft Entra ID PowerShell module.

   Install-Module AzureAD 
   

3. Import the Microsoft Entra ID module.

   Import-Module AzureAD 
   

4. Connect to your Business Central Microsoft Entra tenant.

   1. Run the following command:

      Connect-AzureAD 
      

   2. Provide your sign-in name and password when prompted.

5. Create a Microsoft Entra service principal using the following command:

   New-AzureADServicePrincipal -AppId 7e97dcfb-bcdd-426e-8f0a-96439602627a
   

   7e97dcfb-bcdd-426e-8f0a-96439602627a is the Application (client) ID of Microsoft's centralized Microsoft Entra application.

   This step provisions the application in your Microsoft Entra tenant, where it now "lives" together with your key vaults.

Grant the key vault reader application permission to your key vaults

The next task is to grant the key vault reader application permission to read secrets from your key vaults. The steps in this task are done from the Azure portal.

1. Open the key vault in the portal.
2. Select Access policies, then Add Access Policy.
3. Set Secret Permissions to Get.
4. Choose Select principal, and then in the pane on the right, search for either the application (client) ID 7e97dcfb-bcdd-426e-8f0a-96439602627a or the display name Dynamics 365 Business Central ISV key vault Reader.
5. Select Add, then Save.

Perhaps, if your key vault is using Azure Role-Based Access Control then the steps would be:

1. Navigate to your Azure Key Vault: In the Azure portal, go to your Key Vault resource.
2. Access Control (IAM): Under the Settings menu, select Access control (IAM).
3. Add Role Assignment: Click on + Add and choose Add role assignment.
4. Select Role: On the Add role assignment page, search for Key Vault Secrets User and select it from the search results. This role allows the service identity to read secrets but not perform any other actions.
5. Select Members: Go to the Members tab, select User, group, or service principal, then click on + Select members. In the pane on the right, search for either the application (client) ID 7e97dcfb-bcdd-426e-8f0a-96439602627a or the display name Dynamics 365 Business Central ISV key vault Reader.

Introduce the special Azure key vault secret

Once your key vault is created, there are few steps that you should perform. Feel free to skip the first couple of them if you're just linking new app to an existing Azure key vault.

1. Create AllowedBusinessCentralAppIds secret in your key vault. You can learn how to create a secret following this guide.
2. Add your AppId or AppIds as content of the secret. If you're adding multiple appIds separate them by comma or semicolumn. Your secret creation screen should look similar to this:
3. If you're linking a new app to the existing Azure key vault, you have to create a new version of the AllowedBusinessCentralAppIds secret. When creating the new version make sure to correctly append the new appId. In order to do so you have to get the value of the secret from the existing version by clicking on the secret name then on Current version and then on Show secret value, copy this value and upon creating the new verion modify the secret value to be the existing value + ", [new appId]".

Extra information

1. The key vault URLs added to your app.json file should belong to the same Microsoft Entra Tenant.
2. Microsoft registers the link between your AppSource app and Azure key vault upon submission of a new AppSource app version. Once this link is established, it can't be removed as this is considered breaking changes, and it might break existing installations of your AppSource app.
3. Even if the value of the AllowedBusinessCentralAppIds is deleted or some of the appIds are removed from the secret, this won't "deregister" the access to the key vault from this specific AppSource app. Once the registration is done, it's irreversible.
4. If you're facing issues that are generic and don't give you actionable error messages, contact the AppSource Marketplace support.

Related information

Security considerations with app key vaults
Monitoring and troubleshooting app key vaults
Configuring Business Central Server