Overview

Kerberos authentication centralizes security by using ticket-based authentication to authenticate users and services without sending passwords over the network. When Db2 is integrated with Kerberos:

• Db2 server authenticates clients based on Kerberos service tickets.
• Clients authenticate to the Kerberos Key Distribution Center (KDC) to obtain tickets.
• Db2 validates client tickets via the keytab file containing its service principal credentials.
• Authentication becomes seamless and secure.

Prerequisites

• A working Kerberos realm with a KDC and admin server.
• DNS resolution working properly for Db2 server and clients.
• Time synchronization across all relevant hosts (e.g., via NTP).
• Db2 version that supports Kerberos authentication.
• krb5-user (Kerberos client) installed on both Db2 server and client machines.
• Db2 instance user (usually db2inst1) created on the Db2 server.
• Administrative access to the Kerberos server for principal management.

Create and Export the Db2 Service Principal

On the Kerberos server, open the administrative shell:

sudo kadmin.local

Create the service principal for Db2. Use the fully qualified domain name (FQDN) of your Db2 server, in uppercase realm:

On UNIX and Linux® systems, the default server principal name for a Db2 database instance follows the format:

<instance_name>/<fully_qualified_hostname>@<REALM>.

This Kerberos principal must be properly created and configured before starting the Db2 instance, as the server retrieves and uses this principal name during initialization via the Kerberos plug-in. Additionally, the principal must be authorized to accept incoming Kerberos security contexts for authentication to function correctly.

https://www.ibm.com/docs/en/db2/11.5.x?topic=authentication-naming-mapping-kerberos

addprinc -randkey db2inst1/db2server.example.com@EXAMPLE.COM

This creates a principal without a password, as it uses keytabs for authentication.

Export this principal to a keytab file:

ktadd -k /etc/db2/db2.keytab db2inst1/db2server.example.com@EXAMPLE.COM

Secure the keytab file:

chmod 400 /etc/db2/db2.keytab

Exit the Kerberos admin shell:

quit

If your Db2 server is a different machine, securely transfer the keytab to the Db2 server :

scp /etc/db2/db2.keytab root@db2server.example.com:/etc/krb5.keytab

On the Db2 server, set appropriate ownership and permissions:

chown db2inst1:db2inst1 /etc/krb5.keytab
chmod 400 /etc/krb5.keytab

Create the Db2 User Principal on the Kerberos Server

In this step, we are registering the Db2 user with the Kerberos server by creating a Kerberos principal. This principal acts like a secure identity for the user within the Kerberos authentication system. It allows the Db2 user to request and receive Kerberos tickets, which are required for secure, single sign-on access to services. This setup is a key part of enabling Kerberos-based authentication for Db2.

In the Kerberos admin shell:

sudo kadmin.local
addprinc <db2_user>@EXAMPLE.COM

Set a password when prompted — it will be required later during kinit authentication.

Exit the shell:

quit

Replace <db2_user> with the actual Db2 user name (e.g., db2inst1).

How to Add Kerberos Users to Db2

1. Create the Kerberos principal (you already did this with addprinc).

2. Ensure the OS user exists Db2 maps Kerberos principals to operating system users. So, create the matching OS user if it doesn’t exist:

   sudo useradd <db2_user>

3. Create the user in Db2 Connect to your Db2 database as an administrator and create a Db2 user with the same name:

   CREATE USER <db2_user>;
   

   (Note: Some Db2 versions don’t require explicit user creation; the OS user is enough, but creating users allows for explicit privileges.)

   The Kerberos principal password and the operating system user password are separate and do not have to be the same. The Kerberos password is used to get authentication tickets from the Kerberos server, while the OS password is used to log into the server itself. They serve different purposes and are managed independently.

4. Grant necessary privileges Assign the required permissions to the user:

   GRANT CONNECT ON DATABASE TO USER <db2_user>;
   -- and any other needed privileges, e.g.:
   GRANT SELECT ON TABLE schema.table TO USER <db2_user>;
   

Install and Configure Kerberos Client on Db2 Server

Ensure the Kerberos client package is installed:

sudo apt install krb5-user

During installation, configure the following:

• Default Kerberos realm: The realm name (e.g., EXAMPLE.COM) in uppercase.
• Kerberos servers: The hostname or IP of your KDC (e.g., kdc.example.com).
• Admin server: Usually the same as the KDC.

Verify the contents of /etc/krb5.conf reflect your realm, KDC, and admin server correctly. The [realms] section should look similar to:

[realms]
  EXAMPLE.COM = {
    kdc = kdc.example.com
    admin_server = kdc.example.com
  }

Configure Db2 to Use Kerberos Authentication

Login as db2inst1 user on the Db2 server.

Set the environment variable pointing to the keytab file:

export KRB5_KTNAME=/etc/krb5.keytab

To make this persistent across sessions, add it to .bashrc or .profile:

echo "export KRB5_KTNAME=/etc/krb5.keytab" >> ~/.bashrc
source ~/.bashrc

Next, configure Db2 to recognize the environment variable by setting DB2ENVLIST:

db2set DB2ENVLIST=KRB5_KTNAME

# Display all current Db2 registry variables to verify the setting
db2set -all

Update the Db2 database manager configuration:

db2 update dbm cfg using CLNT_KRB_PLUGIN IBMkrb5
db2 update dbm cfg using AUTHENTICATION KRB_SERVER_ENCRYPT

Verify that the changes took effect:

db2 get dbm cfg | grep -i -E 'auth|plugin'

The output should include:

db2inst1@db2-enterprise1:~$ db2 get dbm cfg | grep -i -E 'auth|plugin'
 Client Userid-Password Plugin          (CLNT_PW_PLUGIN) = 
 Client Kerberos Plugin                (CLNT_KRB_PLUGIN) = IBMkrb5
 Group Plugin                             (GROUP_PLUGIN) = 
 GSS Plugin for Local Authorization    (LOCAL_GSSPLUGIN) = 
 Server Plugin Mode                    (SRV_PLUGIN_MODE) = UNFENCED
 Server List of GSS Plugins      (SRVCON_GSSPLUGIN_LIST) = 
 Server Userid-Password Plugin        (SRVCON_PW_PLUGIN) = 
 Server Connection Authentication          (SRVCON_AUTH) = NOT_SPECIFIED
 Database manager authentication        (AUTHENTICATION) = KRB_SERVER_ENCRYPT
 Alternate authentication           (ALTERNATE_AUTH_ENC) = NOT_SPECIFIED
 Cataloging allowed without authority   (CATALOG_NOAUTH) = NO
 Trusted client authentication          (TRUST_CLNTAUTH) = CLIENT

Set the DB2_KRB5_PRINCIPAL Environment Variable

To ensure Kerberos authentication works correctly with Db2, you must define the DB2_KRB5_PRINCIPAL environment variable with the full Kerberos principal name of the Db2 instance. If this variable is not set, you may encounter connection issues when attempting to authenticate.

Edit the /etc/environment file on the Db2 server and add the following line (replace with your actual principal if different):

DB2_KRB5_PRINCIPAL=db2inst1/db2-enterprise1.example.com@EXAMPLE.COM

Example:

db2inst1@db2-enterprise1:~$ cat /etc/environment
PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin"
DB2_KRB5_PRINCIPAL=db2inst1/db2-enterprise1.example.com@EXAMPLE.COM

This ensures that Db2 knows which Kerberos principal to use during authentication

Obtain Kerberos Ticket and Start Db2

Obtain a Kerberos ticket as db2inst1:

kinit db2inst1@EXAMPLE.COM

Provide the password set earlier.

Verify the ticket is active:

klist

Start the Db2 instance:

# Force stop the Db2 instance to apply configuration changes
db2stop force

# Start the Db2 instance again
db2start

Troubleshoot

If any errors occur during db2start, verify the following:

• The keytab file contains the correct Kerberos principal.
• The principal’s hostname matches the server’s fully qualified domain name (FQDN).
• The KRB5_KTNAME environment variable is properly set and points to the keytab file.
• The system clock is synchronized to avoid time skew issues.
• DNS resolves the Db2 server hostname correctly.

To identify the exact issue, check the Db2 diagnostic log:

find ./ -name "db2diag.log"

cat ./sqllib/db2dump/DIAG0000/db2diag.log

Example error:

db2inst1@db2-enterprise1:~$ db2start
SQL1365N  db2start or db2stop failed in processing the plugin "IBMkrb5". Reason code = "10".
09/13/2025 23:23:18     0   0   SQL1365N  db2start or db2stop failed in processing the plugin "". Reason code = "".
SQL1032N  No start database manager command was issued.  SQLSTATE=57019

This issue can occur if the /etc/krb5.keytab file is missing, inaccessible by the Db2 instance user, or does not contain the correct principal.

The expected principal format is:

<instance_name>/<fully_qualified_hostname>@<REALM>

Configure Kerberos Client Machines

In this step, we configure the Db2 client machine (or any host that needs to connect securely to a Kerberos-enabled Db2 server). For the client to authenticate using Kerberos, it must be able to communicate with the Kerberos Key Distribution Center (KDC).

This involves:

• Installing the Kerberos client tools (krb5-user)
• Configuring the /etc/krb5.conf file to define the Kerberos realm, KDC, and other necessary settings

By setting up the Kerberos client, the Db2 client machine can obtain Kerberos tickets and use them to securely authenticate to the Db2 server without using traditional username/password login.

This configuration is essential for enabling single sign-on (SSO) and centralized authentication in a Kerberos-integrated Db2 environment.

1. Install the Kerberos client utilities:

   sudo apt install krb5-user
   

2. Configure the Kerberos client:

   The Kerberos client requires the /etc/krb5.conf file to define the realm and KDC settings. You can reuse the same krb5.conf file from the Kerberos server, as it already contains the correct configuration for your environment.

   To copy the file from the Kerberos server:

   scp user@<kerberos-server-ip>:/etc/krb5.conf /etc/krb5.conf
   

   Replace <kerberos-server-ip> and user with appropriate values.

   This ensures consistency across your Kerberos environment. In most cases, no further modification is needed unless you have client-specific overrides.

3. Obtain a Kerberos ticket for the user:

   kinit username@EXAMPLE.COM
   

   Replace username@EXAMPLE.COM with the actual Kerberos principal name.

4. Verify the ticket:

   klist
   

   This displays the active Kerberos ticket and confirms that authentication is working correctly.

Troubleshooting and Validation

• List principals on Kerberos server:

  sudo kadmin.local
  listprincs
  

• List principals in keytab file:

  klist -kte /path/to/keytab
  

• Check Kerberos ticket on any machine:

  klist
  

• Verify Db2 config:

  db2 get dbm cfg | grep -i authentication
  

Notes and Best Practices

• Keytab files are only necessary for services (like Db2) to authenticate non-interactively. Users authenticate interactively using kinit.
• Always use fully qualified domain names (FQDN) for principals to avoid hostname mismatches.
• Time synchronization is critical; even a few minutes of drift cause Kerberos authentication failure.
• Protect the keytab file with strict permissions since it contains sensitive credentials.
• Db2 does not support setting the service principal via db2 update dbm cfg; use the environment variable KRB5_KTNAME and ensure the keytab contains the proper principal.