BlogAnnounced at MongoDB.local NYC 2024: A recap of all announcements and updatesLearn more >>
MongoDB Developer
Sign in to follow topics
MongoDB Developer Centerchevron-right
Developer Topicschevron-right

Integrate Azure Key Vault with MongoDB Client-Side Field Level Encryption

Adrienne Tacke9 min read • Published Aug 27, 2021 • Updated May 24, 2022
Facebook Icontwitter iconlinkedin icon
Rate this tutorial
When implementing MongoDB’s client-side field level encryption (CSFLE), you’ll find yourself making an important decision: Where do I store my customer master key? In another tutorial, I guided readers through the basics of CSFLE by using a locally-generated and stored master key. While this works for educational and local development purposes, it isn’t suitable for production! In this tutorial, we’ll see how to use Azure Key Vault to generate and securely store our master key.


Quick Jump

Prepare Azure Infrastructure
Configure your Client Application to use Azure Key Vault and CSFLE

Register App in Azure Active Directory

In order to establish a trust relationship between our application and the Microsoft identity platform, we first need to register it. 
  1. Sign in to the Azure portal.
  2. If you have access to multiple tenants, in the top menu, use the “Directory + subscription filter” to select the tenant in which you want to register an application.
  3. In the main search bar, search for and select “Azure Active Directory.”
  4. On the left-hand navigation menu, find the Manage section and select “App registrations,” then “+ New registration.”
  5. Enter a display name for your application. You can change the display name at any time and multiple app registrations can share the same name. The app registration's automatically generated Application (client) ID, not its display name, uniquely identifies your app within the identity platform.
  6. Specify who can use the application, sometimes called its sign-in audience. For this tutorial, I’ve selected “Accounts in this organizational directory only (Default Directory only - Single tenant).” This only allows users that are in my current tenant access to my application.
  7. Click “Register.” Once the initial app registration is complete, copy the Directory (tenant) ID and Application (client) ID as we’ll need them later on.
  8. Find the linked application under “Managed application in local directory” and click on it.
  9. Once brought to the “Properties” page, also copy the “Object ID” as we’ll need this too.

Create a Client Secret

Once your application is registered, we’ll need to create a client secret for it. This will be required when authenticating to the Key Vault we’ll be creating soon.
  1. On the overview of your newly registered application, click on “Add a certificate or secret”:
  2. Under “Client secrets,” click “+ New client secret.”
  3. Enter a short description for this client secret and leave the default “Expires” setting of 6 months.
  4. Click “Ad." Once the client secret is created, be sure to copy the secret’s “Value” as we’ll need it later. It’s also worth mentioning that once you leave this page, the secret value is never displayed again, so be sure to record it at least once!

Create an Azure Key Vault

Next up, an Azure Key Vault! We’ll create one so we can securely store our customer master key. We’ll be completing these steps via the Azure CLI, so open up your favorite terminal and follow along:
  1. Sign in to the Azure CLI using the az login command. Finish the authentication steps by following the steps displayed in your terminal.
  2. Create a resource group: 
  3. Create a key vault: 

Create and Add a Key to Your Key Vault

With a key vault, we can now create our customer master key! This will be stored, managed, and secured by Azure Key Vault.
Create a key and add to our key vault:
The --protection parameter designates the key protection type. For now, we'll use the software type. Once the command completes, take note of your key’s "name" as we‘ll need it later!

Grant Application Permissions to Key Vault

To enable our client application access to our key vault, some permissions need to be granted:
  1. Give your application the wrapKey and unwrapKey permissions to the keyvault. (For the --object-id parameter, paste in the Object ID of the application we registered earlier. This is the Object ID we copied in the last "Register App in Azure Active Directory" step.)
  2. Upon success, you’ll receive a JSON object. Find and copy the value for the “vaultUri” key. For example, mine is

Integrate Azure Key Vault into Your Client Application

Now that our cloud infrastructure is configured, we can start integrating it into our application. We’ll be referencing the sample repo from our prerequisites for these steps, but feel free to use the portions you need in an existing application.
  1. If you haven’t cloned the repo yet, do so now! 
  2. Navigate to the root directory mongodb-csfle-csharp-demo-azure and open the EnvoyMedSys sample application in Visual Studio.
  3. In the Solution Explorer, find and open the launchSettings.json file (Properties > launchSettings.json).
  4. Here, you’ll see some scaffolding for some variables. Let’s quickly go over what those are:
    • MDB_ATLAS_URI: The connection string to your MongoDB Atlas cluster. This enables us to store our data encryption key, encrypted by Azure Key Vault.
    • AZURE_TENANT_ID: Identifies the organization of the Azure account.
    • AZURE_CLIENT_ID: Identifies the clientId to authenticate your registered application.
    • AZURE_CLIENT_SECRET: Used to authenticate your registered application.
    • AZURE_KEY_NAME: Name of the Customer Master Key stored in Azure Key Vault.
    • AZURE_KEYVAULT_ENDPOINT: URL of the Key Vault. E.g.,
  5. Replace all of the placeholders in the launchSettings.json file with your own information. Each variable corresponds to a value you were asked to copy and keep track of:
    • MDB_ATLAS_URI: Your Atlas URI.
    • AZURE_TENANT_IDDirectory (tenant) ID.
    • AZURE_CLIENT_IDApplication (client) ID.
    • AZURE_CLIENT_SECRET: Secret Value from our client secret.
    • AZURE_KEY_NAME: Key Name.
    • AZURE_KEYVAULT_ENDPOINT: Our Key Vault’s vaultUri.
  6. Save all your files!
Before we run the application, let’s go over what’s happening: When we run our main program, we set the connection to our Atlas cluster and our key vault’s collection namespace. We then instantiate two helper classes: a KmsKeyHelper and an AutoEncryptHelper. The KmsKeyHelper’s CreateKeyWithAzureKmsProvider() method is called to generate our encrypted data encryption key. This is then passed to the AutoEncryptHelper’s EncryptedWriteAndReadAsync() method to insert a sample document with encrypted fields and properly decrypt it when we need to fetch it. This is all in our Program.cs file:
Taking a look at the KmsKeyHelper class, there are a few important methods: the CreateKeyWithAzureKmsProvider() and GetClientEncryption() methods. I’ve opted to include comments in the code to make it easier to follow along:

KmsKeyHelper.cs / GetClientEncryption()
With our Azure Key Vault connected and data encryption key encrypted, we’re ready to insert some data into our Atlas cluster! This is where the AutoEncryptHelper class comes in. The important method to note here is the EncryptedReadAndWrite() method:
AutoEncryptHelper.cs / EncryptedReadAndWrite()
Now that we know what’s going on, run your application!

The Results: What You Get After Integrating Azure Key Vault with MongoDB CSFLE

If all goes well, your console will print out two DataKeyIds (UUID and base64) and a document that resembles the following: 
Sample Result Document (using my information)
Here’s what my console output looks like, for reference:
Screenshot of console output showing two Azure DatakeyIds and a non-formatted document
Seeing this is great news! A lot of things have just happened, and all of them are good:
  • Our application properly authenticated to our Azure Key Vault.
  • A properly generated data encryption key was created by our client application.
  • The data encryption key was properly encrypted by our customer master key that’s securely stored in Azure Key Vault.
  • The encrypted data encryption key was returned to our application and stored in our MongoDB Atlas cluster.

Here’s the same process in a workflow:
Workflow diagram of how a data encryption key is set up with a KMS Provider. Client application creates an unecrypted data encryption key which requests encryption from Azure Key Vault (the KMS provider). using the Customer Master Key, Azure Key Vault encrypts the data encryption key, sends it back to the client application which then stores the encrypted key in MongoDB's key vault collection.
After a few more moments, and upon success, you’ll see a “Successfully upserted the sample document!” message, followed by the properly decrypted results of a test query. Again, here’s my console output for reference:
Screenshot of console output showing a "Successfully upserted the sample document message!" followed by a human-readable document of a sample patient's data, including properly decrypted SSN, policyNumber fields.
This means our sample document was properly encrypted, inserted into our patientData collection, queried with our auto-encrypting client by SSN, and had all relevant fields correctly decrypted before returning them to our console. How neat! 
And just because I’m a little paranoid, we can double-check that our data has actually been encrypted. If you log into your Atlas cluster and navigate to the patientData collection, you’ll see that our documents’ sensitive fields are all illegible:
Screenshot of encrypted document in Atlas cluster. Shows SSN, bloodType, polucyNumber, medicalRecord fields as asterisks and other fields as legible.

Let's Summarize

That wasn’t so bad, right? Let's see what we've accomplished! This tutorial walked you through:
  • Registering an App in Azure Active Directory.
  • Creating a Client Secret.
  • Creating an Azure Key Vault.
  • Creating and Adding a Key to your Key Vault.
  • Granting Application Permissions to Key Vault.
  • Integrating Azure Key Vault into Your Client Application.
  • The Results: What You Get After Integrating Azure Key Vault with MongoDB CSFLE.
By using a remote key management system like Azure Key Vault, you gain access to many benefits over using a local filesystem. The most important of these is the secure storage of the key, reduced risk of access permission issues, and easier portability!
For more information, check out this helpful list of resources I used while preparing this tutorial:
And if you have any questions or need some additional help, be sure to check us out on the MongoDB Community Forums and start a topic!
A whole community of MongoDB engineers (including the DevRel team) and fellow developers are sure to help!

Facebook Icontwitter iconlinkedin icon
Rate this tutorial

Getting Started with Unity for Creating a 2D Game

Apr 02, 2024 | 9 min read

Persistence in Unity Using Realm

Sep 07, 2022 | 14 min read

Using LINQ to Query MongoDB in a .NET Core Application

Feb 03, 2023 | 6 min read
Code Example

Saving Data in Unity3D Using SQLite

Sep 07, 2022 | 13 min read
Table of Contents