Use Automatic Queryable Encryption with Azure
On this page
- Overview
- Before You Get Started
- Set Up the KMS
- Register your Application with Azure
- Create the Customer Master Key
- Create the Application
- Create a Unique Index on your Key Vault collection
- Create your Data Encryption Keys and Encrypted Collection
- Configure your MongoClient for Encrypted Reads and Writes
- Insert a Document with Encrypted Fields
- Retrieve Your Encrypted Document
- Learn More
Overview
This guide shows you how to build a Queryable Encryption enabled application using Azure Key Vault.
After you complete the steps in this guide, you should have:
A Customer Master Key hosted on an Azure Key Vault instance.
A working client application that inserts encrypted documents using your Customer Master Key.
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 the application you make in this guide, select the tab corresponding to your programming language and follow the provided link:
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.
Important
Record your Credentials
Ensure you record the following credentials:
tenant id
client id
client secret
You will need them to construct your kmsProviders
object
later in this tutorial.
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
Create your Data Encryption Keys and Encrypted Collection
Add your Azure Key Vault Credentials
Add the service account credentials to your Queryable Encryption enabled client code.
Select the tab corresponding to your preferred MongoDB driver:
Tip
You recorded your Azure Key Vault credentials in the in the Register Your Applitcation with Azure step of this guide.
Tip
Learn More
To learn more about the KMS provider object for Azure Key Vault, see Azure Key Vault.
Add Your Key Information
Update the following code to specify your Customer Master Key:
Tip
You recorded your Customer Master Key's ARN and Region in the Create a Customer Master Key step of this guide.
Create your Data Encryption Keys
Construct a client with your MongoDB connection string and Key Vault collection namespace, and create the Data Encryption Keys:
Note
Key Vault Collection Namespace Permissions
The Key Vault collection in this guide is the __keyVault
collection in the encryption
database.
Ensure that the database user your application uses to connect
to MongoDB has ReadWrite
permissions on the encryption.__keyVault
namespace.
Tip
Learn More
To view a diagram showing how your client application creates your Data Encryption Key when using an Azure Key Vault, see Architecture.
To learn more about the options for creating a Data Encryption Key encrypted with a Customer Master Key hosted in Azure Key Vault, see kmsProviders Object and dataKeyOpts Object.
Tip
See: Complete Code
Configure your MongoClient for Encrypted Reads and Writes
Specify the Location of the Automatic Encryption Shared Library
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.
Insert a Document with Encrypted Fields
Use your Queryable Encryption enabled
MongoClient
instance to insert an encrypted document into the
medicalRecords.patients
namespace using the following code
snippet:
When you insert a document, your Queryable Encryption enabled client encrypts the fields of your document such that it resembles the following:
{ "_id": { "$oid": "<_id value>" }, "firstName": "Jon", "lastName": "Doe", "patientId": { "$binary": { "base64": "<ciphertext>", "subType": "06" } }, "address": "157 Electric Ave.", "patientRecord": { "ssn": { "$binary": { "base64": "<ciphertext>", "subType": "06" } }, "billing": { "$binary": { "base64": "<ciphertext>", "subType": "06" } } }, "medications": { "$binary": { "base64": "<ciphertext>", "subType": "06" } }, "__safeContent__": [ { "$binary": { "base64": "<ciphertext>", "subType": "00" } }, { "$binary": { "base64": "<ciphertext>", "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.
Tip
See: Complete Code
Retrieve Your Encrypted Document
Retrieve the encrypted document you inserted in the Insert a Document with Encrypted Fields step of this guide.
To show the functionality of Queryable Encryption, the following code snippet queries for your document with a client configured for automatic Queryable Encryption as well as a client that is not configured for automatic Queryable Encryption.
The output of the preceding code snippet should look like this:
Finding a document with regular (non-encrypted) client. { _id: new ObjectId("628eabeb37590e84ea742665"), firstName: 'Jon', lastName: 'Doe', patientId: new Binary(Buffer.from("0798810acc0f4f46c9a76883cee80fca12102e9ddcbcdae46a821fa108a8155a850f2d0919475b6531ada68973d436a199b537a05a98a708c36d2bfec4979d59cbe66878865ce19e392d3e4789d309bdacc336e32efcc851806ae0a41b355288c10d01e39147e1c40d919c41913a0c9d2d3fad0d0d1d2873c4fc82c6c22f27b517df5f3131b331b96ed16a7c5cf89e09082a2d898c2dcd73da91d08760ba74a70077b2d0fdbbe1eea75655a19fcc397812325ad40b102cbd16b8d36b22e11e3f93404f24a8ff68cfdec3c22b0e787cb30078a5227b2a", "hex"), 6), address: '157 Electric Ave.', patientRecord: { ssn: new Binary(Buffer.from("07e8b69630c32f4a00a542af768f8abcf50223edd812ff20b0ecb046ee1a9f5a0eef8d85d99cd26076411129942752516ee605c55aadce73f3d44d81ea6ddbbb8134b108a9deb40d8cab9cb4f08ef210ab0c9d2ea4347f9d235b861baf29751e60abcf059eb5c120305bd5ac05a4e07ac8ccfa6d37283f4cdbfeb7a8accb65b71857d486b5cf55e354d6a95e287d9e2dd65f3f9d9c4c9d0bdb1f26c4bd549d7be77db81796be293e08b2223bac67b212423c4e06568578b5bd7a3c33cedc1b291bcda0b27e005144d344563711a489f24b8e9b65bbb721d3a0e9d9b227a0cec0cbad", "hex"), 6), billing: new Binary(Buffer.from("06808ae69d4caa49cf90bb688f386f097f03f870a7b8fcebb1980c9ee5488b1f0f68558fc2163adcd92d00ea5f349f56ed34e7b391f54c48ed2760b4bde73022fc818dc7486a4e046b92ce9c82e00333c7779d9d6bb476713a20632b593b7de54812662cfc4d174d05451d3f4195514e12edba", "hex"), 6) }, medications: new Binary(Buffer.from("06665ec15d38254dc4aa16da856789d33404f27bfea53e0d2fa4deaff166989ab33f469644d89c29112d33b41dbe54ec2d89c43f3de52cdc5d454e8694046216f533614fa7b42b7c5406d6518f7ed8f9e3ce52fda6c8b2146d0f8cc51e21a3467183697e1735a9f60c18e173c1916101", "hex"), 6), __safeContent__: [ new Binary(Buffer.from("3044b134ad0f7c8a90dab1e05bb8b296a8ede540796bd7403ab47693cdba1b26", "hex"), 0), new Binary(Buffer.from("a22ddf9a5657cdd56bef72febbba44371899e6486962a1c07d682082c4e65712", "hex"), 0) ] } Finding a document with encrypted client, searching on an encrypted field { _id: new ObjectId("628eaca1dcf9b63e2f43162d"), firstName: 'Jon', lastName: 'Doe', patientId: 12345678, address: '157 Electric Ave.', patientRecord: { ssn: '987-65-4320', billing: { type: 'Visa', number: '4111111111111111' } }, medications: [ 'Atorvastatin', 'Levothyroxine' ], __safeContent__: [ new Binary(Buffer.from("fbdc6cfe3b4659693650bfc60baced27dcb42b793efe09da0ded54d60a9d5a1f", "hex"), 0), new Binary(Buffer.from("0f92ff92bf904a858ef6fd5b1e508187f523e791f51d8b64596461b38ebb1791", "hex"), 0) ] }
Tip
See: Complete Code
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.