Use Automatic Client-Side Field Level 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 a New Data Encryption Key
Configure the MongoClient
Insert a Document with Encrypted Fields
Retrieve Your Encrypted Document
Learn More

Overview

This guide shows you how to build a Client-Side Field Level Encryption (CSFLE)-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.

Throughout this guide, code examples use placeholder text. Before you run the examples, substitute your own values for these placeholders.

For example:

dek_id := "<Your Base64 DEK ID>"

You would replace everything between quotes with your DEK ID.

dek_id := "abc123"

Select the programming language for which you want to see code examples for from the Select your language dropdown menu on the right side of the page.

Tip

See: Full Application

To view the complete runnable application code for this tutorial, go to the following 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.

Grant Permissions

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

Create the Application

Create a Unique Index on your Key Vault collection

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

Select the tab corresponding to your preferred MongoDB driver:

Create a New Data Encryption Key

Add your Azure Key Vault Credentials

Add the service account credentials to your CSFLE-enabled client code.

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.

Generate your Data Encryption Key

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 the MongoClient

Specify the Key Vault Collection Namespace

Specify encryption.__keyVault as the Key Vault collection namespace.

Specify your Azure Credentials

Specify the azure KMS provider and your Azure credentials:

Create an Encryption Schema For Your Collection

Tip

Add Your Data Encryption Key Base64 ID

Make sure to update the following code to include your Base64 DEK ID. You received this value in the Generate your Data Encryption Key step of this guide.

Specify the Location of the Encryption Binary

Configure the client to spawn the mongocryptd process by specifying the path to the binary using the following configuration options:

Create the MongoClient

Instantiate a MongoDB client object with the following automatic encryption settings:

Insert a Document with Encrypted Fields

Use your CSFLE-enabled MongoClient instance to insert an encrypted document into the medicalRecords.patients namespace using the following code snippet:

When you insert a document, your CSFLE-enabled client encrypts the fields of your document such that it resembles the following:

{
  "_id": { "$oid": "<_id of your document>" },
  "name": "Jon Doe",
  "ssn": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "bloodType": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "medicalRecords": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "insurance": {
    "provider": "MaestCare",
    "policyNumber": {
      "$binary": "<cipher-text>",
      "$type": "6"
    }
  }
}

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 CSFLE, the following code snippet queries for your document with a client configured for automatic CSFLE as well as a client that is not configured for automatic CSFLE.

The output of the preceding code snippet should look like this:

Finding a document with regular (non-encrypted) client.
{
  _id: new ObjectId("629a452e0861b3130887103a"),
  name: 'Jon Doe',
  ssn: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e7910c20697e5f4fa95710aafc9153f0a3dc769c8a132a604b468732ff1f4d8349ded3244b59cbfb41444a210f28b21ea1b6c737508d9d30e8baa30c1d8070c4d5e26", "hex"), 6),
  bloodType: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79022e238536dfd8caadb4d7751ac940e0f195addd7e5c67b61022d02faa90283ab69e02303c7e4001d1996128428bf037dea8bbf59fbb20c583cbcff2bf3e2519b4", "hex"), 6),
  'key-id': 'demo-data-key',
  medicalRecords: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e790405163a3207cff175455106f57eef14e5610c49a99bcbd14a7db9c5284e45e3ee30c149354015f941440bf54725d6492fb3b8704bc7c411cff6c868e4e13c58233c3d5ed9593eca4e4d027d76d3705b6d1f3b3c9e2ceee195fd944b553eb27eee69e5e67c338f146f8445995664980bf0", "hex"), 6),
  insurance: {
    policyNumber: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79108decd85c05be3fec099e015f9d26d9234605dc959cc1a19b63072f7ffda99db38c7b487de0572a03b2139ac3ee163bcc40c8508f366ce92a5dd36e38b3c742f7", "hex"), 6),
    provider: 'MaestCare'
  }
}
Finding a document with encrypted client, searching on an encrypted field
{
  _id: new ObjectId("629a452e0861b3130887103a"),
  name: 'Jon Doe',
  ssn: 241014209,
  bloodType: 'AB+',
  'key-id': 'demo-data-key',
  medicalRecords: [ { weight: 180, bloodPressure: '120/80' } ],
  insurance: { policyNumber: 123142, provider: 'MaestCare' }
}

Tip

See: Complete Code

Learn More

To learn how CSFLE works, see Fundamentals.

To learn more about the topics mentioned in this guide, see the following links:

Learn more about CSFLE 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 CSFLE keys on the CSFLE KMS Providers page.

← Use Automatic Client-Side Field Level Encryption with AWS Use Automatic Client-Side Field Level Encryption with GCP →