Maintaining Azure Key Vault storage

Overview

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

1. Open the Microsoft Azure portal using the link: https:⁠//ms.portal.azure.com/.
2. 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.
3. 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

1. 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:⁠//learn.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:

Connect-AzAccount

$pfxFilePath = '<Localpath>'

$pwd = ''

$secretName = '<name>'

$keyVaultName = '<keyvault>'

$collection = New-ObjectSystem.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-AzKeyVaultSecret -VaultName $keyVaultName -Name $secretName -SecretValue $Secret -ContentType $secretContentType

Where:

<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

1. 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

1. Click the "Dashboard ⁠"⁠  button on the left panel to see the key vault created earlier.
2. 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.

1. Click on the "Secrets" tile.
2. 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.

1. 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.

1. Open the legacy portal https:⁠//manage.windowsazure.com/.
2. Click on "Azure Active Directory" from the left panel and select yours.
3. In opened the active directory, choose the "App registration⁠" tab.
4. Click the "New application registration" button on the bottom panel to create a new application entry.
5. 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.

1. Click the "Create" button.

Configure your application

1. Open the "App registrations" tab.
2. Find an appropriate application. The "Application ID" field has the same value as parameter of <Key Vault Client>.
3. Click the "Settings" button and then open the "Keys" tab.
4. 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.

1. 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.

1. Go back to the Microsoft Azure portal (https:⁠//ms.portal.azure.com/),
2. Open your key vault storage and click on the tile "Access policies⁠".
3. 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.
4. 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.