GuruGroup logo
Microsoft Dynamics 365 & Azure Security

Azure KeyVault Integration in D365FO

Executive Summary & Key Architectural Takeaways
  • Centralized Cryptographic Store: Storing third-party API keys, certificates, and secrets in Azure KeyVault rather than hardcoding them within D365FO.
  • Entra ID App Authentication: Using Microsoft Entra ID (Azure AD) App Registrations with Client ID and Secret values for seamless service authentication.
  • Vault Access Policy Model: Granting granular KeyVault permissions to authorized users and service principals to maintain least-privilege security.
  • D365FO Native Parameters Setup: Configuring Key Vault URL, App Client ID, and custom Secret URIs (vault://[keyvaultname]/secretname/[secretversion]).
  • Runtime X++ Secret Retrieval: Calling KeyVaultCertificateHelper::getManualSecretValue() to fetch decrypted credentials directly into memory.

Overview: What is Azure KeyVault?

Azure KeyVault is a cloud service provided by Azure which allows us to store and manage sensitive data like passwords, API keys, and encryption keys used by our applications.

In modern enterprise software architectures, business applications no longer live in silos. As integrations multiply, managing credentials securely across production, staging, and development environments becomes a critical operational requirement.

“Hardcoding sensitive API tokens directly into application logic or database parameter tables creates severe compliance and security vulnerabilities. Azure KeyVault eliminates this risk entirely.”

— Ebad Ahmed, Dynamics 365 & Cloud Solutions Consultant

The Enterprise Security Challenge

Challenge: Our D365FO application relies on various third-party APIs, each requiring unique API keys for access. These keys are sensitive credentials that need to be handled with utmost care to prevent unauthorized access and potential security breaches.

Current Approach: Storing these API keys directly within our applications poses a significant security risk and creates major challenges in managing, auditing, and rotating keys across different environments.

Desired Outcome: We need a secure and centralized solution to manage and access these API keys, ensuring keys are stored in a hardened, tamper-proof environment and minimizing the risk of unauthorized exposure.

Architecture Comparison: Cleartext Storage vs. Azure KeyVault Integration
Hardcoded / Local Database Storage Secrets stored directly in X++ code, table fields, or XML config files. Exposed to developers, source repositories, database backups, and unauthorized database exports.
Azure KeyVault Protected Architecture Hardware-backed cryptographic storage, centralized access policies, encrypted in-transit retrieval, granular audit telemetry, and seamless credential rotation.

Step 1: Create and Set Up a New Azure KeyVault

Go to your Azure Subscription on the Azure Portal and search for the Key Vaults service.

Searching KeyVaults in Azure Portal
Figure 1: Navigating to the Key Vaults service in the Microsoft Azure Portal.

Click Create to begin configuring your vault:

  • Resource Group: Select an existing resource group or create a new one by clicking “Create new” and entering a desired name.
  • Key Vault Name: Give your KeyVault a unique name that clearly identifies its purpose.
  • Region / Location: Choose the region where your KeyVault will be deployed (preferably matching your D365FO cloud datacenter).

After filling in the necessary details, click the Review + create button.

Review and create KeyVault in Azure
Figure 2: Reviewing configuration parameters before deploying the KeyVault.

Once validation succeeds, click Create. You will observe that the deployment completes successfully:

Deployment succeeded confirmation
Figure 3: Deployment completed successfully in the Azure subscription.

Navigate to the newly created KeyVault resource. Copy the Vault URI displayed on the Overview page—we will use this URI inside our D365FO application:

Copying KeyVault URI from Overview tab
Figure 4: Copying the Vault URI from the Azure KeyVault overview blade.

Configuring Access Control and Secrets

Navigate to Secrets on the left side of the menu to begin storing your application credentials:

Secrets menu blade in Azure KeyVault
Figure 5: Navigating to the Secrets configuration blade.

When you open the Secrets window, you may encounter an error message: “You are unauthorized to view these contents”. This indicates that your user account lacks the necessary data plane permissions to access KeyVault data:

Unauthorized message in Secrets tab
Figure 6: Unauthorized notification indicating missing access policy permissions.

To solve this, navigate to Access configuration on the left side menu:

Access configuration menu in KeyVault
Figure 7: Access configuration blade settings.

Set the Permission model to Vault access policy, which applies access control directly to the KeyVault itself. Click Apply to save changes:

Setting Permission model to Vault access policy
Figure 8: Applying the Vault access policy permission model.

Navigate to Access policies on the left side menu and click Create:

Creating new Access Policy
Figure 9: Initializing access policy creation for your user account.

Select the required permissions for Key permissions, Secret permissions, and Certificate permissions (for administrative setup, all permissions can be selected), then click Next:

Assigning Key, Secret, and Certificate permissions
Figure 10: Assigning appropriate permissions in the access policy wizard.

On the Principal window, search for and select the user account you want to grant access to your KeyVault, then click Next:

Selecting Principal user account
Figure 11: Selecting the user principal for access policy assignment.

On the Review + create tab, review the permissions and click Create. Now return to the Secrets page—the unauthorized warning is resolved, and you can now use the Generate/Import button to store your secret values:

Secrets page with Generate/Import enabled
Figure 12: Secrets blade fully unlocked with Generate/Import capability active.

Step 2: Microsoft Entra ID (Azure AD) App Registration

Next, we will register an application in Microsoft Entra ID to allow our D365FO instance to securely authenticate against Azure KeyVault without interactive user prompts.

On the Azure Portal, search for App registrations:

App registrations in Azure Portal
Figure 13: Navigating to App registrations in the Azure Portal.

Click on the New registration button:

New registration button in Azure
Figure 14: Starting a new application registration.
  • Name: Give your application a descriptive name (e.g., D365FO-KeyVault-Integration).
  • Supported account types: Select Accounts in this organizational directory only (Single tenant).

Click Register. On the Overview page, copy and record the Application (client) ID and Directory (tenant) ID—we will need both inside D365FO:

App registration Overview showing Client ID and Tenant ID
Figure 15: Registered App details displaying Application (client) ID and Tenant ID.

Creating the Client Secret

Navigate to Certificates & secrets on the left side menu:

Certificates and secrets menu
Figure 16: Certificates & secrets menu blade.

Click the New client secret button, enter a description, choose an expiration period, and click Add:

Adding a new client secret
Figure 17: Generating a new client secret with custom expiration.

Immediately copy the secret Value (this is the Secret Key). Important: This value is displayed only once and cannot be retrieved later:

Copying client secret value
Figure 18: Copying the newly generated client secret Value.

Step 3: Assign Vault Access Policy to the Registered App

Now we must grant permission from our Azure KeyVault to the Entra ID application we registered in Step 2.

Navigate back to your KeyVault resource, open Access policies, and click Create:

Creating access policy for application
Figure 19: Opening Access policies blade in Azure KeyVault.

Assign the necessary Secret permissions (specifically Get and List permissions are required for D365FO runtime retrieval):

Selecting secret permissions for app
Figure 20: Configuring Get and List permissions for the service principal.

On the Principal tab, search for and select the application you registered in Step 2:

Selecting registered application as Principal
Figure 21: Binding the registered application service principal to the access policy.

Complete the wizard and click Create. As shown below, the access policy is now assigned to the application:

Access policy assigned to application
Figure 22: Access policy successfully established for the application.

Step 4: Configure Key Vault Parameters in D365FO

Open your Dynamics 365 Finance & Operations environment. Navigate to the following path:

System administration > Setup > Key Vault parameters

Key Vault parameters form in D365FO
Figure 23: Opening the Key Vault parameters setup form in D365FO.

Create a new record and populate the values we obtained from Azure:

  • Name: Descriptive identifier for the KeyVault configuration.
  • Description: Purpose of the vault connection.
  • Key Vault URL: The Vault URI copied in Step 1 (e.g., https://your-vault-name.vault.azure.net/).
  • Key Vault Client: The Application (client) ID from Step 2.
  • Key Vault secret key: The Client Secret Value from Step 2.
Populating Key Vault parameters details in D365FO
Figure 24: Populating connection parameters and credentials in D365FO.

Defining Secrets in the Subgrid

Under the Key Vault secrets fast tab, click Add to register each secret. Secret values in D365FO must follow this specific URI syntax:

vault://[keyvaultname]/secretname/[secretversion]

Note: If you omit the [secretversion] component, D365FO will automatically retrieve the latest active version of the secret.

Set the Secret type field to Manual:

Defining Secret URI format in D365FO
Figure 25: Defining secret identifiers and setting secret type to Manual.

In this manner, you can register as many secrets as needed from your Azure KeyVault.

Step 5: Retrieve Secrets at Runtime Using X++

Once your Key Vault parameters and secret identifiers are defined in D365FO, you can retrieve any decrypted secret value at runtime using the standard X++ framework helper classes:

private static str getKeyVaultSecretValue(str _keyvaultSecretName)
{
    KeyVaultCertificateTable certificateTable = KeyVaultCertificateTable::findByName(_keyvaultSecretName);
    str keyvaultValue = KeyVaultCertificateHelper::getManualSecretValue(certificateTable.RecId);
    return keyvaultValue;
}

Code Analysis:

  • KeyVaultCertificateTable::findByName(_keyvaultSecretName) locates the parameter record defined in the Key Vault parameters form.
  • KeyVaultCertificateHelper::getManualSecretValue(certificateTable.RecId) handles authentication with Entra ID, queries the Azure KeyVault REST endpoint, and decrypts the secret value into memory.

In this manner, you can securely retrieve third-party API keys, payment gateway tokens, and connection strings without storing credentials in code or database tables.

Ready to Move Forward?

Turn Your Business Goals into Measurable Results

Partner with Guru Group to design, deliver, and scale secure technology solutions for your organization.