For AI agents: a documentation index is available at https://www.mongodb.com/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.

Use Automatic Queryable Encryption with Azure

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 Encryption 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 Install a Queryable Encryption Compatible Driver and Dependencies 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

1

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 need these credentials to construct your kmsProviders object later in this tutorial. You can also authenticate by using an access token or automatic credential fetching. To learn about all available credential forms for Azure, see kmsProviders Object.

2

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.

Grant Permissions

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

Create the Application

1

Assign Your Application Variables

The code samples in this tutorial use the following variables to perform the Queryable Encryption workflow:

  • kmsProviderName - The KMS you're using to store your Customer Master Key. Set this variable to "azure" for this tutorial.

  • uri - Your MongoDB deployment connection URI. Set your connection URI in the MONGODB_URI environment variable or replace the value directly.

  • keyVaultDatabaseName - The database in MongoDB where your data encryption keys (DEKs) will be stored. Set this variable to "encryption".

  • keyVaultCollectionName - The collection in MongoDB where your DEKs will be stored. Set this variable to "__keyVault".

  • keyVaultNamespace - The namespace in MongoDB where your DEKs will be stored. Set this variable to the values of the keyVaultDatabaseName and keyVaultCollectionName variables, separated by a period.

  • encryptedDatabaseName - The database in MongoDB where your encrypted data will be stored. Set this variable to "medicalRecords".

  • encryptedCollectionName - The collection in MongoDB where your encrypted data will be stored. Set this variable to "patients".

You can declare these variables by using the following code:

// KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local"const kmsProviderName = "<Your KMS Provider Name>";const uri = process.env.MONGODB_URI; // Your connection URIconst keyVaultDatabaseName = "encryption";const keyVaultCollectionName = "__keyVault";const keyVaultNamespace = `${keyVaultDatabaseName}.${keyVaultCollectionName}`;const encryptedDatabaseName = "medicalRecords";const encryptedCollectionName = "patients";

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.

Tip

Environment Variables

The sample code in this tutorial references environment variables that you need to set. Alternatively, you can replace the values directly in the code.

To learn how you can setup these environment variables, see the README.md file included in the sample application on GitHub.

2

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.

kmsProviderCredentials = {  azure: {    tenantId: process.env["AZURE_TENANT_ID"], // Your Azure tenant ID    clientId: process.env["AZURE_CLIENT_ID"], // Your Azure client ID    clientSecret: process.env["AZURE_CLIENT_SECRET"], // Your Azure client secret  },};
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.

customerMasterKeyCredentials = {  keyVaultEndpoint: process.env["AZURE_KEY_VAULT_ENDPOINT"], // Your Azure Key Vault Endpoint  keyName: process.env["AZURE_KEY_NAME"], // Your Azure Key Name};
Set Your Automatic Encryption Options

Create an autoEncryptionOptions object that contains the following options:

  • The namespace of your Key Vault collection

  • The kmsProviderCredentials object, which contains your Azure KMS credentials

const autoEncryptionOptions = {  keyVaultNamespace: keyVaultNamespace,  kmsProviders: kmsProviderCredentials,};

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.

Create a Client to Set Up an Encrypted Collection

To create a client used to encrypt and decrypt data in your collection, instantiate a new MongoClient by using your connection URI and your automatic encryption options.

const encryptedClient = Mongo(uri, autoEncryptionOptions);
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:

const encryptedFieldsMap = {  encryptedFields: {    fields: [      {        path: "patientRecord.ssn",        bsonType: "string",        queries: { queryType: "equality" },      },      {        path: "patientRecord.billing",        bsonType: "object",      },    ],  },};

Note

In the previous code sample, both the "ssn" and "billing" fields are encrypted, but only the "ssn" field can be queried.

Create the Collection

Instantiate ClientEncryption to access the API for the encryption helper methods.

const clientEncryption = encryptedClient.getClientEncryption()

Create your encrypted collection by using the encryption helper method accessed through the ClientEncryption class. This method automatically generates data encryption keys for your encrypted fields and creates the encrypted collection:

await clientEncryption.createEncryptedCollection(  encryptedDatabaseName,  encryptedCollectionName,  {    provider: kmsProviderName,    createCollectionOptions: encryptedFieldsMap,    masterKey: customerMasterKeyCredentials,  });
3

Insert a Document with Encrypted Fields

Create a sample document that describes a patient's personal information. Use the encrypted client to insert it into the patients collection, as shown in the following example:

const patientDocument = {  patientName: "Jon Doe",  patientId: 12345678,  patientRecord: {    ssn: "987-65-4320",    billing: {      type: "Visa",      number: "4111111111111111",    },  },};
const encryptedCollection = encryptedClient.getDB(encryptedDatabaseName).getCollection(encryptedCollectionName);
const insertResult = await encryptedCollection.insertOne(patientDocument);
4

Query on an Encrypted Field

The following code sample executes a find query on an encrypted field and prints the decrypted data:

const findResult = await encryptedCollection.findOne({  "patientRecord.ssn": "987-65-4320",});console.log(findResult);

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 Queryable Encryption 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 Encryption Keys and Key Vaults page.

  • See how KMS Providers manage your Queryable Encryption keys on the KMS Providers page.

Back
Use AWS
Next
Use GCP
Select your language
Rate this page

On this page