{"title":"Retrieve key vault secrets in extensions","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-app-key-vault/","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/developer/devenv-app-key-vault, 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/developer/devenv-app-key-vault","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":"Learn how to configure Azure Key Vault in an extension, retrieve secrets securely with SecretText, and monitor key vault operations.","date":"2026-10-09","meta":{"topic":"how-to"},"outline":[{"level":1,"title":"Retrieve key vault secrets in extensions","slug":"retrieve-key-vault-secrets-in-extensions","at":0,"chars":9714},{"level":2,"title":"Prerequisites for retrieving secrets","slug":"prerequisites-for-retrieving-secrets","at":598,"chars":756},{"level":2,"title":"Specify the Azure Key Vault in extensions","slug":"specify-the-azure-key-vault-in-extensions","at":1354,"chars":951},{"level":2,"title":"Add code to retrieve secrets from the key vault","slug":"add-code-to-retrieve-secrets-from-the-key-vault","at":2305,"chars":1817},{"level":2,"title":"Security considerations","slug":"security-considerations","at":4122,"chars":3362},{"level":3,"title":"Use SecretText","slug":"use-secrettext","at":4249,"chars":513},{"level":3,"title":"Don't pass the App Key Vault Secret Provider to untrusted code","slug":"dont-pass-the-app-key-vault-secret-provider-to-untrusted-code","at":4762,"chars":462},{"level":3,"title":"Enable publisher validation","slug":"enable-publisher-validation","at":5224,"chars":2260},{"level":4,"title":"How it works","slug":"how-it-works","at":5740,"chars":1110},{"level":4,"title":"Turning off publisher validation","slug":"turning-off-publisher-validation","at":6850,"chars":634},{"level":2,"title":"Monitoring and troubleshooting","slug":"monitoring-and-troubleshooting","at":7484,"chars":1885},{"level":3,"title":"Compiling and publishing","slug":"compiling-and-publishing","at":7518,"chars":427},{"level":3,"title":"Runtime","slug":"runtime","at":7945,"chars":1424},{"level":4,"title":"Using Application Insights","slug":"using-application-insights","at":8295,"chars":1074},{"level":2,"title":"Related information","slug":"related-information","at":9369,"chars":345}],"text":"# Retrieve key vault secrets in extensions\n> APPLIES TO: Business Central 2020 release wave 2 and later\nThis article describes how to code an extension to retrieve secrets from Azure Key Vault. Secrets are typically used when an extension calls a web service. Learn more about app key vaults and secrets in Use app key vaults with extensions<devenv-app-key-vault-overview>.\nDeveloping an extension to use secrets from a key vault involves two tasks, as described in this article:\n Specifying the Azure Key Vault in the extension's manifest.\n Adding code to retrieve the secrets from the key vault.\n## Prerequisites for retrieving secrets\n Using secrets requires that you have at least one Azure Key Vault with secrets set up and configured for use by the service. If you don't already have an Azure Key Vault, see Setting up App Key Vaults for Business Central online<../administration/setup-app-key-vault> or Setting up App Key Vaults for Business Central on-premises<../administration/setup-app-key-vault-onprem>.\n For coding, you need the URI of the Azure Key Vault that stores the secret and the name of the secret. If you don't have this information, you can get it from the Azure portal. 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## Specify the Azure Key Vault in extensions\nYou specify the key vaults for an extension in the extension's manifest file, app.json. To specify a key vault, add the `\"keyVaultUrls\"` setting and set its value to the key vault URL. The following example specifies a key vault that has the URI `https://mykeyvault.vault.azure.net`:\n```json\n\"keyVaultUrls\": [\n    \"https://mykeyvault.vault.azure.net\"\n]\n```\nYou can specify up to two key vaults in app.json, as shown in the following example:\n```json\n\"keyVaultUrls\": [\n    \"https://myfirstkeyvault.vault.azure.net\",\n    \"https://mysecondkeyvault.vault.azure.net\"\n]\n```\nSpecifying two key vaults can improve the availability of secrets, especially if the vaults are in different Azure regions. At runtime, the Business Central platform tries the configured key vaults in order until it retrieves the secret. If all attempts fail, GetSecret returns false. The extension must decide how to handle the failure.\n## Add code to retrieve secrets from the key vault\nNext, add code to the extension to read secrets from the key vault at runtime. Use the Secrets module of the System Application and codeunit `3800 \"App Key Vault Secret Provider\"`. The codeunit provides TryInitializeFromCurrentApp and two GetSecret overloads. For new code, use the overload that returns the secret in a SecretText variable.\nMethod|Description\n`TryInitializeFromCurrentApp(): Boolean`|Identifies the calling extension and initializes the codeunit with the key vaults specified in the extension's manifest.\n`GetSecret(SecretName: Text; var SecretValue: SecretText): Boolean`|Retrieves a secret from one of the app's key vaults without exposing its value to the debugger.\n`GetSecret(SecretName: Text; var SecretValue: Text): Boolean`|Retrieves a secret as text. Use the SecretText overload for new code.\nLook at the following example for a simple page object. The code retrieves the value of the secret named MySecret in an app key vault:\n```al\npage 50100 HelloWorldPage\n{\n    var\n        SecretProvider: Codeunit \"App Key Vault Secret Provider\";\n        SecretValue: SecretText;\n\n    trigger OnOpenPage()\n    begin\n        if SecretProvider.TryInitializeFromCurrentApp() then begin\n            if SecretProvider.GetSecret('MySecret', SecretValue) then\n                Message('The secret was retrieved successfully.')\n            else\n                Message('The secret couldn''t be retrieved.');\n        end else\n            Message('Error: ' + GetLastErrorText());\n    end;\n}\n```\nThe call to the TryInitializeFromCurrentApp method determines the extension that is currently being executed, then determines the extension's key vaults as specified in the extension manifest. After initialization, the GetSecret call reads secrets from the key vault.\n## Security considerations\nKeep the following information in mind when you use the App Key Vault feature with your extensions.\n### Use SecretText\nThe SecretText data type is designed to protect sensitive values from being exposed through the AL debugger when doing regular or snapshot debugging. Its use is recommended for applications that need to handle any kind of credentials like API keys, custom licensing tokens, or similar. Learn more about how to denote a secret text string, which is non-debuggable in methods-auto/secrettext/secrettext-data-type and Protecting sensitive values with the SecretText data type<devenv-secret-text>.\n### Don't pass the App Key Vault Secret Provider to untrusted code\nAfter you initialize the `App Key Vault Secret Provider` codeunit, you can use it to get secrets.\n If you pass the codeunit to another method, that method can use it.\n If you pass the codeunit to a method in another extension, then the other extension can also use the secret provider to get secrets.\nThese conditions may not be what you want, so be careful who you pass the secret provider to.\n### Enable publisher validation\nFor on-premises deployments, you can configure Business Central Server to run with or without publisher validation of key vault secret providers. The server's Enable Publisher Validation (AzureKeyVaultAppSecretsPublisherValidationEnabled) configuration setting controls publisher validation. The validation is a runtime operation that ensures extensions use only key vaults that belong to their publishers. It blocks attempts in AL to read secrets from another publisher's key vault.\n#### How it works\nPublisher validation is done by comparing the key vault's Microsoft Entra tenant ID with the extension publisher's Microsoft Entra tenant ID. It works this way:\n1. When an extension is published by using the Publish-NAVApp cmdlet<https://learn.microsoft.com/powershell/module/microsoft.dynamics.nav.apps.management/publish-navapp>, the publisher can provide their Microsoft Entra tenant ID by setting the `-PublisherAzureActiveDirectoryTenantId` parameter:\n ```powershell\n Publish-NavApp -ServerInstance <ServerInstance> -Path <PathToExtensionPackage> -PublisherAzureActiveDirectoryTenantId <MicrosoftEntraTenantId>\n ```\n> NOTE\n> An error won't occur if `-PublisherAzureActiveDirectoryTenantId` isn't set. There is nothing preventing you from publishing the extension at this point.\n1. When the extension runs, it tries to initialize the `App Key Vault Secret Provider` codeunit.\n1. The system compares the key vault's Microsoft Entra tenant ID with the Microsoft Entra tenant ID published with the extension:\n  If they match, initialization succeeds.\n  If they don't match, an error occurs.\n#### Turning off publisher validation\nPublisher validation is turned on by default, which is the recommended setting. If it's turned off, the server instance won't do any additional validation to ensure extensions have the right to read secrets from the key vaults that they specify. This condition implies some risk of unauthorized access to key vaults that you should be aware of. So, don't turn off publisher validation unless you trust the extensions that can be potentially installed.\nLearn more about how to turn publisher validation on or off in Configuring Business Central Server<../administration/server-instance-settings>.\n## Monitoring and troubleshooting\n### Compiling and publishing\nIf you get errors when you compile or publish your extension, check the following conditions:\n You're using an old Visual Studio Code AL extension. Upgrade to the latest AL extension.\n Your extension targets an older runtime. Make sure that the `\"runtime\"` value in the app.json file is at least `\"6.0\"`.\n You're running an old version of Business Central Server. Upgrade to at least version 17.0.\n### Runtime\nFor runtime operations, there are two sources that you can use for gathering details:\n Windows Event Log of the machine running the Business Central Server.\n Application Insights.\nThese sources provide details about retrieving secrets from key vaults, for calls to the TryInitializeFromCurrentApp and GetSecret methods from an extension.\n#### Using Application Insights\nYou can set up extensions to emit telemetry to an Application Insights resource in Azure.\n1. Create an Application Insights resource in Azure if you don't have one.\n For runtime 7.2 and later, copy the Application Insights connection string. For runtime 6.0 through 7.1, copy the instrumentation key.\n See Create an Application Insights resource<https://learn.microsoft.com/azure/azure-monitor/app/create-new-resource>.\n2. For runtime 7.2 and later, add the `\"applicationInsightsConnectionString\"` setting to the extension's app.json file and set it to the Application Insights connection string. If the extension targets runtime 6.0 through 7.1, set `\"applicationInsightsKey\"` to the instrumentation key.\n ```json\n \"applicationInsightsConnectionString\": \"<ConnectionString>\"\n ```\n3. Run your extension and view the data in Application Insights.\nSee Viewing telemetry data in Application Insights<../administration/telemetry-overview> and Analyzing App Key Vault Secret Trace Telemetry<../administration/telemetry-extension-key-vault-trace>.\n## Related information\nGet started with AL<devenv-get-started>\ndevenv-how-publish-and-install-an-extension-v2\nConfigure Business Central Server<../administration/configure-server-instance>\nApp key vault telemetry<../administration/telemetry-extension-key-vault-trace>\nProtecting sensitive values with the SecretText data type<devenv-secret-text>"}