Connect Liquibase to Oracle Database using Microsoft Entra ID

Last updated: March 24, 2026

This procedure configures Liquibase to authenticate to Oracle Database for Azure (DB@Azure) using OAuth2 tokens issued by Microsoft Entra ID. Authentication is handled by the ojdbc-provider-azure library—no username or password is stored in configuration files. Requires Oracle JDBC 21.x or later (ojdbc11.jar) and a connection over TCPS (port 2484). The Oracle Wallet holds the server’s TLS trust anchor only.

Before you begin

Install Liquibase
Ensure Java is installed.
Install Oracle Client Tools (included with Oracle Database, Oracle Instant Client, or Oracle Database Client) to obtain the orapki utility used in this procedure.
Obtain from your Azure/Oracle DBA: the Oracle DB@Azure TCPS hostname, the server certificate DN, and the Entra ID tenant ID and client ID for your service principal (or confirm that a managed identity is assigned to the compute resource).
Ask your Oracle DBA to create an external database user mapped to your service principal’s client ID or managed identity:
CREATE USER "<CLIENT_ID_OR_MANAGED_IDENTITY>" IDENTIFIED EXTERNALLY AS 'APP_AZURE'; GRANT CREATE SESSION TO "<CLIENT_ID_OR_MANAGED_IDENTITY>";

Procedure

Download required JARs

All JARs are available from Maven Central. Replace 21.13.0.0 with the latest 21.x release.

Download the following JARs and place them in your lib/ directory.

ojdbc11.jar — available from the Oracle JDBC Downloads page or Maven Central
ojdbc-provider-azure.jar — available from Maven Central
oraclepki.jar, osdt_core.jar, osdt_cert.jar — available from the Oracle JDBC Downloads page, required for TCPS only

mkdir -p lib

# Required for all configurations
wget -P lib "https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc11/21.13.0.0/ojdbc11-21.13.0.0.jar"
wget -P lib "https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc-provider-azure/21.13.0.0/ojdbc-provider-azure-21.13.0.0.jar"

# Required for TCPS only
wget -P lib "https://repo1.maven.org/maven2/com/oracle/database/security/oraclepki/21.13.0.0/oraclepki-21.13.0.0.jar"
wget -P lib "https://repo1.maven.org/maven2/com/oracle/database/security/osdt_core/21.13.0.0/osdt_core-21.13.0.0.jar"
wget -P lib "https://repo1.maven.org/maven2/com/oracle/database/security/osdt_cert/21.13.0.0/osdt_cert-21.13.0.0.jar"

mkdir -p lib

# Required for all configurations
curl -L -o lib/ojdbc11.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc11/21.13.0.0/ojdbc11-21.13.0.0.jar"
curl -L -o lib/ojdbc-provider-azure.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc-provider-azure/21.13.0.0/ojdbc-provider-azure-21.13.0.0.jar"

# Required for TCPS only
curl -L -o lib/oraclepki.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/oraclepki/21.13.0.0/oraclepki-21.13.0.0.jar"
curl -L -o lib/osdt_core.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/osdt_core/21.13.0.0/osdt_core-21.13.0.0.jar"
curl -L -o lib/osdt_cert.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/osdt_cert/21.13.0.0/osdt_cert-21.13.0.0.jar"

Download the following JARs and place them in your lib/ directory.

ojdbc11.jar — available from the Oracle JDBC Downloads page or Maven Central
ojdbc-provider-azure.jar — available from Maven Central
oraclepki.jar, osdt_core.jar, osdt_cert.jar — available from the Oracle JDBC Downloads page, required for TCPS only

mkdir -p lib

# Required for all configurations
wget -P lib "https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc11/21.13.0.0/ojdbc11-21.13.0.0.jar"
wget -P lib "https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc-provider-azure/21.13.0.0/ojdbc-provider-azure-21.13.0.0.jar"

# Required for TCPS only
wget -P lib "https://repo1.maven.org/maven2/com/oracle/database/security/oraclepki/21.13.0.0/oraclepki-21.13.0.0.jar"
wget -P lib "https://repo1.maven.org/maven2/com/oracle/database/security/osdt_core/21.13.0.0/osdt_core-21.13.0.0.jar"
wget -P lib "https://repo1.maven.org/maven2/com/oracle/database/security/osdt_cert/21.13.0.0/osdt_cert-21.13.0.0.jar"

mkdir -p lib

# Required for all configurations
curl -L -o lib/ojdbc11.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc11/21.13.0.0/ojdbc11-21.13.0.0.jar"
curl -L -o lib/ojdbc-provider-azure.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc-provider-azure/21.13.0.0/ojdbc-provider-azure-21.13.0.0.jar"

# Required for TCPS only
curl -L -o lib/oraclepki.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/oraclepki/21.13.0.0/oraclepki-21.13.0.0.jar"
curl -L -o lib/osdt_core.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/osdt_core/21.13.0.0/osdt_core-21.13.0.0.jar"
curl -L -o lib/osdt_cert.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/osdt_cert/21.13.0.0/osdt_cert-21.13.0.0.jar"

Create Oracle Wallet for TCPS

Download the wallet zip from the Oracle Cloud console.

Be sure to:

Replace ~/oracle-wallet with the directory where you want to place the wallet files.

# Azure Portal → Oracle Database@Azure → DB Connection → Download Wallet
# or: OCI Console → Autonomous Database → DB Connection → Download Wallet

mkdir -p ~/oracle-wallet
unzip wallet.zip -d ~/oracle-wallet

Create tnsnames.ora

If you downloaded the wallet zip in Step 2, tnsnames.ora is already included — skip this step or use it as a reference.

Otherwise, create tnsnames.ora in your wallet directory. The hostname, port, service name, and SSL DN come from Azure Portal → Oracle Database@Azure → Connection Strings.

Be sure to:

Replace ORACLE_AZURE with your TNS alias. The default alias in the downloaded wallet zip is ORACLE_AZURE
Replace your_hostname with your Oracle Database@Azure hostname
Replace your_port with your TCPS port. Usually, 2484
Replace your_service_name with your service name
Replace your_ssl_cert_dn with your server certificate's distinguished name

ORACLE_AZURE =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCPS)(HOST = your_hostname)(PORT = your_port))
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = your_service_name)
    )
    (SECURITY =
      (SSL_SERVER_CERT_DN = "your_ssl_cert_dn")
    )
  )

Create sqlnet.ora

If you downloaded the wallet zip in Step 2, sqlnet.ora is already included — skip this step or use it as a reference.

Otherwise, create sqlnet.ora in your wallet directory.

NAMES.DIRECTORY_PATH = (TNSNAMES, EZCONNECT)
SSL_CLIENT_AUTHENTICATION = FALSE
SSL_SERVER_DN_MATCH = ON
DISABLE_OOB = TRUE

Configure JDBC properties

Create ojdbc.properties in your wallet directory. Uncomment one authentication mode.

Be sure to:

Replace your_wallet_dir with the absolute path to your wallet directory. For example, /home/user/oracle-wallet, /Users/name/oracle-wallet
Replace your_tenant_id with your Entra ID tenant ID (service principal and interactive browser modes only).
Replace your_client_id with your service principal client ID or managed identity client ID.
Replace your_client_secret with your service principal client secret (service principal mode only).

# ── Mode A: Service Principal (recommended for CI/CD)
oracle.jdbc.provider.tokenAuthentication=ojdbc-azure-service-principal
oracle.jdbc.provider.azure.tenantId=your_tenant_id
oracle.jdbc.provider.azure.clientId=your_client_id
oracle.jdbc.provider.azure.clientSecret=your_client_secret

# ── Mode B: System Managed Identity (no credentials needed)
# oracle.jdbc.provider.tokenAuthentication=ojdbc-azure-managedidentity

# ── Mode C: User-Assigned Managed Identity
# oracle.jdbc.provider.tokenAuthentication=ojdbc-azure-managedidentity
# oracle.jdbc.provider.azure.clientId=your_client_id

# ── Mode D: Interactive browser (developer laptops)
# oracle.jdbc.provider.tokenAuthentication=ojdbc-azure-interactive
# oracle.jdbc.provider.azure.tenantId=your_tenant_id
# oracle.jdbc.provider.azure.clientId=your_client_id

# TNS resolution and wallet (points to the unzipped wallet directory)
oracle.net.tns_admin=your_wallet_dir
oracle.net.wallet_location=(SOURCE=(METHOD=FILE)(METHOD_DATA=(DIRECTORY=your_wallet_dir)))

Configure Liquibase

Create or update liquibase.properties. Omit username and password. Entra ID provides the token.

Be sure to:

Replace ORACLE_AZURE with your TNS alias from tnsnames.ora. The default alias in the downloaded wallet zip is ORACLE_AZURE
Include both JARs on the classpath

url=jdbc:oracle:thin:/@ORACLE_AZURE
driver=oracle.jdbc.OracleDriver
changeLogFile=changelog.xml
classpath=lib/ojdbc11.jar:lib/ojdbc-provider-azure.jar

Set environment variables

Set the following environment variables before running Liquibase.

export TNS_ADMIN=~/oracle-wallet
export LIQUIBASE_ORACLE_DISABLE_OOB=true

Test your connection

Run Liquibase against your Entra ID-configured database.

# Check connection and pending changesets
liquibase --defaults-file=liquibase.properties status

# Apply all pending changesets
liquibase --defaults-file=liquibase.properties update

# Roll back last 1 changeset
liquibase --defaults-file=liquibase.properties rollback-count 1