CSFLE-Specific MongoClient Options

On this page

Overview

AutoEncryptionOpts
Example

Queryable Encryption is generally available (GA) in MongoDB 7.0. To learn more, 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 Key Vault Collections.
`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 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 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 for Automatic Encryption

KMS Providers