Database Management

Configure DPA to use Kerberos instead of NTLM to authenticate the DPA server

This article provides instructions for configuring DPA to use Kerberos instead of NTLM. By default, DPA uses NTLM to authenticate the DPA server to monitored database instances.

First published date

10/30/2018 2:34 PM

Last published date

10/24/2026 1:26 AM

Overview

By default, DPA uses NTLM to authenticate the DPA server to monitored database instances. To configure DPA to use Kerberos instead of NTLM, complete the following tasks. 

SolarWinds allows you to configure DPA to use Kerberos. However, SolarWinds Support does not provide configuration assistance.

Product section

Database Performance Analyzer

Resolution

Prerequisites 

  • The DPA server, domain controller, and database server have working DNS resolution and synchronized time.
  • You have not set up DPA for SSO via browser.

Steps 

Task 1: Set up a Kerberos configuration file on the DPA server 

First determine if a Kerberos configuration file already exists on the DPA server. Look for the following are standard file names.

OPERATING SYSTEMPATH AND FILE NAME
Solaris/etc/krb5/krb5.conf
WindowsC:\Windows\krb5.ini
Linux/etc/krb5.conf

If you do not have a Kerberos configuration file on the DPA server, complete the following steps to create one.

  1. In a text editor, create a new file and copy the following text to use as a template:

    # Set defaults
[libdefaults]
    default_realm = {REALM NAME}
    default_tkt_enctypes = rc4-hmac,aes256-cts-hmac-sha1-96,aes128-cts-hmac-sha1-96
    default_tgs_enctypes = rc4-hmac,aes256-cts-hmac-sha1-96,aes128-cts-hmac-sha1-96
    forwardable=true
 
# Define where to find the kerberos server for a particular realm
[realms]
{REALM NAME} = {
    kdc = {ActiveDirectoryServerName.domain.com}
    default_domain = {domain.com}
}
 
# Map subdomains and domain names to Kerberos realm names.
# Individual host names may be specified. Domain suffixes may be
# specified with a leading period and will apply to all host
# names ending in that suffix.
[domain_realm]
    {domain.com} = {REALM NAME}
    {.domain.com} = {REALM NAME}
 
[logging]
#    kdc = CONSOLE
#    kdc = SYSLOG:INFO
#    admin_server = FILE:=/var/kadm5.log

  2. Change the values surrounded by braces: {REALM NAME}, {ActiveDirectoryServerName.domain.com}, and {domain.com}.

    To determine the Realm Name, run the following command on your Active Directory server:

    ksetup

    A typical value for REALM.NAME is your company's domain, such as YOURCOMPANY.COM.

    The Realm Name must be specified in uppercase.

  3. Save the file with the path and file name specified in the table above.

Task 2: Create a service account 

  1. Ask your Active Directory administrator to create a service account in Active Directory. A service account is similar to a regular domain user account, but the password should be set to Never Expire, and the user is not required to change the password on the next login.

    Later in this article, this user is referred to as {Service Account}.

  2. Configure this user in SQL Server to have sufficient permissions to SQL Server permissions for DPA monitoring .

    Later in this article, the computer name is referred to as {SQL Server name} and the SQL Server port is referred to as {SQL Server port}.

  3. On the domain controller, verify that SQL server has registered itself correctly:

    1. Run this command:

      setspn -L  {SQL Server name}

    2. Verify that the following are included in the SPNs:
      • MSSQLSvc/{SQL Server Name}.{Fully Qualified Domain Name}
      • MSSQLSvc/{SQL Server Name}.{Fully Qualified Domain Name}:{SQL Server port}

    3. If you do not see them, add them manually by running the following commands:

      setspn MSSQLSvc/{SQL Server Name}.{Fully Qualified Domain Name} {SQL Server Name}

      setspn MSSQLSvc/{SQL Server Name}.{Fully Qualified Domain Name}:{SQL Server port} {SQL Server Name}

Task 3: Build the ignite.keytab file 

Generate the keytab file that the DPA server will use to authenticate itself to the domain controller. This file contains the private key for the service account and should be protected accordingly.

  1. Choose a {Service account} login name that can be used as the SPN (service principal name). This name cannot conflict with anything already registered in AD as an SPN.

    This name will be referred to as {Service Account Login}.

  2. To generate the file, run the following command from your Active Directory server on a single line:

    ktpass /out .\ignite.keytab /mapuser {Service Account}@{Fully Qualified Domain Name} /princ {Service Account Login}@{REALM NAME} /pass {Service Account Password} /ptype KRB5_NT_PRINCIPAL /crypto ALL

    Notes:

    /princThe value for the /princ parameter is case-sensitive.
    {encryption type}

    Example values for {encryption type} are:

    • ALL
    • RC4-HMAC-NT
    • AES128-SHA1

    If you use AES128-SHA1 encryption, be sure that "This account supports AES 128 bit encryption" is selected for the user account.

    By default, the files bundled in the Java JRE enforce a restriction that limits the maximum key length to 128 bits. To use AES256 encryption, you must install the JCE Unlimited Strength Jurisdiction Policy Files.

  3. Move the keytab file to the DPA server.
    • Do not put the file in a directory inside of the DPA installation directory structure, so you will not have to change paths if you move the DPA installation directory.
    • If your server already has a keytab file, you may want to merge the ignite.keytab file with the existing one.
    • For UNIX, keytab files are typically stored in /etc/krb5.keytab.

Task 4: Create the login.conf file 

  1. In a text editor, create a file with the following content:

    com.sun.security.jgss.krb5.initiate {
   com.sun.security.auth.module.Krb5LoginModule required
   useTicketCache=false
   doNotPrompt=true
   useKeyTab=true
   keyTab="{Path to ignite.keytab}"
   principal="{Service Account Login}@{REALM NAME}"
   storeKey=true
   debug=false;
};

  2. Save the file with the following name and location:

    <DPA_install_directory>/iwc/tomcat/ignite_config/login.conf

Task 5: Edit the system.properties file 

  1. On the DPA server, back up the system.properties file. The system.properties file is in one of the following locations, depending on the operating system on which DPA is installed:
    • Windows: <DPAInstallDir>\iwc\tomcat\ignite_config\idc\system.properties
    • Linux: <DPAInstallDir>/iwc/tomcat/ignite_config/idc/system.properties
  2. Open the system.properties file in a text editor.

  3. Add the following lines to your system.properties file. Replace each placeholder with the applicable absolute path in the environment.

    javax.security.auth.useSubjectCredsOnly=false
    java.security.auth.login.config={Path to login.conf}
    com.confio.ws.ldap.sso.krbConfLocation={Path to krb5.conf}

    Notes:

    • In property values, use ‘/' as the path separator instead of '\’ including on Windows.

    • Ensure that each property is present only once and that the DPA service identity can read login.conf and the Kerberos configuration file.

    Windows example

    The following example assumes that DPA is installed in C:/Program Files/SolarWinds/DPA, login.conf is stored under the DPA installation directory, and the Kerberos configuration file is C:/Windows/krb5.ini.

    javax.security.auth.useSubjectCredsOnly=false
    java.security.auth.login.config=C:/Program Files/SolarWinds/DPA/iwc/tomcat/ignite_config/login.conf
    com.confio.ws.ldap.sso.krbConfLocation=C:/Windows/krb5.ini

    Linux example

    The following example assumes that DPA is installed in /opt/solarwinds/dpa and the Kerberos configuration file is /etc/krb5.conf. Replace these example paths with the paths used in the environment.

    javax.security.auth.useSubjectCredsOnly=false
    java.security.auth.login.config=/opt/solarwinds/dpa/iwc/tomcat/ignite_config/login.conf
    com.confio.ws.ldap.sso.krbConfLocation=/etc/krb5.conf

  4. Save the system.properties file. Continue with Task 6 to restart DPA and apply the configuration changes.

Task 6: Restart DPA 

Restart DPA to apply the changes in the configuration files.

  • On Windows, stop and restart the Ignite PI Server service.
  • On Linux, run the following commands from the DPA directory:
    • shutdown.sh
    • startup.sh

Task 7: Register or update a SQL Server instance to use Kerberos 

Complete the appropriate procedure depending on whether the SQL Server instance is being registered for the first time or is already monitored by DPA. DPA can use either the Microsoft JDBC driver or the jTDS driver. The Connection Properties are different for each driver, so identify the driver first and use only the matching property string.

DriverDriver class stored in repositoryConnection Properties value
Microsoft JDBCcom.microsoft.sqlserver.jdbc.SQLServerDriverauthenticationScheme=JavaKerberos;integratedSecurity=true;jaasConfigurationName=com.sun.security.jgss.krb5.initiate
jTDSnet.sourceforge.jtds.jdbc.DriverintegratedSecurity=true;useKerberos=true

Identify the driver for a new registration

For a new SQL Server registration, DPA selects the driver based on the following property in system.properties:

com.confio.ignite.jdbc.sqlserver.useJtdsDriver=false

  • If the value is false, the new registration uses the Microsoft JDBC driver.
    • If com.confio.ignite.jdbc.sqlserver.useJtdsDriver=false,
       
    • Use the Microsoft JDBC properties:
      authenticationScheme=JavaKerberos;integratedSecurity=true;jaasConfigurationName=com.sun.security.jgss.krb5.initiate
  • If the value is true, the new registration uses the jTDS driver.
    • If com.confio.ignite.jdbc.sqlserver.useJtdsDriver=true, 
       
    • Use the jTDS properties:
      integratedSecurity=true;useKerberos=true
  • If the property is added or changed, restart DPA before registering the instance.
  • This property affects only new registrations. It does not change the driver for an existing monitored instance. 

Identify the driver for an existing monitored instance

Use one of the following methods. The DPA user interface is the recommended customer-facing method because it is the most user-friendly and does not require direct access to the DPA repository.

 Method 1: Use the DPA user interface (recommended)

  1. In DPA, click Options > Update Connection Info.

  2. Select the monitored SQL Server instance and click Next.

  3. If DPA displays an option to switch from jTDS to the Microsoft JDBC driver, the instance is currently using jTDS.

  4. If the switch option is not displayed, the instance is generally using Microsoft JDBC.
     

Method 2: Check system.properties (supporting check)

The com.confio.ignite.jdbc.sqlserver.useJtdsDriver value can also be checked as a supporting reference. However, this is a global driver-selection setting for new registrations. It might not identify the driver currently stored for an existing instance if the instance was registered before the property changed or if its driver was switched later. For an existing instance, we recommend the DPA UI or the repository value when confirmation is required.

Method 3: Query the DPA repository

This method requires direct access to the DPA repository. Run read-only SELECT statements only. Do not modify the ignite.COND table.

To list the monitored database ID, name, and stored driver class, run:

SELECT id, name, JDBC_driver
FROM ignite.COND;

To check a specific monitored instance, filter by database ID or name:

SELECT id, name, JDBC_driver
FROM ignite.COND
WHERE id = <database_id>;

Interpret JDBC_driver as follows:

  • com.microsoft.sqlserver.jdbc.SQLServerDriver indicates Microsoft JDBC.
  • net.sourceforge.jtds.jdbc.Driver indicates jTDS.

Register a new SQL Server instance

  1. In DPA, open the Register Instance wizard and select Microsoft SQL Server.

  2. Enter the connection information for the SQL Server instance. Use the SQL Server fully qualified domain name rather than an IP address so the server name can match the MSSQLSvc service principal name.

  3. Complete the Monitoring User and Password fields with non-empty values if the wizard requires them. When the Kerberos configuration and Connection Properties are active, DPA uses the Kerberos identity for authentication.

  4. In Connection Properties, enter the value for the driver selected for the new registration: Microsoft JDBC or jTDS.

  5. Continue through the wizard and complete the registration.

  6. Confirm that DPA connects to and begins monitoring the SQL Server instance.

Update an existing monitored SQL Server instance

  1. In DPA, click Options > Update Connection Info.

  2. Select the monitored SQL Server instance and click Next.

  3. Identify the current driver. Use the DPA UI as the recommended customer-facing method. Use system.properties only as a supporting check. If confirmation is still required, you can run the read-only ignite.COND query.

  4. In Connection Properties, enter the value for the driver currently used by the monitored instance.

  5. You can leave the Monitoring User and Password values unchanged. These values are not used when Kerberos authentication is active.

  6. Click Next, and then click Update Connection.

  7. Confirm that the connection update succeeds and that DPA continues monitoring the instance.

Verify Kerberos authentication

On the monitored SQL Server, run the following query while DPA is connected:

SELECT 
    s.session_id, 
    s.login_name, 
    s.host_name, 
    s.program_name, 
    c.net_transport, 
    c.auth_scheme 
FROM sys.dm_exec_sessions AS s 
JOIN sys.dm_exec_connections AS c 
  ON c.session_id = s.session_id 
WHERE s.is_user_process = 1 
ORDER BY s.session_id DESC;

Locate the DPA monitoring session. The auth_scheme value should be KERBEROS, and the login should be the configured Kerberos monitoring identity.

Common issues 

The computer name is not properly resolved to the IP address 

Use nslookup to ensure that both the computer name and its IP address are resolved correctly.

While building the ignite.keytab file, an error is returned 

Verify that no error was returned during keytab generation, and that the SPN was set correctly. 

The following is an example of ktpass output with errors:

C:\Users\Administrator>ktpass /out .\DPA_user.keytab /mapuser DPA_user@ignite.local /princ MSSQLSvc/JJ-W-NINER.ignite.local@IGNITE.LOCAL /pass Confio123 /ptype KRB5 _NT_PRINCIPAL /crypto ALL
DsCrackNames returned 0x5 in the name entry for DPA_user@ignite.local.
ktpass:failed getting target domain for specified user.

The following is an example of correct ktpass output:

C:\Users\Administrator>ktpass /out .\DPA_user.keytab /mapuser DPA_user@ignite.local /princ dpa/kerberos@IGNITE.LOCAL /pass Confio123 /ptype KRB5_NT_PRINCIPAL /crypto ALL
Targeting domain controller: {ActiveDirectoryServerName.domain.com}
Successfully mapped dpa/kerberos to DPA_user.
Password successfully set!
Key created.
Key created.
Key created.
Key created.
Key created.
Output keytab to .\DPA_user.keytab:
Keytab version: 0x502
keysize 52 dpa/kerberos@IGNITE.LOCAL ptype 1 (KRB5_NT_PRINCIPAL) vno 20 etype 0x1 (DES-CBC-CRC) keylength 8 (0xc808a145ea01731c)
keysize 52 dpa/kerberos@IGNITE.LOCAL ptype 1 (KRB5_NT_PRINCIPAL) vno 20 etype 0x3 (DES-CBC-MD5) keylength 8 (0xc808a145ea01731c)
keysize 60 dpa/kerberos@IGNITE.LOCAL ptype 1 (KRB5_NT_PRINCIPAL) vno 20 etype 0x17 (RC4-HMAC) keylength 16 (0xdeeb603a6c4d7bf8a30e485abfc6155c)
keysize 76 dpa/kerberos@IGNITE.LOCAL ptype 1 (KRB5_NT_PRINCIPAL) vno 20 etype 0x12 (AES256-SHA1) keylength 32 (0xdb8cf130ca48925b4b1fb26f982429d720f1d6665cf431a6ae1c4d8fe4029440)
keysize 60 dpa/kerberos@IGNITE.LOCAL ptype 1 (KRB5_NT_PRINCIPAL) vno 20 etype 0x11 (AES128-SHA1) keylength 16 (0x39fbfbbb4a11a126eea073da8d3eb627)