From time to time I have to configure the electronic certificate to be used in the SII (Immediate Information Supply) module and it always happens the same, I don’t remember exactly what I had to do. That is why I have decided to write this post, with a detailed step by step detailed so that I don’t have to spend more time googling how to do it, and hey, if I also help someone in the same situation, not that bad!
This post will be divided into three main parts. The first two parts are, as I said, the ones we need to use the SII module. In the third part, we will see how we can use these Key Vaults in our developments to store passwords and secrets in a secure way.
Upload certificate to an Azure Key Vault
The first thing we will do is upload our electronic certificate to an Azure Key Vault, but what is a Key Vault?
Azure Key Vault is a cloud service that provides a secure store for secrets. You can securely store keys, passwords, certificates, and other secrets.https://docs.microsoft.com/en-us/azure/key-vault/secrets/quick-create-portal
In this link you can get more details about the advantages of using this service.
Therefore, in order to upload our certificate, the first thing we will have to do is create a Key Vault within our Azure subscription. To do this, we go to the azure portal, click on the Create new resource button, search for “Key Vault” in the marketplace search engine and click on the Create button.
The next step will be to configure the necessary data requested by the Key Vault, such as the resources group (it can be a new or existing one), the name that we associate to the Key Vault, or the region in which we want to deploy it.
Once filled, click on the Review and Create button, and when creation is complete, the following notification will appear in the panel.
Now that we have the Key Vault created, we can proceed with the upload of the certificate. To do this, we will run the following PowerShell script setting the required values. In order to run this script, some minimum requirements are necessary:
- The certificate must have a .pfx extension (I have tested it with .p12 and it also works).
- The .Net Framework 4.7.2 or later must be installed.
- The Azure PowerShell module must be installed.
- The user running the script must have sufficient permissions within the Azure subscription.
$pfxFilePath = 'C:\Temp\jatomas.pfx'
$pwd = 'password'
$secretName = 'JATCertificateSecret'
$keyVaultName = 'JATKeyVault'
$collection = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2Collection
$pkcs12ContentType = [System.Security.Cryptography.X509Certificates.X509ContentType]::Pkcs12
$clearBytes = $collection.Export($pkcs12ContentType)
$fileContentEncoded = [System.Convert]::ToBase64String($clearBytes)
$secret = ConvertTo-SecureString -String $fileContentEncoded -AsPlainText –Force
$secretContentType = 'application/x-pkcs12'
Set-AzKeyVaultSecret -VaultName $keyVaultName -Name $secretName -SecretValue $Secret -ContentType $secretContentType
In this script you must set the following values:
- $pfxFilePath = Path where the certificate is located
- $pwd = Certificate password (if required)
- $secretName = Name of the secret that will be created in our key vault and will contain the certificate
- $keyVaultName = Name of the key vault that we have previously created
Once executed, Azure credentials will be requested.
Now, we go back to the Key Vault from the Azure portal, and we see that a new Secret has been created within it.
The next step will be to create a new Azure Active Directory App registration. Thanks to this, we can impersonate Dynamics 365 access to the Key Vault.
To do this, we go to Azure Active Directory. and we create a new app registration.
Once the app registration is created, we will create a secret, which will be used by Dynamics to authenticate and use the Key Vault. To do this, we go to Certificates & secrets and add a new one. We will have to put the name and when we want it to expire. Once the secret is generated, we copy it to a safe place to use it later.
To finish with the configuration within the Azure portal, we are going to add an access policy within the Key Vault that will give the necessary permissions to the app registration that we have just generated. To do this, we go to the Key Vault, Access Policies, and add a new policy. In it, we select the necessary template to associate the required permissions, and we select the application registry that we previously created.
Finally, we click on the save button. With this, we would already have all the necessary configuration on the Azure side.
Set up Key Vault in Microsoft Dynamics 365 Finance
Now, it’s time to go to Dynamics 365 Finance to make the necessary settings. For this we go to System Administration > Key Vault Parameters. We create a new record and fill it with the following values:
- Key Vault URL: DNS Name (Key Vault)
- Key Vault client: Application ID (App reg. AAD)
- Key Vault secret key: Secret generated by us (App reg. AAD)
Finally, add a new secret:
- Secret: vault://KeyVault_Name/Secret_Name/[Secret_Version] (In our case, we only have one version of the secret, so it is not necessary to indicate it).
- Secret type: Certificate
Now, click on the Validate button, and if everything went well, the following info should appear:
And with this, we would already have completed the configuration of the certificate to use in the SII, so that our colleagues can continue with the configuration and testing of the module.
Store passwords in Key Vault and use them from X++
Yes, apart from using Key Vaults to store our certificates for the SII, we can use these key stores to securely store the passwords we need, for example, to integrate with third-party applications from X++. With this, we would avoid storing them in our database, and of course, we would avoid having the passwords directly in the code (yes, in the code, believe it or not, it exists) and we would be able to centralize all this information in a single repository.
All we need is to add a new secret to the Key Vault manually by clicking on the Generate/Import button.
We enter the name of the secret and the password that we want to keep in the Value field.
And we configure it within Dynamics 365 Finance in the same way that we saw in the previous point.
The only difference with the previous configuration is that in this case the Secret Type is Manual.
Now, we can just use the secret from our x++ code, and this can be done quite simply, using the getManualSecretValue method of the KeyVaultCertificateHelper class.
/// Runs the class with the specified arguments.
/// <param name = "_args">The specified arguments.</param>
public static void main(Args _args)
KeyVaultCertificateTable certificateTable = KeyVaultCertificateTable::findByName('JATPassword');
str password = KeyVaultCertificateHelper::getManualSecretValue(certificateTable.RecId);
This method will return the value of the secret that we have configured, as can be seen in the following image.
I hope you find it useful! 🙂