Use Automatic Queryable Encryption with Azure
On this page
Overview
This guide shows you how to build an application that implements the MongoDB Queryable Encryption feature to automatically encrypt and decrypt document fields and use Azure Key Vault KMS for key management.
After you complete the steps in this guide, you should have:
A Customer Master Key managed by Azure Key Vault
A working client application that inserts documents with encrypted fields using your Customer Master Key
Tip
Customer Master Keys
To learn more about the Customer Master Key, read the Keys and Key Vaults documentation.
Before You Get Started
To complete and run the code in this guide, you need to set up your development environment as shown in the Installation Requirements page.
Tip
See: Full Application
To see the complete code for this sample application,
select the tab corresponding to your programming language and follow
the provided link. Each sample application repository includes a
README.md
file that you can use to learn how to set up your environment
and run the application.
Set Up the KMS
Register your Application with Azure
Log in to Azure.
Register your Application with Azure Active Directory
To register an application on Azure Active Directory, follow Microsoft's official Register an application with the Microsoft identity platform Quick Start.
Create the Customer Master Key
Create your Azure Key Vault and Customer Master Key
To create a new Azure Key Vault instance and Customer Master Key, follow Microsoft's official Set and retrieve a key from Azure Key Vault using the Azure portal Quick Start.
Important
Record your Credentials
Ensure you record the following credentials:
Key Name
Key Identifier (referred to as
keyVaultEndpoint
later in this guide)Key Version
You will need them to construct your dataKeyOpts
object
later in this tutorial.
Create the Application
Assign Your Application Variables
The code samples in this tutorial use the following variables to perform the Queryable Encryption workflow:
Important
Key Vault Collection Namespace Permissions
The Key Vault collection is in the encryption.__keyVault
namespace. Ensure that the database user your application uses to connect
to MongoDB has ReadWrite
permissions on this namespace.
Create your Encrypted Collection
Add Your Azure KMS Credentials
Create a variable containing your Azure KMS credentials with the following structure. Use the Azure Key Vault credentials you recorded in the Register your Application with Azure step of this tutorial.
Add your Customer Master Key Credentials
Create a variable containing your Customer Master Key credentials with the following structure. Use the Customer Master Key details you recorded in the Create a Customer Master Key step of this tutorial.
Set Your Automatic Encryption Options
Note
Automatic Encryption Options
The automatic encryption options provide configuration information to the Automatic Encryption Shared Library, which modifies the application's behavior when accessing encrypted fields.
To learn more about the Automatic Encryption Shared Library, see the Automatic Encryption Shared Library for Queryable Encryption page.
Specify Fields to Encrypt
To encrypt a field, add it to the encryption schema. To enable queries on a field, add the "queries" property. Create the encryption schema as follows:
Note
In the previous code sample, both the "ssn" and "billing" fields are encrypted, but only the "ssn" field can be queried.
Query on an Encrypted Field
The following code sample executes a find query on an encrypted field and prints the decrypted data:
The output of the preceding code sample should look similar to the following:
{ "_id": { "$oid": "648b384a722cb9b8392df76a" }, "name": "Jon Doe", "record": { "ssn": "987-65-4320", "billing": { "type": "Visa", "number": "4111111111111111" } }, "__safeContent__": [ { "$binary": { "base64": "L1NsYItk0Sg+oL66DBj6IYHbX7tveANQyrU2cvMzD9Y=", "subType": "00" } } ] }
Warning
Do not Modify the __safeContent__ Field
The __safeContent__
field is essential to Queryable Encryption. Do not modify
the contents of this field.
Learn More
To learn how Queryable Encryption works, see Fundamentals.
To learn more about the topics mentioned in this guide, see the following links:
Learn more about Queryable Encryption components on the Reference page.
Learn how Customer Master Keys and Data Encryption Keys work on the Keys and Key Vaults page.
See how KMS Providers manage your Queryable Encryption keys on the KMS Providers page.