Docs Menu

Docs HomeMongoDB Manual

Use Automatic Queryable Encryption with GCP

On this page

  • Overview
  • Before You Get Started
  • Set Up the KMS
  • Register a GCP Service Account
  • Create a GCP Customer Master Key
  • Create the Application
  • Assign Your Application Variables
  • Create your Encrypted Collection
  • Insert a Document with Encrypted Fields
  • Query on an Encrypted Field
  • Learn More

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 Google Cloud Key Management Service for key management.

After you complete the steps in this guide, you should have:

  • A CMK managed by Google Cloud Key Management Service

  • A working client application that inserts documents with encrypted fields using your CMK


Customer Master Keys

To learn more about the Customer Master Key, read the Keys and Key Vaults documentation.

To complete and run the code in this guide, you need to set up your development environment as shown in the Installation Requirements page.


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 file that you can use to learn how to set up your environment and run the application.


To create a service account on Google Cloud, follow the Creating a service account guide in Google's official documentation.


To add a service account key on Google Cloud, follow the Managing service account keys guide in Google's official documentation.


Create a key ring and a symmetric key by following the Create a key guide from Google's official documentation.

This key is your Customer Master Key (CMK).

Record the following details of your CMK for use in a future step of this tutorial.

Identifier for the CMK.
Identifier for the group of keys your key belongs to.
The version of the named key.
Region specified for your key.
The host and optional port of the Google Cloud KMS. The default value is

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


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 a variable containing your Google Cloud Key Management Service credentials with the following structure:


Create a variable containing your Customer Master Key credentials with the following structure. Use the credentials you recorded in the Create a new Customer Master Key step of this tutorial.



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.


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.


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:


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


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


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"


Do not Modify the __safeContent__ Field

The __safeContent__ field is essential to Queryable Encryption. Do not modify the contents of this field.

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 AzureUse Automatic Queryable Encryption with KMIP →
Share Feedback
© 2023 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2023 MongoDB, Inc.