Connect Liquibase MongoDB Secure with MongoDB Atlas

Last updated: November 18, 2025

Verified database versions

  • 8

  • 7

  • 6

  • 5

Before you begin

Note: mongosh is required to use Liquibase MongoDB Secure features, including the <mongo> and <mongosh> Change types and Mongo changelogs. These features allow you to run native JavaScript-based MongoDB changes. To use mongosh, it must be made accessible to Liquibase. We recommend that you make sure mongosh is available in your system PATH. If not, its location must be manually specified using the liquibase.mongosh.conf file. While mongosh is not required; without it, your functionality will be limited, and you won’t be able to use advanced MongoDB Secure features.

Procedure

1

(Maven users only) Configure Maven

If you're running Liquibase using the Maven plugin using mvn liquibase:update installing the extension with Maven ensures the right files are available and everything works together automatically. You can manage these extensions by adding them as dependencies in your project’s pom.xml file. When configured this way, Maven automatically downloads the specified JAR files from Maven Central during the build process.

2

Configure your connection

Choose an authentication method. This guide includes SCRAM (username/password), X.509 Certificate, AWS IAM, and OIDC.

Users may prefer the SCRAM method because of simplicity and increased security. The server stores passwords in a iterated hash format. This makes offline attacks harder, and decreases the impact of database breaches.

MongoDB Atlas configuration

  1. Create a Database User for Your Cluster

  2. Add or change Database User role to Atlas admin (Security > Database Access > Edit > Database User Privileges > Built-in Role)

  3. Note: Learn more about database users and built in roles here: Modify Database Users and Built In Roles.

Liquibase configuration

Once MongoDB Atlas is configured, you must then configure Liquibase.

  1. Add the liquibase.command.url property to the properties file, environment variables, or command line options in the following format:

  2. liquibase.command.url: mongodb+srv://cluster0.abcd123.mongodb.net/lbcat

  3. Add the liquibase.command.username and liquibase.command.password properties to the same configuration file, environment variables, or command line. These are the same credentials entered in Step 1 above titled: Create a Database User for Your Cluster.

This authorization mechanism allows system administrators to configure certificates for users within their organization. It also does not require you to memorize a password.

MongoDB Atlas configuration

1. Add Database Users for X.509 Certificates.

2. Add or change Database User role to Atlas admin.

(Security > Database Access > Edit > Database User Privileges > Built-in Role)

Note: Learn more about database users and built in roles here: Modify Database Users and Built In Roles.

Java configuration

Java Truststore is a Java mechanism that stores Certificates. It is used only by Java applications. The command below creates the CA.p12 Truststore file that contains the certificate using the CLI.

openssl pkcs12 -export -in X509-cert-137983036943191321.pem -name mongoAtlas -caname CA -out CA.p12 -passout pass:qwerty123

The CA.p12 Truststore file that contains the certificate can now be used by Liquibase to connect to MongoDB Atlas.

Liquibase configuration

Once MongoDB Atlas and Java are configured, you must then configure Liquibase.

Note: Your connection to MongoDB Atlas must be TLS and SSL encrypted.

1. Add the liquibase.command.url property to the properties file, environment variables, or command line options in the following format:

liquibase.command.url: mongodb+srv://cluster0.xtsabc123.mongodb.net/lbcat?authSource=%24external&authMechanism=MONGODB-X509&&tlsCertificateKeyFile=X509-cert-137983036943191321.pem

2. Add the following to the environment variables before running Liquibase commands.

JAVA_OPTS="-Djavax.net.ssl.keyStoreType=pkcs12 -Djavax.net.ssl.keyStore=CA.p12 -Djavax.net.ssl.keyStorePassword=qwerty123"

AWS lets you configure credentials using IAM (Identity and Access Management) roles, which can offer better security and simplify your credential management process.

MongoDB Atlas configuration

Follow the steps in the MongoDB documentation Set Up Authentication with AWS IAM:

  1. Set Up Authentication with AWS IAM Roles

  2. Grant Database Access to AWS IAM Roles

  3. Connect to Atlas Cluster Using AWS IAM

Liquibase configuration

Configure your properties file, environment variables, or command line options in the following format:

liquibase.command.url=mongodb+srv://<atlas-host-name>/test?authSource=%24external&authMechanism=MONGODB-AWS liquibase.command.username=<AWS_ACCESS_KEY_ID> # optional liquibase.command.password=<AWS_SECRET_ACCESS_KEY> # optional

OIDC is a type of federated authentication that provides a secure, scalable, and user-friendly identity solution with Single Sign-On (SSO) capabilities and seamless integration across diverse applications.

In the Liquibase Secure MongoDB extension version 1.5.0 and later, you can authenticate using OIDC through Microsoft Entra ID (formerly called Azure Active Directory) in an Azure environment. For more information, see MongoDB: Enterprise Authentication Mechanisms.

Prerequisites

  • A running MongoDB Atlas cluster (version 7 or newer)

  • An active Azure subscription with administrative access

  • Java Development Kit (JDK) 8 or later installed

  • MongoDB Java driver version 5.2.0 or later, which includes OIDC support

Microsoft Azure configuration

  1. Register your application in Azure Entra ID from the Azure portal. For more information, see Quickstart: Register an application with the Microsoft identity platform.

  2. Retrieve your application ID URI so that you can provide it to Liquibase later in this tutorial. For more information, seeQuickstart: Configure an application to expose a web API.

  3. Configure a user-managed or system-managed identity. Retrieve the Object (principal) ID so that you can provide it to MongoDB Atlas later in this tutorial. For more information, seeConfigure managed identities on Azure virtual machines (VMs).

  4. (Optional) If you have a user-managed identity, retrieve your Client ID so that you can provide it to Liquibase later in this tutorial. This is the unique identifier of your user-assigned managed identity (it is different than your overall application ID). For more information, see Manage user-assigned managed identities.

MongoDB Atlas configuration

  1. Enable Workforce Identity Provider for your organization. Follow the steps in § Configure Workforce Identity Federation Authentication.

  2. Register your Azure identity by adding it to a new database user in MongoDB Atlas. Follow the steps in § Add a Database User using Workforce Authentication. While you configure the database user, ensure that:

  • For "Select Identity Provider," select "Liquibase OIDC config for Applications."

  • For "User Identifier," specify the Object ID you retrieved earlier (not the application ID).

Liquibase configuration

Configure your properties file, environment variables, or command line options in the following format:

url=mongodb+srv://dat-18611.cn9br.mongodb.net/demo liquibase.mongodb.oidc.authenticationMechanism=MONGODB-OIDC liquibase.mongodb.oidc.environment=azure liquibase.mongodb.oidc.oidcApplicationIDURI=api://8d719796-c744-4352-aab9-47a52c363907 liquibase.mongodb.oidc.oidcClientID=<optional-user-assigned-client-id>

For more information about MongoDB Atlas OIDC parameters, see Liquibase Parameters for MongoDB.

Warning: In the MongoDB extension version 1.5.0, Liquibase MongoDB Atlas OIDC authentication is incompatible with the mongosh native executor. If you want to use OIDC authentication in this version, you must use a YAML, JSON, or XML changelog. You cannot use the mongo and mongoFile Change types since they require mongosh. When you copy the following examples into your changelog, ensure that you remove runWith from each changeset.

3

Test your connection

1. Create a text file called changelog (.sql, .yaml, .json, or .xml) in your project directory and add a changeset.

Native MongoDB Shell (mongosh) scripts in MongoDB Query Language (MQL): Let developers use Liquibase without modifying existing MQL scripts, which may be JavaScript (.js) files.

Formatted Mongo changelogs (MongoDB Secure 1.3.0+): Add Liquibase changeset metadata to your MQL scripts to use features like rollback, contexts, labels, and the include and includeAll tags. These must be saved as .js files.

YAML, JSON, and XML modeled changelogs: Specify changes for Liquibase to deploy without the need for MQL scripts. However, you can still deploy MQL scripts in YAML, JSON, and XML changelogs by using the mongo and mongoFile Change Types. Using these Change Types requires you to specify mongosh as the value of the runWith attribute for all mongo and mongoFile changesets.

Note for XML: The Liquibase MongoDB Secure extension uses a unique mongodb-secure XML namespace and XSD files in the changelog header. However, the ext prefix used with other extensions is backwards-compatible:

db.createCollection('customers');

loading

loading

loading

loading

The preceding examples show only the mongo and mongoFile Change Types for Liquibase Secure. For a list of all Liquibase Secure and Liquibase Open Source Change Types for MongoDB, including Change Types that you can without the mongosh native executor, see Liquibase Change types for MongoDB.

2. Navigate to your project folder in the CLI and run the Liquibase status command to see whether the connection is successful:

liquibase status --username=test --password=test --changelog-file=<changelog.xml>

Note: You can specify arguments in the CLI or keep them in the Liquibase properties file.

If your connection is successful, you'll see a message like this:

4 changesets have not been applied to <your_connection_url> Liquibase command 'status' was executed successfully.

3. Inspect the deployment SQL with the update-sql command

liquibase update-sql --changelog-file=<changelog.xml>

If the SQL that Liquibase generates isn't what you expect, you should review your changelog file and make any necessary adjustments.

4. Then execute these changes to your database with the update command:

liquibase update --changelog-file=<changelog.xml>

If your update is successful, Liquibase runs each changeset and displays a summary message ending with:

Liquibase: Update has been successful. Liquibase command 'update' was executed successfully.

5. From a database UI tool, ensure that your database contains the test_table object you added along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table.