Connect Liquibase to Oracle Database with Kerberos Authentication

Last updated: March 24, 2026

This procedure configures Liquibase to authenticate to Oracle Database using Kerberos (GSSAPI) over a standard TCP connection. Kerberos authentication and TLS encryption are independent.

Before you begin

Important: Java 23 or earlier is required. Java 24 permanently removed the JVM API (Subject.getSubject) that Oracle JDBC depends on for Kerberos authentication (JEP 486).
Ask your Oracle DBA to configure the Oracle server’s sqlnet.ora for Kerberos, register the database service principal with the KDC, and provide you with a keytab file for the Liquibase service account. The server’s sqlnet.ora must include SQLNET.AUTHENTICATION_KERBEROS5_SERVICE = oracle; without this setting, connections fail with ORA-12641.
Ask your Oracle DBA to create an external database user mapped to the Kerberos principal:
CREATE USER liquibase_svc IDENTIFIED EXTERNALLY AS 'liquibase-svc@MYCOMPANY.COM'; GRANT CREATE SESSION TO liquibase_svc;
Ask your KDC administrator for: the Kerberos realm name, KDC hostname, and domain realm mapping.

Procedure

Download Oracle JDBC driver

All JARs are available from the Oracle JDBC Downloads page and Maven Central. Replace 21.13.0.0 with the latest 21.x release.

Download the following JARs from the Oracle JDBC Downloads page and place them in your lib/ directory.

ojdbc11.jar — required for all configurations
oraclepki.jar, osdt_core.jar, osdt_cert.jar — required for TCPS (Part B) only

# Required for all configurations
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/ojdbc11.jar

# Required for TCPS only (Part B — Add TLS encryption)
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/oraclepki.jar
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/osdt_core.jar
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/osdt_cert.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"

# Required for TCPS only (Part B — Add TLS encryption)
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 from the Oracle JDBC Downloads page and place them in your lib/ directory.

ojdbc11.jar — required for all configurations
oraclepki.jar, osdt_core.jar, osdt_cert.jar — required for TCPS (Part B) only

# Required for all configurations
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/ojdbc11.jar

# Required for TCPS only (Part B — Add TLS encryption)
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/oraclepki.jar
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/osdt_core.jar
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/osdt_cert.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"

# Required for TCPS only (Part B — Add TLS encryption)
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"

Configure Oracle server for Kerberos (ask your DBA)

Ask your Oracle DBA to add the following lines to $ORACLE_HOME/network/admin/sqlnet.ora on the Oracle DB server.

# Oracle server sqlnet.ora — add these lines for Kerberos support
SQLNET.AUTHENTICATION_SERVICES = (TCPS, NTS, BEQ, KERBEROS5)

# REQUIRED: tells Oracle which Kerberos service name prefix to use.
# Without this, Oracle cannot look up the service ticket and throws ORA-12641.
SQLNET.AUTHENTICATION_KERBEROS5_SERVICE = oracle

# Path to the Oracle server keytab (from the KDC admin)
SQLNET.KERBEROS5_KEYTAB = /etc/oracle/oracle.keytab

# Path to krb5.conf inside the Oracle DB server
SQLNET.KERBEROS5_CONF = /etc/krb5.conf

# Enable mutual authentication (recommended)
SQLNET.KERBEROS5_MUTUAL_AUTHENTICATION = TRUE

After editing, restart the Oracle listener.

lsnrctl stop && lsnrctl start

Configure Kerberos

Create krb5.conf with your Kerberos realm configuration.

Be sure to:

Replace your_realm with your Kerberos realm name (typically uppercase). For example, MYCOMPANY.COM, CORP.EXAMPLE.COM
Replace your_kdc_host with your KDC hostname. For example, kdc.mycompany.com, kdc1.corp.example.com
Replace your_domain with your domain for realm mapping. For example, mycompany.com, corp.example.com

[libdefaults]
  default_realm = your_realm
  dns_lookup_realm = false
  dns_lookup_kdc = false
  # Prefer TCP over UDP (more reliable through firewalls)
  udp_preference_limit = 1

[realms]
  your_realm = {
    kdc = your_kdc_host:88
    admin_server = your_kdc_host:749
  }

[domain_realm]
  .your_domain = your_realm
  your_domain = your_realm

Create sqlnet.ora

Create sqlnet.ora in your working directory to enable Kerberos authentication.

Be sure to:

Replace your_krb5_conf_path with the absolute path to your krb5.conf file. For example, /absolute/path/to/liquibase-krb/krb5.conf
Replace your_keytab_path with the absolute path to your Kerberos keytab file. For example, /absolute/path/to/liquibase.keytab
Replace your_cc_name with the path for the Kerberos credential cache. For example, /tmp/krb5cc_liquibase

# Client-side sqlnet.ora — Kerberos authentication settings

SQLNET.AUTHENTICATION_SERVICES         = (KERBEROS5)
SQLNET.KERBEROS5_CONF                  = your_krb5_conf_path
SQLNET.KERBEROS5_KEYTAB                = your_keytab_path
SQLNET.KERBEROS5_CC_NAME               = your_cc_name
SQLNET.KERBEROS5_MUTUAL_AUTHENTICATION = TRUE

NAMES.DIRECTORY_PATH = (TNSNAMES, EZCONNECT)

Create tnsnames.ora

Create tnsnames.ora in your TNS admin directory.

Be sure to:

Replace your_tns_alias with your TNS alias. For example, MYDB, PROD_DB, ORA_KRB
Replace your_hostname with your Oracle server hostname. For example, your-db-host.example.com, db.company.com
Replace your_port with your Oracle DB port. Usually. For example, 1521
Replace your_service_name with your service name. For example, MYDB, ORCL

your_tns_alias =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = your_hostname)(PORT = your_port))
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = your_service_name)
    )
  )

Configure JDBC properties

Create ojdbc.properties in your TNS admin directory.

Be sure to:

Replace your_tns_admin_dir with your absolute path to your TNS admin directory. For example, /home/user/tns-admin, /Users/name/tns-admin
Replace your_cc_name with your path for the Kerberos credential cache (must match sqlnet.ora). For example, /tmp/krb5cc_liquibase
Replace your_keytab_path with your path to your Kerberos keytab file (must match sqlnet.ora). For example, /etc/liquibase.keytab

# Path to the directory containing tnsnames.ora and sqlnet.ora
oracle.net.tns_admin=your_tns_admin_dir

# Force Kerberos authentication (no username/password)
oracle.net.authentication_services=(KERBEROS5)

# Path to the credential cache written by kinit
oracle.net.kerberos5_cc_name=your_cc_name

# Path to the Liquibase client keytab (from your KDC admin)
oracle.net.kerberos5_keytab=your_keytab_path

# Verify the Oracle server's Kerberos identity (recommended)
oracle.net.kerberos5_mutual_authentication=true

Configure Liquibase

Create liquibase.properties in your working directory. The /@MYDB URL format (with no username/password before @) means "connect using external authentication" — the Kerberos ticket provides the credentials.

Be sure to:

Replace MYDB with your TNS alias from tnsnames.ora. For example, MYDB, PROD_DB
Replace liquibase-svc with your Kerberos principal (without realm). For example, liquibase-svc, lbsvc

# liquibase.properties — Kerberos TCP connection
# No username or password — Kerberos handles authentication

liquibase.command.url=jdbc:oracle:thin:/@MYDB
liquibase.classpath=lib/ojdbc11.jar
liquibase.command.changelogFile=changelog.xml

Set environment variables

Set the following environment variables before running Liquibase.

Be sure to:

Replace your_krb5_conf_path with the absolute path to your krb5.conf file. For example, /absolute/path/to/liquibase-krb/krb5.conf
Replace your_ojdbc_props_path with the absolute path to your ojdbc.properties file. For example, /absolute/path/to/liquibase-krb/ojdbc.properties

# Set JAVA_HOME to Java ≤ 23 (required for Kerberos)
export JAVA_HOME=/path/to/jdk-21

# Load Oracle JDBC config and Kerberos JVM flags
export JAVA_OPTS="-Djava.security.krb5.conf=your_krb5_conf_path \
                -Djavax.security.auth.useSubjectCredsOnly=false \
                -Doracle.jdbc.config.file=your_ojdbc_props_path"

Obtain Kerberos ticket

Before running Liquibase, obtain a valid Kerberos ticket (TGT). Choose the method that matches your environment.

Be sure to:

Replace your_username@your_realm with your Kerberos principal. For example, liquibase-svc@COMPANY.COM
Replace your_krb5_conf with the absolute path to your krb5.conf file (Headless only). For example, /absolute/path/to/liquibase-krb/krb5.conf
Replace your_keytab_path with the absolute path to your keytab file (Headless only). For example, /absolute/path/to/liquibase.keytab
Replace your_cc_name with the path for the credential cache. For example, /tmp/krb5cc_liquibase

kinit your_username@your_realm

KRB5_CONFIG=your_krb5_conf \
kinit -kt your_keytab_path \
      -c your_cc_name \
      your_username@your_realm

kinit your_username@your_realm

KRB5_CONFIG=your_krb5_conf \
kinit -kt your_keytab_path \
      -c your_cc_name \
      your_username@your_realm

Verify the ticket was obtained.

KRB5CCNAME="FILE:your_cc_name" klist

Set the credential cache environment variable so tools find it automatically.

export KRB5CCNAME="FILE:your_cc_name"

Run Liquibase (TCP)

Be sure to:

Replace your_krb5_conf_path with the absolute path to your krb5.conf file. For example, /absolute/path/to/liquibase-krb/krb5.conf
Replace your_ojdbc_props_path with the absolute path to your ojdbc.properties file. For example, /absolute/path/to/liquibase-krb/ojdbc.properties
Replace your_liquibase_krb_path with the absolute path to your working directory. For example, /absolute/path/to/liquibase-krb

# Set JAVA_HOME to Java ≤ 23 (required for Kerberos)
export JAVA_HOME=/path/to/jdk-21

# Load Oracle JDBC config and Kerberos JVM flags
export JAVA_OPTS="-Djava.security.krb5.conf=your_krb5_conf_path \
                -Djavax.security.auth.useSubjectCredsOnly=false \
                -Doracle.jdbc.config.file=your_ojdbc_props_path"

# Use the ticket cache
export KRB5CCNAME="FILE:/tmp/krb5cc_liquibase"

# Run from the liquibase-krb/ directory so Liquibase finds the changelog
cd your_liquibase_krb_path
liquibase --defaults-file=liquibase.properties status --verbose
liquibase --defaults-file=liquibase.properties update
liquibase --defaults-file=liquibase.properties rollback-count --count=1

JAVA_HOME=/path/to/jdk-21 \
KRB5CCNAME="FILE:/tmp/krb5cc_liquibase" \
JAVA_OPTS="-Djava.security.krb5.conf=your_krb5_conf_path \
          -Djavax.security.auth.useSubjectCredsOnly=false \
          -Doracle.jdbc.config.file=your_ojdbc_props_path" \
liquibase \
  --search-path=your_liquibase_krb_path \
  --url="jdbc:oracle:thin:/@MYDB" \
  --driver=oracle.jdbc.OracleDriver \
  --classpath=your_liquibase_krb_path/lib/ojdbc11.jar \
  --username=liquibase-svc \
  --changeLogFile=changelog.xml \
  status --verbose

# Set JAVA_HOME to Java ≤ 23 (required for Kerberos)
export JAVA_HOME=/path/to/jdk-21

# Load Oracle JDBC config and Kerberos JVM flags
export JAVA_OPTS="-Djava.security.krb5.conf=your_krb5_conf_path \
                -Djavax.security.auth.useSubjectCredsOnly=false \
                -Doracle.jdbc.config.file=your_ojdbc_props_path"

# Use the ticket cache
export KRB5CCNAME="FILE:/tmp/krb5cc_liquibase"

# Run from the liquibase-krb/ directory so Liquibase finds the changelog
cd your_liquibase_krb_path
liquibase --defaults-file=liquibase.properties status --verbose
liquibase --defaults-file=liquibase.properties update
liquibase --defaults-file=liquibase.properties rollback-count --count=1

JAVA_HOME=/path/to/jdk-21 \
KRB5CCNAME="FILE:/tmp/krb5cc_liquibase" \
JAVA_OPTS="-Djava.security.krb5.conf=your_krb5_conf_path \
          -Djavax.security.auth.useSubjectCredsOnly=false \
          -Doracle.jdbc.config.file=your_ojdbc_props_path" \
liquibase \
  --search-path=your_liquibase_krb_path \
  --url="jdbc:oracle:thin:/@MYDB" \
  --driver=oracle.jdbc.OracleDriver \
  --classpath=your_liquibase_krb_path/lib/ojdbc11.jar \
  --username=liquibase-svc \
  --changeLogFile=changelog.xml \
  status --verbose

Get the server's TLS certificate

If your DBA provides a PEM file for the Oracle server certificate, copy it to your working directory and skip to the next step.

Otherwise, extract it from the Oracle TLS port.

Be sure to:

Replace db.company.com with your Oracle DB hostname
Replace 2484 with your Oracle TCPS port. Usually, 2484

# Replace 2484 with your Oracle TLS port; replace db.company.com with your DB hostname
openssl s_client -connect db.company.com:2484 -showcerts </dev/null 2>/dev/null \
  | openssl x509 -outform PEM > server.pem

# Verify: you should see CN= and notBefore/notAfter dates
openssl x509 -in server.pem -noout -subject -dates

Create the wallet directory

Create the wallet directory inside your working directory.

mkdir -p wallet

Import the certificate into the wallet

Import the server certificate into the wallet. Use whichever approach is available on your system.

# Create an auto-login wallet (no password needed at connection time)
orapki wallet create -wallet wallet/ -auto_login

# Import the server's certificate as a trusted entry
orapki wallet add -wallet wallet/ -trusted_cert -cert server.pem -auto_login_only

# Verify
orapki wallet display -wallet wallet/

# Create a PKCS12 file with the server cert (use any password — it's for trust only)
keytool -import -trustcacerts -noprompt \
        -alias oracle-server \
        -file server.pem \
        -keystore wallet/ewallet.p12 \
        -storetype PKCS12 \
        -storepass changeit

# Verify
keytool -list -keystore wallet/ewallet.p12 -storetype PKCS12 -storepass changeit

# Create an auto-login wallet (no password needed at connection time)
orapki wallet create -wallet wallet/ -auto_login

# Import the server's certificate as a trusted entry
orapki wallet add -wallet wallet/ -trusted_cert -cert server.pem -auto_login_only

# Verify
orapki wallet display -wallet wallet/

# Create a PKCS12 file with the server cert (use any password — it's for trust only)
keytool -import -trustcacerts -noprompt \
        -alias oracle-server \
        -file server.pem \
        -keystore wallet/ewallet.p12 \
        -storetype PKCS12 \
        -storepass changeit

# Verify
keytool -list -keystore wallet/ewallet.p12 -storetype PKCS12 -storepass changeit

Verify the wallet contents (optional but recommended)

If you have oraclepki.jar available, compile and run this one-time diagnostic to confirm the wallet has the server certificate.

// CheckWallet.java — compile and run to inspect cwallet.sso
import oracle.security.pki.OraclePKIProvider;
import java.security.*;
import java.io.*;
import java.util.Enumeration;
import java.security.cert.X509Certificate;

public class CheckWallet {
    public static void main(String[] args) throws Exception {
        Security.insertProviderAt(new OraclePKIProvider(), 3);
        String walletDir = args.length > 0 ? args[0] : "wallet";
        System.out.println("Checking: " + walletDir + "/cwallet.sso");
        KeyStore ks = KeyStore.getInstance("SSO", "OraclePKI");
        ks.load(new FileInputStream(walletDir + "/cwallet.sso"), null);
        System.out.println("Entries: " + ks.size());
        Enumeration<String> al = ks.aliases();
        while (al.hasMoreElements()) {
            String a = al.nextElement();
            System.out.println("  " + a);
            if (ks.isCertificateEntry(a)) {
                X509Certificate c = (X509Certificate) ks.getCertificate(a);
                System.out.println("    Subject: " + c.getSubjectX500Principal());
            }
        }
    }
}

# Compile
javac -cp lib/ojdbc11.jar:lib/oraclepki.jar:lib/osdt_core.jar:lib/osdt_cert.jar \
      CheckWallet.java

# Run
java -cp lib/ojdbc11.jar:lib/oraclepki.jar:lib/osdt_core.jar:lib/osdt_cert.jar:. \
     CheckWallet wallet/

Expected output:

Checking: wallet/cwallet.sso
Entries: 1
CN=db.company.com
  Subject: CN=db.company.com

If Entries: 0, the wallet is empty — re-run the previous step.

Update tnsnames.ora for TCPS

Add a TCPS entry to your existing tnsnames.ora. Keep the original TCP entry (MYDB) as a fallback.

Be sure to:

Replace db.company.com with your Oracle DB hostname
Replace MYDB with your Oracle service name
Replace /absolute/path/to/wallet with the absolute path to your wallet directory

# TCP connection (from Part A — keep this for fallback)
MYDB =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = db.company.com)(PORT = 1521))
    (CONNECT_DATA = (SERVER = DEDICATED)(SERVICE_NAME = MYDB))
  )

# TCPS connection — Kerberos authentication + TLS encryption
MYDB_SSL =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCPS)(HOST = db.company.com)(PORT = 2484))
    (CONNECT_DATA = (SERVER = DEDICATED)(SERVICE_NAME = MYDB))
    (SECURITY =
      (MY_WALLET_DIRECTORY = /absolute/path/to/wallet)
    )
  )

Create ojdbc_ssl.properties

Create ojdbc_ssl.properties as a separate file from ojdbc.properties. This lets you switch between TCP and TCPS without editing the same file — use ojdbc.properties for TCP and ojdbc_ssl.properties for TCPS.

Be sure to:

Replace /absolute/path/to/liquibase-krb with the absolute path to your working directory
Replace /absolute/path/to/liquibase.keytab with the absolute path to your keytab file
Replace /absolute/path/to/wallet with the absolute path to your wallet directory
Set oracle.net.ssl_server_dn_match=true if the server cert CN matches the hostname in your JDBC URL; set it to false if connecting via localhost, IP, or alias

# ojdbc_ssl.properties — Oracle JDBC Kerberos + TCPS (Oracle Wallet) settings
# Load this by adding to JAVA_OPTS:
#   -Doracle.jdbc.config.file=/absolute/path/to/liquibase-krb/ojdbc_ssl.properties

# Path to directory containing tnsnames.ora and sqlnet.ora
oracle.net.tns_admin=/absolute/path/to/liquibase-krb

# Kerberos authentication
oracle.net.authentication_services=(KERBEROS5)
oracle.net.kerberos5_cc_name=/tmp/krb5cc_liquibase
oracle.net.kerberos5_keytab=/absolute/path/to/liquibase.keytab
oracle.net.kerberos5_mutual_authentication=true

# ── TLS / Oracle Wallet ──────────────────────────────────────────────────────
# Wallet directory containing the server's trusted certificate.
# This must contain cwallet.sso (with the Oracle server's cert imported).
# The wallet is loaded internally by Oracle JDBC — oraclepki.jar must be on classpath.
oracle.net.wallet_location=(SOURCE=(METHOD=FILE)(METHOD_DATA=(DIRECTORY=/absolute/path/to/wallet)))

# Set to "true" if the server cert CN matches the hostname in your JDBC URL.
# Set to "false" if connecting via localhost, IP, or alias (common in dev/Docker setups).
oracle.net.ssl_server_dn_match=false

Run Liquibase with TCPS

The only changes from the TCP run are:

Use ojdbc_ssl.properties instead of ojdbc.properties
Add the three PKI JARs to the classpath
Use the MYDB_SSL TNS alias (TCPS, port 2484)

Be sure to:

Replace your_krb5_conf_path with the absolute path to your krb5.conf file
Replace your_liquibase_krb_path with the absolute path to your working directory

export JAVA_HOME=/path/to/jdk-21
export KRB5CCNAME="FILE:/tmp/krb5cc_liquibase"
export JAVA_OPTS="-Djava.security.krb5.conf=your_krb5_conf_path \
                -Djavax.security.auth.useSubjectCredsOnly=false \
                -Doracle.jdbc.config.file=your_liquibase_krb_path/ojdbc_ssl.properties"

liquibase \
  --search-path=your_liquibase_krb_path \
  --url="jdbc:oracle:thin:/@MYDB_SSL" \
  --classpath="lib/ojdbc11.jar:lib/oraclepki.jar:lib/osdt_core.jar:lib/osdt_cert.jar" \
  --username=liquibase-svc \
  --changelog-file=changelog.xml \
  status --verbose