Task
Version · 6.0
Create

MSSQL Server with Integrated Security and Kerberos Authentication for Linux and macOS

Last updated: August 11, 2026

If your application runs on a Linux or macOS machine in an Active Directory environment, you can use integrated security to access your Microsoft SQL Server database. Integrated security uses an operating-system identity, rather than a username and password stored in Liquibase, to authenticate to MSSQL Server.

Kerberos is an authentication protocol that works based on tickets to provide strong authentication for client/server applications by using secret-key cryptography. The Kerberos authentication protocol does not store passwords locally or send them over the Internet.

On Linux and macOS, Kerberos (authenticationScheme=JavaKerberos) is the only integrated authentication mechanism available to the Microsoft JDBC driver. The NativeAuthentication scheme is available on Windows only, see MSSQL Server with Integrated Security and Kerberos Authentication for Windows.

Note: This page covers integrated (passwordless) authentication. If you want to connect with a username and password instead, you do not need Kerberos, see Using Liquibase with MSSQL Server.

Before you begin

Install Liquibase.
Ensure you have Java installed. Liquibase requires Java to run. If you used the Liquibase Installer, Java is included automatically. Otherwise, you must install Java manually.
Ensure SQL Server is joined to Active Directory and has a Service Principal Name (SPN) registered, for example MSSQLSvc/dbserver.mydomain.com:1433. See Use Active Directory authentication with SQL Server on Linux or ask your DBA.
Note: For SQL Server on Amazon RDS joined to AWS Managed Microsoft AD, the SPN is registered automatically under the instance's AD machine name (for example EC2AMAZ-XXXXXXX.mydomain.com), not under the *.rds.amazonaws.com endpoint. See Connecting through a load balancer, CNAME, or RDS endpoint.
Ensure your machine can reach the Active Directory domain controllers (TCP/UDP 88 for Kerberos and DNS for the AD domain) and the SQL Server host (TCP 1433).
Have an Active Directory user with a login on the SQL Server instance (for example MYDOMAIN\lbuser).
Install the Kerberos client tools (kinit, klist) if they are not already present. On most Linux distributions they are in the krb5-workstation (RHEL family) or krb5-user (Debian family) package. macOS includes them (Heimdal) out of the box.

Procedure

Configure Kerberos

Create or verify the /etc/krb5.conf file. Hosts that are already joined to the domain typically have a working file; in that case, continue to step 2.

Example

[libdefaults]
    default_realm = MYDOMAIN.COM
    dns_lookup_kdc = true
    dns_lookup_realm = false
    forwardable = true
[realms]
    MYDOMAIN.COM = {
        kdc = dc1.mydomain.com
        admin_server = dc1.mydomain.com
    }
[domain_realm]
    .mydomain.com = MYDOMAIN.COM
    mydomain.com = MYDOMAIN.COM

Note: The realm name (MYDOMAIN.COM) is your Active Directory domain name in UPPERCASE. It must be identical in default_realm, the [realms] section, and the [domain_realm] mappings.

(Optional) If you cannot edit /etc/krb5.conf, place the file anywhere and point both the Kerberos tools and Liquibase at it. You will also pass -Djava.security.krb5.conf=/path/to/krb5.conf to Liquibase in step 3.

export KRB5_CONFIG=/path/to/krb5.conf

Obtain a Kerberos ticket

1. Set the KRB5CCNAME environment variable to a file-based ticket cache before running kinit:

export KRB5CCNAME=FILE:/tmp/krb5cc_$(id -u)

Note: The Java Virtual Machine that runs Liquibase can read Kerberos tickets only from a FILE: cache. Many modern systems default to a cache type that Java cannot read, KCM: on RHEL 8+ and Fedora (sssd-kcm), and the API: cache on macOS. If you skip this step, kinit and sqlcmd work but Liquibase fails to find the ticket.

2. Run the kinit command to obtain and cache the Kerberos ticket-granting ticket, then verify it with klist:

kinit lbuser@MYDOMAIN.COM
klist

Sample output

Ticket cache: FILE:/tmp/krb5cc_1001
Default principal: lbuser@MYDOMAIN.COM
Valid starting     Expires            Service principal
06/05/26 12:41:48  06/05/26 22:41:48  krbtgt/MYDOMAIN.COM@MYDOMAIN.COM
        renew until 06/12/26 12:41:48

The Ticket cache line must begin with FILE:. If it shows KCM: or API:, the KRB5CCNAME variable was not in effect when you ran kinit.

3. Keep KRB5CCNAME exported in the shell where you run Liquibase. Tickets expire (10 hours by default); re-run kinit when they do.

Configure the Liquibase connection

If your krb5.conf is not at the platform default location (/etc/krb5.conf), include the following JAVA_OPTS argument:

JAVA_OPTS="-Djava.security.krb5.conf=/path/to/krb5.conf"

No other JAVA_OPTS arguments are required for Kerberos.

Verify the connection

1. Run the liquibase status command to ensure the connection works:

liquibase status --verbose

Sample output

Starting Liquibase at 15:09:50 (version 5.0.0)
Liquibase Secure license issued to MyCompany
MYDOMAIN\lbuser@jdbc:sqlserver://dbserver.mydomain.com:1433;...;authenticationScheme=JavaKerberos;...;databaseName=MYDATABASE;... is up to date
Liquibase command 'status' was executed successfully.

The connection identity (MYDOMAIN\lbuser@jdbc:sqlserver://...) confirms Liquibase connected as the Active Directory user.

(Optional) For positive proof that the session authenticated with Kerberos, and not NTLM or SQL authentication, run:

liquibase execute-sql --sql "SELECT SUSER_SNAME() AS logged_in_as, auth_scheme FROM sys.dm_exec_connections WHERE session_id=@@SPID"

Sample output

Output of SELECT SUSER_SNAME() AS logged_in_as, auth_scheme FROM sys.dm_exec_connections WHERE session_id=@@SPID:
LOGGED_IN_AS    | AUTH_SCHEME |
MYDOMAIN\lbuser | KERBEROS    |
Liquibase command 'execute-sql' was executed successfully.

2. You can now run any Liquibase command. For example:

liquibase update

Sample output

Running Changeset: changelog.sql::myfirstchangeset::lbuser
UPDATE SUMMARY
Run:                          1
Previously run:               0
Filtered out:                 0
-------------------------------
Total change sets:            1
Liquibase: Update has been successful. Rows affected: 1
Liquibase command 'update' was executed successfully.

Connecting through a load balancer, CNAME, or RDS endpoint

Kerberos issues service tickets for a specific SPN. If the hostname in your JDBC URL is not the name the SPN was registered under — common with Amazon RDS endpoints (*.rds.amazonaws.com), CNAME aliases, and load balancers — authentication fails with No valid credentials provided (Mechanism level: Server not found in Kerberos database (7)) even though the ticket from kinit is valid.

You have two options:

1. Connect using the AD-registered name (preferred when your network can resolve it):

url: jdbc:sqlserver://EC2AMAZ-XXXXXXX.mydomain.com:1433;databaseName=MYDATABASE;integratedSecurity=true;authenticationScheme=JavaKerberos;useDefaultJaasConfig=true;encrypt=true;trustServerCertificate=true

2. Keep the alias in the URL and override the SPN with the serverSpn property:

url: jdbc:sqlserver://myinstance.abc123.us-east-1.rds.amazonaws.com:1433;databaseName=MYDATABASE;integratedSecurity=true;authenticationScheme=JavaKerberos;useDefaultJaasConfig=true;encrypt=true;trustServerCertificate=true;serverSpn=MSSQLSvc/EC2AMAZ-XXXXXXX.mydomain.com:1433

To find the registered SPN, ask your DBA, or run setspn -L <machine-account> from any domain-joined Windows machine.

macOS notes

macOS ships the Heimdal Kerberos implementation rather than MIT Kerberos. The procedure above is identical on macOS, with two caveats:

Ticket cache: the macOS default ticket cache is the API:/KCM cache, which the JVM cannot read. The export KRB5CCNAME=FILE:... step is mandatory on macOS, not just recommended.

Forcing TCP to the KDC: if your network blocks UDP port 88, Heimdal and Java require different configuration:

For kinit (Heimdal): use kdc = tcp/dc1.mydomain.com:88 in the [realms] section.
For Liquibase (Java): use plain kdc = dc1.mydomain.com:88 and add udp_preference_limit = 1 to [libdefaults].

Java does not understand the tcp/ prefix and Heimdal does not honor udp_preference_limit, so in this situation maintain two krb5.conf files, one for kinit (selected with KRB5_CONFIG) and one for Liquibase (selected with -Djava.security.krb5.conf). On networks where UDP 88 is open, a single shared file works for both.

Unattended execution with a keytab

For CI/CD pipelines and scheduled jobs where running kinit interactively is not possible, store the principal's key in a keytab file and refresh the ticket non-interactively.

Note: Use only AES encryption types. The RC4 (arcfour-hmac) and DES encryption types are deprecated and rejected by current Active Directory and Kerberos clients.

1. Create the keytab with the MIT ktutil utility:

ktutil
ktutil:  add_entry -password -p lbuser@MYDOMAIN.COM -k 1 -e aes256-cts-hmac-sha1-96
Password for lbuser@MYDOMAIN.COM:
ktutil:  wkt /secure/path/lbuser.keytab
ktutil:  q

Note: The key version number (-k) must match the account's msDS-KeyVersionNumber attribute in Active Directory, and the keytab must be regenerated whenever the account password changes.

2. Verify the keytab and obtain a ticket from it:

klist -k /secure/path/lbuser.keytab
export KRB5CCNAME=FILE:/tmp/krb5cc_lb
kinit -kt /secure/path/lbuser.keytab lbuser@MYDOMAIN.COM

3. Run Liquibase exactly as described in Configure the Liquibase connection in step 3.

Protect the keytab file like a password file (chmod 600) and store it outside version control.

Troubleshooting

Symptom	Likely cause and fix
`Kerberos Login failed: Integrated authentication failed ... LoginException (Cannot get any of properties: [user, USER] from con properties ...)`	The JVM found no ticket. Ensure `KRB5CCNAME` points to a `FILE:` cache, the ticket is not expired (`klist`), and the variable is exported in the same shell that runs Liquibase
`No valid credentials provided (Mechanism level: Server not found in Kerberos database (7))`, typically only via an alias, load balancer, or RDS endpoint	SPN mismatch, the URL hostname is not the name the SPN is registered under. Connect via the AD machine name or add `serverSpn=` to the URL (see above)
`KrbException: Encryption type ... is not supported/enabled`	Deprecated encryption types in a keytab or krb5.conf. Remove allow_weak_crypto, RC4, and DES configuration, and regenerate keytabs with AES
`Cannot locate KDC / Cannot contact any KDC`	The `[realms]` section is wrong or DNS SRV lookups are failing. Verify `dig SRV _kerberos._tcp.MYDOMAIN.COM` resolves, or list KDCs explicitly in `[realms]`
Works with `sqlcmd -E` but Liquibase fails to find a ticket	`sqlcmd` can read KCM/API caches; Java cannot. Re-run `kinit` with `KRB5CCNAME=FILE:...` set
`Clock skew too great`	Kerberos requires client and KDC clocks within 5 minutes. Enable NTP time synchronization

To see detailed Kerberos negotiation logs while diagnosing a problem, add -Dsun.security.krb5.debug=true to JAVA_OPTS. Remove it for normal operation.

PreviousMSSQL server with integrated security and Kerberos authentication for Windows NextUse the SQLCMD integration with multiple databases

MSSQL Server with Integrated Security and Kerberos Authentication for Linux and macOS

Before you begin

Procedure

Configure Kerberos

Obtain a Kerberos ticket

Configure the Liquibase connection

Verify the connection

Connecting through a load balancer, CNAME, or RDS endpoint

macOS notes

Unattended execution with a keytab

Troubleshooting

Related links