Setting 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 App Source apps. However, there are some onboarding tasks required.

Important

With Business Central online, App key vaults can only be used with AppSource apps. They're not supported with per-tenant extensions.

Tip

You must also specify secrets in a key vault if you deploy Business Central as part of the Embed App program. Especially if you must support the Outlook add-in, in which case you must specify secrets for TEMPORARYDOCUMENTSTORAGEACCOUNT and TEMPORARYDOCUMENTSTORAGEKEY.

For more information about developing extensions with key vaults, see 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. For instructions, see Quickstart: Set and retrieve a secret from Azure Key Vault using the Azure portal.

For using other methods, see Azure Key Vault Developer's Guide.

Provision the key reader application in your Azure AD tenant

Your Business Central online solution 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. 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 Azure AD tenant, as described here.

To provision the key vault reader application, use the Azure Active Directory PowerShell module.

  1. Open Windows PowerShell as an administrator.

  2. Install the Azure Active Directory PowerShell module.

    Install-Module AzureAD 
    
  3. Import the Azure AD module.

    Import-Module AzureAD 
    
  4. Connect to your Business Central Azure AD tenant.

    1. Run the following command:

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

  5. Create an Azure AD 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 Azure AD application.

    This step provisions the application in your Azure AD 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 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.

Contact Microsoft to enable the App Key Vault feature

Send an email to bcappkeyvaultonboard@microsoft.com to start the onboarding process. Do this step before you publish your updated extension to Partner Center.

The onboarding process involves a manual verification step that verifies that you own the AAD tenant that contains the key vaults.

Provide the following information in the email:

  • Your AAD tenant ID. Obtain this information from the Azure portal by going to the Azure Active Directory Overview page.
  • Your AppSource extensions, including names and App IDs, that should be enabled to read secrets from your key vaults. Note: It is important that all your AppSource extensions that need access to a key vault are included, as it is not enough to just set the key vault property in your app.json manifest files.
  • Optionally, a screenshot from the Azure portal showing the key vault and its access policies. The screenshot can help Microsoft catch configuration mistakes early in the process.

See Also

Security Considerations With App Key Vaults
Monitoring and Troubleshooting App Key Vaults
Configuring Business Central Server