{"title":"Setting up App Key Vaults for Business Central On-premises","url":"https://jonas-paprotka.de/docs/dev-itpro/administration/setup-app-key-vault-onprem/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/setup-app-key-vault-onprem, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/setup-app-key-vault-onprem","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Describes how to set up App Key Vault with Business Central on-premises.","date":"2021-04-01","meta":{"topic":"how-to"},"outline":[{"level":1,"title":"Setting up App Key Vaults for Business Central On-premises","slug":"setting-up-app-key-vaults-for-business-central-on-premises","at":0,"chars":12822},{"level":2,"title":"Prerequisites","slug":"prerequisites","at":509,"chars":1423},{"level":2,"title":"Create the Azure Key Vault with secrets","slug":"create-the-azure-key-vault-with-secrets","at":1932,"chars":780},{"level":2,"title":"Register a key vault reader application in Microsoft Entra ID","slug":"register-a-key-vault-reader-application-in-microsoft-entra-id","at":2712,"chars":1767},{"level":2,"title":"Grant the key vault reader application permission to key vaults","slug":"grant-the-key-vault-reader-application-permission-to-key-vaults","at":4479,"chars":1168},{"level":2,"title":"Configure the Business Central Server to use the Apps Key Vault feature","slug":"configure-the-business-central-server-to-use-the-apps-key-vault-feature","at":5647,"chars":6755},{"level":3,"title":"Configure a container-based Business Central Server instance","slug":"configure-a-container-based-business-central-server-instance","at":6211,"chars":499},{"level":3,"title":"Manually configure a Business Central Server instance","slug":"manually-configure-a-business-central-server-instance","at":6710,"chars":5692},{"level":2,"title":"Related information","slug":"related-information","at":12402,"chars":420}],"text":"# Setting up App Key Vaults for Business Central On-premises\n> APPLIES TO: Business Central 2020 release wave 2 and later\nBusiness 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.\nLearn more about developing extensions with key vaults in Use key vault secrets in Business Central extensions<../developer/devenv-app-key-vault>.\n## Prerequisites\nTo complete the tasks in this article, you need:\n An Azure subscription with an Active Directory tenant.\n  You sign up for an Azure subscription at https://azure.microsoft.com<https://azure.microsoft.com>. For information about getting a Microsoft Entra tenant, see How to get a Microsoft Entra tenant<https://learn.microsoft.com/azure/active-directory/develop/active-directory-howto-tenant>.\n A security certificate\n  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.\n  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:\n  ```powershell\n  $cert = New-SelfSignedCertificate -Subject \"BusinessCentralKeyVaultReader\" -Provider \"Microsoft Strong Cryptographic Provider\"\n  $cert.Thumbprint\n  Export-Certificate -Cert $cert -FilePath c:\\certs\\BusinessCentralKeyVaultReader.cer\n  ```\n  These commands add a certificate called BusinessCentralKeyVaultReader to the computer's LocalMachine > Personal (My) certificate store.\n## Create the Azure Key Vault with secrets\nNow, 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.\nThere are different ways to create an Azure key vault. For example, you can use the Azure portal, Azure CLI, and more.\n 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<https://learn.microsoft.com/azure/key-vault/secrets/quick-create-portal>.\n  After you create the key vault, add the secrets.\n For using other methods, see Azure Key Vault Developer's Guide<https://learn.microsoft.com/azure/key-vault/general/developers-guide#creating-and-managing-key-vaults>.\n## Register a key vault reader application in Microsoft Entra ID\nNext, 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.\nThe steps in this task are done from the https://portal.azure.com.\n1. Sign in to Azure portal at https://portal.azure.com and set the portal to your Microsoft Entra tenant.\n2. Register a Microsoft Entra application for the reading key vault.\n You add the new application by using the https://portal.azure.com. For guidelines, see Register your application with your Microsoft Entra tenant<https://learn.microsoft.com/azure/active-directory/develop/quickstart-register-app>.\n When you add an application to a Microsoft Entra tenant, you must specify the following information:\n Setting|Description\n Name|The name of your application as it will display to your users, such as Business Central Key Vault Reader.\n 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.\n When completed, the Overview displays in the portal for the new application.\n Copy the Application (client) ID. You'll use this information later.\n2. Upload the security certificate to the registered application.\n In this step, you upload the certificate file that you obtained as part of the prerequisites.\n Go to the key vault reader application overview page. Select Certificates & secrets > Upload certificate. Follow the instructions to locate and upload the certificate.\n## Grant the key vault reader application permission to key vaults\nIn this task, you grant the key vault reader application permission to read secrets from your key vaults.\nThe steps in this task are done from the https://portal.azure.com.\n1. Open the key vault in the portal.\n2. Select Access policies, then Add Access Policy.\n3. Set Secret Permissions to Get.\n4. Choose Select principal, and on the right, search for either Application (client) ID or display name for the key vault reader application.\n5. Select Add.\n6. Select Save.\nIf your key vault uses Azure role-based access control (Azure RBAC), use these steps instead:\n1. In the Azure portal, open your key vault.\n2. Select Access control (IAM).\n3. Select Add > Add role assignment.\n4. On the Role tab, search for and select Key Vault Secrets User.\n5. On the Members tab, select User, group, or service principal, and then select + Select members.\n6. Search for the key vault reader application by its Application (client) ID or display name, for example, Dynamics 365 Business Central Key Vault Reader On-Prem, and then add it.\n7. Complete the role assignment.\nAt this point, the work in Azure is finished.\n## Configure the Business Central Server to use the Apps Key Vault feature\nNext, 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.\nIf 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.\n### Configure a container-based Business Central Server instance\nIf 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<https://github.com/microsoft/navcontainerhelper/blob/master/ContainerHandling/Set-BcContainerKeyVaultAadAppAndCertificate.ps1>.\n### Manually configure a Business Central Server instance\nTo complete this task, you'll need the user name of the service account that runs the Business Central Server.\n1. If not already done, import your key vault certificate and its private keys to the local certificate store for the Business Central server computer.\n You can import the certificate either using the https://learn.microsoft.com/dotnet/framework/wcf/feature-details/how-to-view-certificates-with-the-mmc-snap-in or Import-PfxCertificate cmdlet<https://learn.microsoft.com/powershell/module/pki/import-pfxcertificate> from a Windows PowerShell prompt.\n For example, the following PowerShell command installs a certificate to the local machine's personal store:\n ```powershell\n Import-PfxCertificate -FilePath \"C:\\certificates\\BusinessCentralKeyVaultReader.pfx\" -Password (ConvertTo-SecureString -String \"pfxpassword\" -AsPlainText -Force) -CertStoreLocation Cert:\\LocalMachine\\My\\\n ```\n2. Give the service account used by the Business Central Server instance permission to access the certificates private key.\n To do this using the MMC:\n 1. Open the MMC snap-in for certificates. See https://learn.microsoft.com/dotnet/framework/wcf/feature-details/how-to-view-certificates-with-the-mmc-snap-in.\n 2. Expand the Certificates \\(Local Computer\\) node, expand the Personal node, and then select the Certificates subfolder.\n 3. In the right pane, right-click the certificate, select All Tasks, and then choose Manage Private Keys.\n 4. In the Security dialog box, choose Add.\n 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.\n 6. In the Full Control field, select Allow, and then choose the OK button.\n3. Make a note of the certificate thumbprint because you'll need it in the next step. See https://learn.microsoft.com/dotnet/framework/wcf/feature-details/how-to-retrieve-the-thumbprint-of-a-certificate.\n4. Configure the Business Central Server instance.\n Now, you'll configure App Key Vault settings on the server instance. The following table describes the settings that you must configure:\n Setting<br />(key name)|Value\n Client Certificate Store Location<br />(AzureKeyVaultClientCertificateStoreLocation)|Set to the certificate store location where key vault certificate was stored.<br /><br />Example:<br />LocalMachine\n Client Certificate Store Name<br />(AzureKeyVaultClientCertificateStoreName)|Set to the certificate store name where key vault certificate was stored.<br /><br />Example:<br />MY\n Client Certificate Thumbprint<br />(AzureKeyVaultClientCertificateThumbprint)|Set to the thumbprint for the key vault certificate.<br /><br />Example:<br />649419e4fbb87340f5a0f995e605b74c5f6d943e\n Client ID<br />(AzureKeyVaultClientId)|Set to the Application (client) ID of the key vault reader application registered in your Microsoft Entra tenant.<br /><br />Example:<br />00001111-aaaa-2222-bbbb-3333cccc4444\n Enable Publisher Validation<br />(AzureKeyVaultAppSecretsPublisherValidationEnabled)|Specifies whether extensions can only use key vaults that belong to their publishers. <br /><br />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<https://learn.microsoft.com/powershell/module/microsoft.dynamics.nav.apps.management/publish-navapp> with the `-PublisherAzureActiveDirectoryTenantId` parameter.<br /><br />Important We recommend that you only set it to false if you trust all extensions that will be installed. See App Key Vaults - Security considerations<../developer/devenv-app-key-vault#security>.<br /><br />Example:<br />true\n You can configure the instance using the Business Central Server Administration tool<administration-tool> or Set-NAVServerConfiguration cmdlet<https://learn.microsoft.com/powershell/module/microsoft.dynamics.nav.management/set-navserverconfiguration>.\n 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.\n ```powershell\n Set-NAVServerConfiguration -ServerInstance <serverInstance> -KeyName AzureKeyVaultClientCertificateStoreLocation -KeyValue <certificate store location>\n Set-NAVServerConfiguration -ServerInstance <serverInstance> -KeyName AzureKeyVaultClientCertificateStoreName -KeyValue <certifcate store>\n Set-NAVServerConfiguration -ServerInstance <serverInstance> -KeyName AzureKeyVaultClientCertificateThumbprint -KeyValue <certificate thumbprint>\n Set-NAVServerConfiguration -ServerInstance <serverInstance> -KeyName AzureKeyVaultClientId -KeyValue <application ID of key vault reader app in Azure>\n Set-NAVServerConfiguration -ServerInstance <serverInstance> -KeyName AzureKeyVaultAppSecretsPublisherValidationEnabled -KeyValue <true|false>\n Restart-NAVServerInstance -ServerInstance <serverInstance>\n ```\nAt this point, you can run your extensions that use key vault secrets to read secrets from key vault.\n> TIP\n> If your on-premises solution uses the ../developer/methods-auto/system/system-importstreamwithurlaccess-method 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.\n## Related information\nUse app key vaults with Business Central extensions<../developer/devenv-app-key-vault-overview>\nSecurity considerations with app key vaults<../developer/devenv-app-key-vault#security>\nMonitor and troubleshoot app key vaults<../developer/devenv-app-key-vault#troubleshooting>\nAuthentication and Credential Types<users-credential-types>\nConfiguring Business Central Server<configure-server-instance>"}