Docs Menu

Docs Home → Develop Applications → MongoDB Manual

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 Document with Encrypted Fields
  • 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 documents with encrypted fields 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

1

Register your Application with Azure

1

Log in to Azure.

2

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.

2

Create the Customer Master Key

1

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.

2

Grant Permissions

Grant your client application wrap and unwrap permissions to the key.

Create the Application

1

Create a Unique Index on your Key Vault collection

Create a unique index on the keyAltNames field in your encryption.__keyVault namespace.

Select the tab corresponding to your preferred MongoDB driver:

2

Create your Data Encryption Keys and Encrypted Collection

1

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:

2

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.

3

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 is in the encryption.__keyVault namespace. Ensure that the database user your application uses to connect to MongoDB has ReadWrite permissions on this namespace.

4

Create Your Encrypted Collection

Use a Queryable Encryption enabled MongoClient intance to specify what fields you must encrypt and create your encrypted collection:

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

3

Configure your MongoClient for Encrypted Reads and Writes

Tip

Follow the remaining steps in this tutorial in a separate file from the one created in the previous steps.

1

Specify the Key Vault Collection Namespace

Specify encryption.__keyVault as the Key Vault collection namespace.

2

Specify your Azure Credentials

Specify the azure KMS provider and your Azure credentials:

3

Create an Encrypted Fields Map For Your Collection

4

Specify the Location of the Automatic Encryption Shared Library

Tip

Learn More

To learn more about the Automatic Encryption Shared Library, see the Automatic Encryption Shared Library page.

5

Create the MongoClient

Instantiate a MongoDB client object with the following automatic encryption settings that use the variables declared in the previous steps:

4

Insert a Document with Encrypted Fields

Use your Queryable Encryption enabled MongoClient instance to insert a document with encrypted fields 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

5

Retrieve Your Document with Encrypted Fields

Retrieve the document with encrypted fields 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.

←  Use Automatic Queryable Encryption with AWSUse Automatic Queryable Encryption with GCP →

On this page