Setting-up Kerberos Authentication

Several modules of the Denodo Platform support Kerberos authentication:

  • The Virtual DataPort server
  • The Information Self-Service Tool
  • The Diagnostic and Monitoring Tool
  • The Scheduler server and administration tool

Before enabling this support, you have to perform these tasks:

  1. Configure the Kerberos authentication server to be able to authenticate the Virtual DataPort server and its users.
  2. If necessary, install the “Unlimited Strength Policy Files” for the Java Cryptography Extension (JCE). This section explains when that is necessary.
  3. Optionally, modify the Windows registry to use the native ticket cache so the user does not have to enter her credentials when opening the administration tool.

After performing these steps, you have to configure the Virtual DataPort server and its clients to use Kerberos authentication. The section Kerberos Authentication of the Virtual DataPort Administration Guide explains how to do this.

Configuring the Kerberos Authentication Server (e.g. Active Directory)

You need to perform the following tasks on the Kerberos server, which on a Windows environment is Active Directory:

  1. Create a user in the Kerberos server of type “User”.
  2. Declare a Service Principal Name (SPN) and associate it with the user of the Virtual DataPort server.
  3. Generate a keytab file.

Creating a User in the Active Directory

Create a user account in the Active Directory. The Virtual DataPort server will use this user to authenticate itself so it can provide Kerberos authentication to its users.

You have to create a user (not a Machine or a Computer) and we recommend doing it with the options This account supports AES 128 bit encryption and Passwod never expires. Below, you can find the explanation for this recommendation. You have to do this from the host of the Active Directory.


To create a user called denodo_server, follow these steps:

  1. Launch the tool Active Directory Users and Computers tool (Programs > Administrative Tools).

  2. Right click the Users node and select New > User (do not select Machine nor Computer).

  3. Enter denodo_server in the “Full Name” and the “Logon name” fields.

  4. Click Next and enter a password.

  5. Locate denodo_server in the “Users” tree, in the left side pane and double-click it.

  6. Click the “Account” tab of denodo_server and in the Account options, select this:

    • We recommend selecting Password never expires. Otherwise, you will have to reconfigure and restart the Virtual DataPort server every time the password expires.

    • Regarding encryption mechanisms, we recommend selecting This account supports AES 128 bit encryption and clearing This account supports AES 256 bit encryption and clearing Use Kerberos DES encryption types for this account.

      If you select This account supports AES 256 bit encryption, the encryption level is higher, but you will have to install the Unlimited Strength Policy Files for the “Java Cryptography Extension” (JCE) in:

      • All the clients that connect to Virtual DataPort using the JDBC driver.
      • And in all the hosts that have an administration tool.
      • And in the host that runs the Virtual DataPort server.

      The reason you have to install this package to use AES 256 is that Java, by default, does not support this level of encryption due to export regulations.

      Using AES 128 bit encryption does not require installing this package.

Active Directory User Configuration (Account tab)

Active Directory User Configuration (Account tab)

Declaring a Service Principal Name (SPN)

A Service Principal Name (SPN) is a unique identifier for a service running on a server. SPNs are used by Kerberos authentication to associate a service instance with a service logon account.

Use the setspn utility to declare an SPN and associate it with the user account that was created in the previous step.

Syntax of the setspn utility
setspn -S HTTP/<Fully Qualified Domain Name> <REALM>\<server account>

For example,

setspn -S HTTP/denodo-prod.subnet1.contoso.com@CONTOSO.COM CONTOSO.COM\denodo_server

To run this command, you need to be a domain administrator user.

If setspn returns an error like “Duplicate SPN found, aborting operation!”, it means this SPN is already registered, either on this account or another one. The SPN you use for Kerberos authentication of the Denodo servers cannot be associated with more than one user account. If it is, this authentication will not work. You have to either choose another SPN or delete this SPN first.

Consider the following:

  • The SPN has to comply with the following two rules. Otherwise, the Kerberos authentication will not work on web services, nor in the Information Self-Service Tool nor in the Diagnostic and Monitoring Tool, nor in the Scheduler administration tool.

    1. The host name (in this example “host1.subnet1.contoso.com”) has to be the Fully Qualified Domain Name (FQDN) of the host where the Virtual DataPort server runs or in case of a cluster of Denodo servers, the FQDN of the load balancer.
    2. The “service class” of the SPN has to be HTTP, except for the Scheduler server (it could be any string, for instance, SCHED).

    When web browsers request a Kerberos ticket, they do it for the service “HTTP/<host name of the URL you are accessing>” (the browser forms the SPN with “HTTP” even if you use the protocol “https”). The SPN of this ticket has to match the SPN that the Denodo servers will use; otherwise the authentication will fail.

  • SPNs are case insensitive when used by Microsoft Windows-based computers. However, Linux/Unix is case-sensitive and require the proper case to function properly. So when you create the SPN and configure the Virtual DataPort server, always enter the names with the proper case. That is, the host name in lower case (e.g. denodo-prod.subnet1.contoso.com) and the domain name in upper case (e.g. CONTOSO.COM).

  • If your organization uses Microsoft Active Directory 2003 or earlier, you will not be able to use the -S switch because it is not available for that version. If that is the case, replace -S with -a.

See the documentation of setspn.

See what a Fully Qualified Domain Name is at https://en.wikipedia.org/wiki/Fully_qualified_domain_name.

Generating a Keytab File

Generate a keytab file for the Virtual DataPort server. A keytab file contains pairs of Kerberos principals and encrypted keys derived from the Kerberos password.

Once it is generated, you will have to copy it to the hosts where the Denodo servers run.

To generate the keytab, use the ktpass utility, which is included in Windows Server.

Syntax of the ktpass utility
ktpass /out denodo.keytab /princ <SPN with FQDN>@<REALM> /mapUser
<server Active Directory account> /crypto ALL -pass *
/ptype KRB5_NT_PRINCIPAL

For example:

Example of generating a keytab file
ktpass /out denodo.keytab /princ HTTP/denodo-prod.subnet1.contoso.com@CONTOSO.COM
/mapuser denodo_server /pass * /crypto ALL /ptype KRB5_NT_PRINCIPAL

You have to execute this in the host of the Active Directory. Only domain administrator users can run it. Then, copy keytab to the host where the Denodo servers run.

See more about this utility in its documentation .


After running setspn and ktpass, the configuration of the user account in Active Directory changes in two ways:

  1. In the Account tab, the field User logon name changes to the Service Principal Name (before, it was just the name user account).
  2. There is a new tab: Delegation. If you are going to use “pass-through session credentials” on the data sources that support it, select one of these:
    • Trust this user for delegation to any service.
    • Trust this user for delegation to specified services only. If you select this, you have to do this:
      1. Select Use any authentication protocol. Otherwise, the pass-through session credentials of Kerberos will not work.
      2. In Services to which this account can present delegated credentials, add the Service Principal Names of the databases and web services that you want Denodo to access on behalf of users.

Important

If you select Trust this user for delegation to specified services only, you are enabling what it is called “constrained delegation”.

In this case, the queries sent to Virtual DataPort could fail if they involve a JDBC data source with the authentication option “pass-through session credentials” and the driver does not support Kerberos authentication with constrained delegation. Read the section Connecting to a JDBC Source with Kerberos Authentication of the Administration Guide to check if in your scenario, you can enable this option.

In order to use “constrained delegation”, Java 8 is required. Otherwise, an error java.security.PrivilegedActionException: java.lang.ClassNotFoundException: com.sun.security.jgss.ExtendedGSSCredential will be shown.

Active Directory User Configuration (Delegation tab)

Active Directory User Configuration (Delegation tab)

Installing the “Unlimited Strength Policy Files” for the Java Cryptography Extension (JCE)

Jump to the next task if in Active Directory, you did not select the option This account supports AES 256 bit encryption in the configuration of the user account.

If you did, install the “Unlimited Strength Policy Files” for the Java Cryptography Extension (JCE). To do this, follow these steps:

  1. Download the Unlimited strength JCE package for Java 7.

    Although the Denodo Platform includes Java 7, you can configure it to run with Java 8. In that case, download this package for Java 8 instead.

  2. Make a copy of the original JCE policy files (US_export_policy.jar and local_policy.jar of the folder <DENODO_HOME>/jre/lib/security/). This will allow reverting to the original policy versions.

  3. Copy the jar files included the downloaded file to <DENODO_HOME>/jre/lib/security

    Note

    If you configured Denodo to run with a JRE other than the one included by Denodo, copy these files to the lib\security folder of JRE you are using, instead of to the Denodo’s JRE.

Important

You need to install this in:

  • The host where the Virtual DataPort server runs.
  • All the clients that connect to Virtual DataPort using the JDBC driver.
  • In all the hosts that have an administration tool.
  • And in the host that runs the Virtual DataPort server.

You do not need to install it in the hosts of the clients that connect to the ODBC interface or from a browser (e.g. clients of the Information Self-Service Tool).

Modifying the Windows Registry to Use the Native Ticket Cache

The Virtual DataPort administration tool provides “Single Sign-on” (SSO), which means that the users do not need to enter their password to log in.

If the administration tool runs on Windows and you want to use this feature, you have to modify the Windows registry of the host where the tool runs. That way, the tool will be able to obtain the Kerberos ticket that the system acquired when you logged in to the system. The reason for having to modify the registry to use SSO is that Microsoft added a new feature in which they no longer export the session keys for Ticket-Granting Tickets (TGTs). As a result, the native TGT obtained on Windows has an “empty” session key and null EType.

You do not have to do anything to use single sign-on on Linux or to connect to the Denodo server using the ODBC driver.

Jump to the next task if you are not going to use “single sign-on” or the administration tool runs on Linux.

Note that you can use Kerberos authentication without modifying the registry by providing the user and the password when you log in. This is what you do when selecting Use user/password of the Kerberos authentication options of the administration tool.

To modify the registry, follow these steps:

  1. Run regedit.exe
  2. Look for the key HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos\Parameters
  3. Right-click the “Parameters” node and click New > DWORD.
  4. Enter the name of the entry: allowtgtsessionkey.
  5. Double click on the new entry and set the value to 1 (0x00000001)

Important

You have to do this in all these hosts:

  • All the hosts where Virtual DataPort administration tools run and whose users want to use Kerberos authentication.
  • All the hosts where JDBC clients run and want to use Kerberos authentication.

You have to do this when the client runs on Windows because, as explained in the Troubleshooting page for Kerberos authentication of the Java Runtime Environment, Windows does not give access to the session key of a Ticket-Granting Ticket (TGT) by defaults. This change in the registry will make the session key for TGT accessible, so Java can use it to acquire additional service tickets.

Even if you modify the registry, if the user that starts the administration tool belongs to the group “local administrator” of that computer, the tool will not be able to retrieve the Kerberos ticket from the system. This will make the single sign-on to fail. If that is the case, use the options Use user/password or Use ticket cache of the Kerberos authentication options of the administration tool.

The information provided in this section also applies to the Denodo JDBC driver.