A business-sensitive data is usually used in a secured way. It means that a functionality or application working with this data must support data encryption, working with certificates, etc. As the cloud version of Microsoft Dynamics 365 for Finance and Operations doesn't support a local storage of certificates, customers need to use a key vault storage in this case. The Azure Key Vault provides opportunity to import cryptographic keys, certificates to Azure, and to manage them. Additional information on the Azure Key Vault: What is Azure Key Vault.
The following data is required to define the integration between Microsoft Dynamics 365 for Finance and Operations and Azure Key Vault:
- Key vault URL (DNS name),
- Client ID (application identifier),
- List of the certificates with their names,
- Secret key (key value).
Below, you can find a detailed description of setup steps:
Create a Key Vault storage
- Open the Microsoft Azure portal using the link: https://ms.portal.azure.com/.
- Click the "Create a resource" button on the left panel to create a new resource. Choose the “Security + Identity” group and the "Key Vault" resource type.
- The "Create key vault" page is opened. Here, you should define key vault storage parameters and then click the "Create" button:
- Specify "Name" of the key vault. This parameter is referred in "Setting up Azure Key Vault Client" as <KeyVaultName>.
- Select your subscription.
- Choose a resource group. It’s like an internal directory inside the key vault storage. You may both use an existing resource group or create a new one.
- Select your location.
- Select a pricing tier.
- Click "Create".
- Pin the created Key vault to the Dashboard.
Upload a certificate
Upload procedure to the key vault storage depends on a certificate type.
Import of the *.pfx certificates
- The certificates with extension *.pfx can be uploaded to the Azure Key Vault using a PowerShell-script.
- Install the module AzureRM for PowerShell following this instruction: https://docs.microsoft.com/ru-ru/powershell/azure/install-azurerm-ps?view=azurermps-5.4.0
- Run a script in the PowerShell like in the example shown below:
$pfxFilePath = '<Localpath>'
$pwd = ''
$secretName = '<name>'
$collection = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2Collection
$collection.Import($pfxFilePath, $pwd, [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::Exportable)
$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-AzureKeyVaultSecret -VaultName '<keyvault>' -Name $secretName -SecretValue $Secret -ContentType $secretContentType
<Localpath> - local path to the file with certicate, e.g. C:\<smth>.pfx
<name> - name of the certificate, e.g. <smth>
<keyvault> - name of the Key vault storage
If password is required, add it to the tag $pwd
- Set a tag for the certificate uploaded to the Azure Key vault.
- In Microsoft Azure portal, click the "Dashboard" button and select the appropriate Key vault to open it.
- Click on the "Secrets" tile.
- Find an appropriate secret by the certificate name and open it.
- Open the "Tags" tab.
- Set Tag name = "type" and Tag value = "certificate".
Note: Tag name and Tag value must be filled in without quotes and in lowercase.
- Click the OK button and save the updated secret.
Import of the other certificates
- Click the "Dashboard" button on the left panel to see the key vault created earlier.
- Select the appropriate Key vault to open it. The "Overview" tab shows essential parameters of the key vault storage, including a "DNS name".
Note: The DNS Name is a mandatory parameter for integration with the key vault, therefore it should be specified in the application, and referred in "Setting up Azure Key Vault Client" as <Key Vault URL> parameter.
- Click on the "Secrets" tile.
- Click the "Generate/Import" button on the "Secrets" page to add a new certificate to the key vault storage. On the right side of the page, you should define the certificate parameters:
- Select the "Manual" value in the "Upload options" field.
- Enter the certificate name in the "Name" field.
Note: The Secret Name is a mandatory parameter for integration with the key vault, therefore it should be specified in the application. It is referred in "Setting up Azure Key Vault Client" as <SecretName> parameter.
- Open a certificate for editing and copy all its content including the beginning and closing tags.
- Paste the copied content in the "Value" field.
- Enable the certificate.
- Press the "Create" button.
- It's possible to upload several versions of the certificate and manage them in the key vault storage. If you need to upload a new version for an existing certificate, then select an appropriate certificate and click the "New version" button.
Note: The current version should be defined in application setup, and is referred to in "Setting up Azure Key Vault Client" as <SecretVersion> parameter.
Create an entry point for your application
Create an entry point for your application that uses the key vault storage.
- Open the legacy portal https://manage.windowsazure.com/.
- Click on "Azure Active Directory" from the left panel and select yours.
- In opened the active directory, choose the "App registration" tab.
- Click the "New application registration" button on the bottom panel to create a new application entry.
- Specify a "Name" of the application and select an appropriate type.
Note: On this page you may also define the "Sign-on URL", that should have a format http://<AppName>, where <AppName> is an application name specified on the previous page. <AppName> must be defined in the access policies for the key vault storage.
- Click the "Create" button.
Configure your application
- Open the "App registrations" tab.
- Find an appropriate application. The "Application ID" field has the same value as parameter of <Key Vault Client>.
- Click the "Settings" button and then open the "Keys" tab.
- Generate a key. It’s used for a secured access to the key vault storage from the application.
- Fill in the "Description" field.
- You may create a key with the duration period equals one or two years. After clicking the "Save" button in the bottom part of the page, the Key Value becomes visible.
Note: The Key Value is a mandatory parameter for integration with the key vault. It should be copied and then specified in the application. It is referred in "Setting up Azure Key Vault Client" as <Key Vault secret key> parameter.
- Copy the value of "Client ID" from the configuration. It should be specified in the application, and referred in "Setting up Azure Key Vault Client" as <Key Vault Client> parameter.
Add an application to the key vault storage
Add your application to the key vault storage created before.
- Go back to the Microsoft Azure portal (https://ms.portal.azure.com/),
- Open your key vault storage and click on the tile "Access policies".
- Click on the "Add new" button and choose the "Select principal" option. Then you should find your application by its name. When the application is found, click the "Select" button.
- Fill the "Configure from template" field and click the Ok button.
Note: On this page, you also may set up the key permissions if necessary.