MongoClient Options for CSFLE

On this page

Overview

AutoEncryptionOpts
Example

MongoDB's Queryable Encryption feature is available (GA) in MongoDB 7.0 and later. To learn more about Queryable Encryption and compare its benefits with Client-Side Field Level Encryption, see Queryable Encryption.

Overview

View information about the Client-Side Field Level Encryption (CSFLE)-specific configuration options for MongoClient instances.

AutoEncryptionOpts

Pass an autoEncryptionOpts object to your MongoClient instance to specify CSFLE-specific options.

The following table describes the structure of an autoEncryptionOpts object:

Parameter	Type	Required	Description
`keyVaultClient`	`MongoClient`	No	A `MongoClient` instance configured to connect to the MongoDB instance hosting your Key Vault collection. If you omit the `keyVaultClient` option, the MongoDB instance specified to your `MongoClient` instance containing the `autoEncryptionOpts` configuration is used as the host of your Key Vault collection. To learn more about Key Vault collections, see Encryption Keys and Key Vaults.
`keyVaultNamespace`	String	Yes	The full namespace of the Key Vault collection.
`kmsProviders`	Object	Yes	The Key Management System (KMS) used by Client-Side Field Level Encryption for managing your Customer Master Keys (CMKs). To learn more about `kmsProviders` objects, see KMS Providers. To learn more about Customer Master Keys, see Encryption Keys and Key Vaults.
`tlsOptions`	Object	No	An object that maps Key Management System provider names to TLS configuration options. To learn more about TLS options see: TLS Options. To learn more about TLS see: TLS/SSL (Transport Encryption).
`schemaMap`	Object	No	An encryption schema. To learn how to construct an encryption schema, see Encryption Schemas. For complete documentation of encryption schemas, see CSFLE Encryption Schemas.
`bypassAutoEncryption`	Boolean	No	Specify `true` to bypass automatic Client-Side Field Level Encryption rules and perform explicit encryption. `bypassAutoEncryption` does not disable automatic decryption. To learn more about this option, see Automatic Decryption.

Example

To view a code-snippet demonstrating how to use autoEncryptionOpts to configure your MongoClient instance, select the tab corresponding to your driver:

var autoEncryptionOpts =
{
   "keyVaultNamespace" : "<database>.<collection>",
   "kmsProviders" : { ... },
   "schemaMap" : { ... }
}
cluster = Mongo(
  "<Your Connection String>",
  autoEncryptionOpts
);

Tip

Environment Variables

If possible, consider defining the credentials provided in kmsProviders as environment variables, and then passing them to mongosh using the --eval option. This minimizes the chances of credentials leaking into logs.

var clientSettings = MongoClientSettings.FromConnectionString(_connectionString);
var autoEncryptionOptions = new AutoEncryptionOptions(
    keyVaultNamespace: keyVaultNamespace,
    kmsProviders: kmsProviders,
    schemaMap: schemaMap,
    extraOptions: extraOptions);
clientSettings.AutoEncryptionOptions = autoEncryptionOptions;
var client = new MongoClient(clientSettings);

autoEncryptionOpts := options.AutoEncryption().
	SetKmsProviders(provider.Credentials()).
	SetKeyVaultNamespace(keyVaultNamespace).
	SetSchemaMap(schemaMap).
	SetExtraOptions(extraOptions)
client, err := mongo.Connect(context.TODO(), options.Client().ApplyURI(uri).SetAutoEncryptionOptions(autoEncryptionOpts))

MongoClientSettings clientSettings = MongoClientSettings.builder()
    .applyConnectionString(new ConnectionString("mongodb://localhost:27017"))
    .autoEncryptionSettings(AutoEncryptionSettings.builder()
        .keyVaultNamespace(keyVaultNamespace)
        .kmsProviders(kmsProviders)
        .schemaMap(schemaMap)
        .extraOptions(extraOptions)
        .build())
    .build();
MongoClient mongoClient = MongoClients.create(clientSettings);

const secureClient = new MongoClient(connectionString, {
  useNewUrlParser: true,
  useUnifiedTopology: true,
  monitorCommands: true,
  autoEncryption: {
    keyVaultNamespace,
    kmsProviders,
    schemaMap: patientSchema,
    extraOptions: extraOptions,
  },
});

fle_opts = AutoEncryptionOpts(
  kms_providers,
  key_vault_namespace,
  schema_map=patient_schema,
  **extra_options
)
client = MongoClient(connection_string, auto_encryption_opts=fle_opts)

Back

Supported Operations

Components