SQL Server Kerberos authentication

This guide describes how to configure a Database connection to authenticate with Microsoft SQL Server using Kerberos ticket cache authentication (kinit).

Prerequisites

Before beginning, ensure the following are in place:

1. A Jitterbit private agent.

2. Network access to the following:

   • An Active Directory Domain Controller (Key Distribution Center, or KDC).

   • The SQL Server host.

3. A valid Active Directory user account.

4. A Service Principal Name (SPN) configured in Active Directory for SQL Server in the following format:

    MSSQLSvc/<SQL_SERVER_HOST>:<PORT>
   

Step 1: Ensure DNS resolution to the KDC

Kerberos requires proper DNS resolution to locate the KDC.

Linux

In some environments, DNS may need to be adjusted. Replace the following placeholders with your values:

• <AD_DNS_IP>: The DNS server that can resolve the Active Directory domain.
• <SECONDARY_DNS_IP>: An optional fallback DNS server.

This is a temporary configuration. Run these commands again each time the container restarts:

cat > /etc/resolv.conf <<EOF
nameserver <AD_DNS_IP>
nameserver <SECONDARY_DNS_IP>
EOF

Windows

If the device running the Windows private agent is already joined to the same domain as the KDC, no further configuration is needed. Otherwise, add the required entries to C:\Windows\System32\drivers\etc\hosts so the device can resolve the KDC and SQL Server hostnames.

Step 2: Install Kerberos client utilities

Linux

The private agent host must have Kerberos tools installed. These tools are required to create the ticket cache and to validate KDC communication and service ticket creation.

Run the following commands to install krb5-user:

apt-get update
apt-get install krb5-user

This installs the following:

• kinit
• klist
• Kerberos libraries

Windows

Kerberos tools are available natively on Windows. If they are not installed, download them from https://ist.mit.edu/mit-apps/kerberos-win.

Step 3: Test DNS resolution

Verify that the agent can resolve the KDC hostname.

Linux

Run the following command to install DNS utilities:

apt-get update
apt-get install dnsutils

Then test the DNS resolution:

nslookup <DOMAIN_CONTROLLER_HOSTNAME>

nslookup ad.dev.local

Windows

Run the following command to test name resolution:

ping <DOMAIN_CONTROLLER_HOSTNAME>

ping ad.dev.local

If resolution fails, Kerberos authentication will not work.

Step 4: Create the Kerberos configuration file (krb5.conf)

Linux

Use the following command to create or edit the configuration file at /etc/krb5.conf:

vi /etc/krb5.conf

[libdefaults]
default_realm = DEV.LOCAL
rdns = false
dns_lookup_kdc = false
dns_lookup_realm = false
[realms]
DEV.LOCAL = {
kdc = ad.dev.local
admin_server = ad.dev.local
}
[domain_realm]
.dev.local = DEV.LOCAL
dev.local = DEV.LOCAL

Windows

Create the krb5.conf file using the same structure shown above. Choose a location that the private agent can access without requiring elevated privileges, such as:

C:\Jitterbit\kerberos

Configuration parameters

[libdefaults]

• default_realm: The Active Directory domain name in uppercase.
• rdns = false: Prevents reverse DNS lookup issues.
• dns_lookup_kdc = false: Disables automatic KDC discovery via DNS.
• dns_lookup_realm = false: Disables automatic realm discovery via DNS.

[realms]

• kdc: The domain controller hostname.
• admin_server: The domain controller for administrative operations.

[domain_realm]

Maps DNS domains to the Kerberos realm.

Step 5: Create the JAAS configuration file

Kerberos authentication requires a Java Authentication and Authorization Service (JAAS) configuration file.

Linux

Run the following command to create the directory:

mkdir -p /opt/jitterbit/kerberos

Run the following command to create the configuration file:

vi /opt/jitterbit/kerberos/jaas.conf

com.sun.security.jgss.krb5.initiate {
com.sun.security.auth.module.Krb5LoginModule required
useTicketCache=true
useKeyTab=false
storeKey=false
isInitiator=true
doNotPrompt=true
renewTGT=false
debug=true
refreshKrb5Config=true;
};

SQLJDBCDriver {
com.sun.security.auth.module.Krb5LoginModule required
useTicketCache=true
useKeyTab=false
storeKey=false
isInitiator=true
doNotPrompt=true
renewTGT=false
debug=true
refreshKrb5Config=true;
};

Windows

Create the jaas.conf file using the same structure shown above. Choose a location that the private agent can access without requiring elevated privileges, such as:

C:\Jitterbit\kerberos

JAAS parameter reference

• useTicketCache=true: Uses the Kerberos ticket obtained via kinit.
• useKeyTab=false: Does not use a keytab file.
• storeKey=false: Does not store a secret key.
• isInitiator=true: Configures this client as the authentication initiator.
• doNotPrompt=true: Does not prompt for a password.
• renewTGT=false: Does not auto-renew the Ticket Granting Ticket (TGT).
• debug=true: Enables Kerberos debug logs. (Optional)
• refreshKrb5Config=true: Reloads the Kerberos configuration dynamically.

Set file permissions (Linux only)

Kerberos authentication requires proper file permissions to function correctly. If the files are not readable, authentication will fail with the following error:

Could not initialize class com.microsoft.sqlserver.jdbc.KerbAuthentication

Run the following commands to set the required permissions:

chmod 644 /opt/jitterbit/kerberos/jaas.conf
chmod 644 /etc/krb5.conf
chmod 644 /tmp/krb5cc_agent

Step 6: Configure Tomcat (setenv.sh)

Linux

Use the following command to open the Tomcat startup script at /opt/jitterbit/tomcat/bin/setenv.sh:

vi /opt/jitterbit/tomcat/bin/setenv.sh

#!/bin/sh
JAVA_OPTS="$JAVA_OPTS \
-Djava.security.krb5.conf=/etc/krb5.conf \
-Dsun.security.jgss.native=true \
-Djava.security.auth.login.config=/opt/jitterbit/kerberos/jaas.conf \
-Dsun.security.krb5.debug=true \
-Djavax.security.auth.useSubjectCredsOnly=false"

export KRB5CCNAME=/tmp/krb5cc_agent
export JAVA_OPTS

Windows

For the Windows private agent, you do not need to create a setenv.sh file. Instead, add the JAVA_OPTS parameters shown above by following the instructions in Configure Java options for private agents.

When setting KRB5CCNAME, note the path, as you will need to specify it again in Step 8 when creating the ticket cache.

If the connection test returns an error mentioning jgss or gss, try the following:

1. Remove the -Dsun.security.jgss.native=true parameter.
2. Add udp_preference_limit = 1 to the [libdefaults] section of krb5.conf.
3. Restart the agent for the changes to take effect.

Parameter reference

• java.security.krb5.conf: The path to the Kerberos configuration file.
• sun.security.jgss.native=true: Enables the native Generic Security Services (GSS) implementation.
• java.security.auth.login.config: The path to the JAAS configuration file.
• sun.security.krb5.debug=true: Enables Kerberos debug logs (optional).
• javax.security.auth.useSubjectCredsOnly=false: Allows the use of external credentials.

Step 7: Restart the private agent

After any configuration change, restart the private agent.

Linux

Run the following command to restart the agent:

sudo jitterbit restart

If using a Docker agent, restart the container:

docker restart <CONTAINER_NAME>

After restarting, repeat Step 1.

Windows

To restart the Windows private agent, use the stop and start shortcuts created during agent installation:

Stop Jitterbit Services
Start Jitterbit Services

Step 8: Obtain a Kerberos ticket

This configuration uses a Kerberos ticket cache, which is user-dependent. The following commands create a ticket cache that Tomcat accesses at runtime. You may be prompted to enter a password.

Linux

Run the following command to create the ticket cache:

kinit -c /tmp/krb5cc_agent <USER>@<REALM>

Verify the ticket was created:

klist -c /tmp/krb5cc_agent

Windows

On Windows, use the same path specified for KRB5CCNAME in Step 6.

Run the following command to create the ticket cache:

kinit -c <TICKET_CACHE_PATH> <USER>@<REALM>

Verify the ticket was created:

klist -c <TICKET_CACHE_PATH>

If no ticket appears, authentication will fail.

Step 9: Configure the Database connection

Configure the Database connection with the following settings:

1. Driver type: Select JDBC.
2. Driver: Select SQL Server (Microsoft).
3. Server name: Enter the name, URL, or IP address of the SQL Server.
4. Database name: Enter the name of the target database.
5. Login and Password: Leave these fields blank.

6. Under Optional settings, select the Use Connection String checkbox and enter the following:

   jdbc:sqlserver://<SQL_SERVER_HOST>:<PORT>;databaseName=<DATABASE>;integratedSecurity=true;authenticationScheme=JavaKerberos;encrypt=false
   

Configure the connection string using the following values:

• <SQL_SERVER_HOST>: The fully qualified domain name (FQDN) of the SQL Server.
• <PORT>: The SQL Server port number, typically 1433.
• <DATABASE>: The name of the target database.
• encrypt: Set to true or false depending on your environment.
• trustServerCertificate=true: Required if using Transport Layer Security (TLS) without a trusted certificate authority (CA).