Setting up App Key Vaults for Business Central On-premises

Article
09/29/2023

APPLIES TO: Business Central 2020 release wave 2 and later

Note

Azure Active Directory is now Microsoft Entra ID. Learn more

Business Central extensions can be developed to get secrets from Azure Keys Vaults. This article describes the tasks required to set up Azure Keys Vaults for storing extension secrets and configure them in your Business Central deployment.

For more information about developing extensions with key vaults, see Using Key Vault Secrets in Business Central Extensions.

Prerequisites

To complete the tasks in this article, you need:

An Azure subscription with an Active Directory tenant.

You sign up for an Azure subscription at https://azure.microsoft.com. For information about getting a Microsoft Entra tenant, see How to get a Microsoft Entra tenant.
A security certificate

Later, you'll have to register and configure an application in Microsoft Entra ID for reading key vaults. This step requires a certificate. The certificate is used to prove the application's identity when requesting upon request. For a production environment, obtain a certificate from a certification authority or trusted provider.

In a test environment, if you don't have a certificate, then you can create your own self-signed certificate. For example, on the Business Central server computer, start Windows PowerShell as an administrator. Then at the prompt, run the following commands:
```
$cert = New-SelfSignedCertificate -Subject "BusinessCentralKeyVaultReader" -Provider "Microsoft Strong Cryptographic Provider"
$cert.Thumbprint
Export-Certificate -Cert $cert -FilePath c:\certs\BusinessCentralKeyVaultReader.cer
```
These commands add a certificate called BusinessCentralKeyVaultReader to the computer's LocalMachine > Personal (My) certificate store.

Create the Azure Key Vault with secrets

Now, you create one or more key vaults in Azure, and add the secrets that you want to make available to your extensions. An extension can be set up with one or two key vaults.

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.

After you create the key vault, add the secrets.
For using other methods, see Azure Key Vault Developer's Guide.

Register a key vault reader application in Microsoft Entra ID

Next, register an application on your Microsoft Entra tenant for reading secrets from the key vaults. When Microsoft Entra authentication was set up, a Microsoft Entra tenant was created in Azure. Reading key vaults requires a separate application registration with the Microsoft Entra tenant. You can use an existing application.

The steps in this task are done from the Azure portal.

You add the new application by using the Azure portal. For guidelines, see Register your application with your Microsoft Entra tenant.

When you add an application to a Microsoft Entra tenant, you must specify the following information:

Setting	Description
Name	The name of your application as it will display to your users, such as Business Central Key Vault Reader.
Supported account types	Specifies which accounts that you would like your application to support. For purposes of this article, select Accounts in this organizational directory only.

When completed, the Overview displays in the portal for the new application.

Copy the Application (client) ID. You'll use this information later.

Upload the security certificate to the registered application.

In this step, you upload the certificate file that you obtained as part of the prerequisites.

Go to the key vault reader application overview page. Select Certificates & secrets > Upload certificate. Follow the instructions to locate and upload the certificate.

Grant the key vault reader application permission to key vaults

In this task, you 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.

Open the key vault in the portal.
Select Access policies, then Add Access Policy.
Set Secret Permissions to Get.
Choose Select principal, and on the right, search for either Application (client) ID or display name for the key vault reader application.
Select Add.
Select Save.

At this point, the work in Azure is finished.

Configure the Business Central Server to use the Apps Key Vault feature

Next, you configure the Business Central Server instance to use the key vault reader application and its certificate, which you registered in Microsoft Entra ID, for authenticating to the key vaults.

If you're running a container-based environment, you have two options for configuring the server instance. You can either do it manually or use the Set-BcContainerKeyVaultAadAppAndCertificate script. Using the Set-BcContainerKeyVaultAadAppAndCertificate script is simpler and recommended.

Configure a container-based Business Central Server instance

If you are running a container-based environment, use the Set-BcContainerKeyVaultAadAppAndCertificate.ps1 script that is available in the NAV Container Helper GitHub repository at https://github.com/microsoft/navcontainerhelper/blob/master/ContainerHandling/Set-BcContainerKeyVaultAadAppAndCertificate.ps1.

Manually configure a Business Central Server instance

To complete this task, you'll need the user name of the service account that runs the Business Central Server.

If not already done, import your key vault certificate and its private keys to the local certificate store for the Business Central server computer.

You can import the certificate either using the MMC snap-in or Import-PfxCertificate cmdlet from a Windows PowerShell prompt.

For example, the following PowerShell command installs a certificate to the local machine's personal store:
```
Import-PfxCertificate -FilePath "C:\certificates\BusinessCentralKeyVaultReader.pfx" -Password (ConvertTo-SecureString -String "pfxpassword" -AsPlainText -Force) -CertStoreLocation Cert:\LocalMachine\My\
```
Give the service account used by the Business Central Server instance permission to access the certificates private key.

To do this using the MMC:
1. Open the MMC snap-in for certificates. See How to: View Certificates with the MMC Snap-in.
2. Expand the Certificates (Local Computer) node, expand the Personal node, and then select the Certificates subfolder.
3. In the right pane, right-click the certificate, select All Tasks, and then choose Manage Private Keys.
4. In the Security dialog box, choose Add.
5. In the Select Users, Computers, Service Accounts, or Groups dialog box, enter the name of the dedicated domain user account that is associated with Business Central Server, for example, NETWORK SERVICE. Then, choose the OK button.
6. In the Full Control field, select Allow, and then choose the OK button.
Make a note of the certificate thumbprint because you'll need it in the next step. See How to: Retrieve the Thumbprint of a Certificate.

Configure the Business Central Server instance.

Now, you'll configure App Key Vault settings on the server instance. The following table describes the settings that you must configure:

Setting (key name)	Value
Client Certificate Store Location (AzureKeyVaultClientCertificateStoreLocation)	Set to the certificate store location where key vault certificate was stored. Example: LocalMachine
Client Certificate Store Name (AzureKeyVaultClientCertificateStoreName)	Set to the certificate store name where key vault certificate was stored. Example: MY
Client Certificate Thumbprint (AzureKeyVaultClientCertificateThumbprint)	Set to the thumbprint for the key vault certificate. Example: 649419e4fbb87340f5a0f995e605b74c5f6d943e
Client ID (AzureKeyVaultClientId)	Set to the Application (client) ID of the key vault reader application registered in your Microsoft Entra tenant. Example: ed4129d9-b913-4514-83db-82e305163bec
Enable Publisher Validation (AzureKeyVaultAppSecretsPublisherValidationEnabled)	Specifies whether extensions can only use key vaults that belong to their publishers. Enabling this setting (`true`) blocks attempts in AL to read secrets from another publisher's key vault. When extensions that use key vault secrets are published, you must provide your Microsoft Entra tenant ID, which is done by using the Publish-NAVApp cmdlet with the `-PublisherAzureActiveDirectoryTenantId` parameter. Important We recommend that you only set it to `false` if you trust all extensions that will be installed. For more information, see App Key Vaults - Security considerations. Example: true

You can configure the instance using the Business Central Server Administration tool or Set-NAVServerConfiguration cmdlet.

To use the Set-NAVServerConfiguration cmdlet, start the Business Central Administration Shell as an administrator, and run the following commands one at a time. Replace brackets with your own values.

Set-NAVServerConfiguration -ServerInstance <serverInstance> -KeyName AzureKeyVaultClientCertificateStoreLocation -KeyValue <certificate store location>    
Set-NAVServerConfiguration -ServerInstance <serverInstance> -KeyName AzureKeyVaultClientCertificateStoreName -KeyValue <certifcate store>    
Set-NAVServerConfiguration -ServerInstance <serverInstance> -KeyName AzureKeyVaultClientCertificateThumbprint -KeyValue <certificate thumbprint> 
Set-NAVServerConfiguration -ServerInstance <serverInstance> -KeyName AzureKeyVaultClientId -KeyValue <application ID of key vault reader app in Azure> 
Set-NAVServerConfiguration -ServerInstance <serverInstance> -KeyName AzureKeyVaultAppSecretsPublisherValidationEnabled -KeyValue <true|false> 
Restart-NAVServerInstance -ServerInstance <serverInstance>

At this point, you can run your extensions that use key vault secrets to read secrets from key vault.

Tip

If your on-premises solution uses the ImportStreamWithUrlAccess method, you must have set up an Azure blob storage account and stored the account name and account keys in the current subscription's Azure KeyVault using the identifiers TEMPORARYDOCUMENTSTORAGEACCOUNT and TEMPORARYDOCUMENTSTORAGEKEY. That way, your users can use the integration with Outlook.