Goal

The aim of this document is to provide guidance and advice on how to configure Kerberos in the Denodo Platform and how to solve the most common problems when configuring Kerberos.

Kerberos Configuration Guide

Denodo Virtual DataPort (VDP) allows Kerberos authentication not only for accessing the underlying data sources but also for connecting to the VDP Server through Kerberos from any client.

To connect to data sources using Kerberos authentication the configuration steps will be different depending on the data source type:

• JDBC: the section “Connecting to a JDBC Source with Kerberos Authentication” of the Virtual DataPort Administration Guide contains the steps for configuring a JDBC data source in order to use Kerberos credentials at connection time.
• SOAP Web Services: for configuring Kerberos authentication with SOAP web services check the section “Connecting to a SOAP Web Service with Kerberos Authentication” of the Virtual DataPort Administration Guide.
• XML, JSON, Excel and Delimited File data sources: the section “Path Types in Virtual DataPort” of the Virtual DataPort Administration Guide contains the configuration instructions for configuring Kerberos using HTTP as data route for these data sources.

To configure Kerberos for the VDP Server, the section “Setting-up Kerberos Authentication” of the Denodo Platform Installation Guide includes the configuration process of a Kerberos server (Active Directory) before enabling Kerberos in VDP. Once the Kerberos server is configured, the configuration steps for configuring Kerberos in a VDP Server are included in the section “Kerberos authentication” of the Virtual DataPort Administration Guide. Additional steps may be needed to connect to the VDP server depending on the client used to connect:

• Web Design Studio: after configuring Kerberos in the VDP Server some changes must be performed in the Web Design Studio configuration in order to use Kerberos authentication. Local login needs to be used to modify the Kerberos configuration (eg: http://hostname:9090/denodo-design-studio/#/web-local-login). Once logged in, click Configuration > Kerberos settings to fill the Kerberos parameters according to your configuration.
• VDP Administration Tool: after configuring Kerberos in the VDP Server some changes must be performed in the VDP Administration Tool configuration in order to use Kerberos authentication. Check the section “Configuring the Administration Tool to Use Kerberos Authentication” of the Virtual DataPort Administration Guide for further information.
• Data Catalog: You can configure the Data Catalog to use Kerberos to authenticate the users with Virtual DataPort. The section “Setting-up Kerberos Authentication in the Data Catalog” of the Denodo Platform Installation Guide contains the steps for the configuration.
• REST and SOAP web services: the section “Web services authentication” of the Virtual DataPort Administration Guide contains the steps for using HTTP SPNEGO (Kerberos) in the authentication of published web services.
• OData service: the section “Kerberos Authentication” of the VDP Administration Guide contains the steps for using Kerberos in the authentication of the OData service.
• GraphQL service: (Denodo 8 only) the section “Authentication” of the VDP Administration Guide contains the steps for using Kerberos in the authentication of the GraphQL service.
• JDBC: necessary configuration steps can be found in the section “Connecting to Virtual DataPort using Kerberos authentication” of the Virtual DataPort Developer Guide.
• ODBC: the section “Configuration of the ODBC driver in Windows” of the VDP Developer Guide contains the required steps for configuring an ODBC DSN through Kerberos in Windows. The section “Configuration of the ODBC Driver in Linux and Other UNIX” includes the configuration for UNIX systems.
• ADO.NET: the section “Access through an ADO.NET data provider” of the VDP Developer Guide explains how to use Kerberos in an ADO.NET client.

Kerberos Debug Mode

Kerberos Debug Mode in Northbound connections

When configuring Kerberos within your environment it is strongly recommended to enable Kerberos Debug Mode and use the tools listed in the section “Useful tools to debug issues with Active Directory or other LDAP servers” in case that you face any issue.

For enabling the Kerberos Debug Mode in the VDP Administration Tool and in the VDP Server, just follow these steps (only Denodo 8 and Denodo 7 update 20190903 or newer) :

1. Click "Server authentication" on the menu "Administration > Server Configuration", click “Kerberos” tab and select "Activate Kerberos debug mode" and click "Ok".
2. Click "Authentication" on the menu "Tools > Admin tool preferences", select "Activate Kerberos debug mode" and click "Ok".
3. To obtain Kerberos debug messages in the VDP server log, edit the file <DENODO_HOME>/conf/vdp/log4j2.xml and add the following line, below the line <Loggers>

<Logger name="com.denodo.util.logging.JavaConsoleLogging" level="debug" />

4. Restart the VDP Server to apply the Kerberos configuration changes.
5. You will find the Kerberos debug messages in <DENODO_HOME>/logs/vdp/vdp.log
6. To obtain Kerberos debug messages in the VDP Administration Tool log, in the installation of your administration tool (not in the Denodo server) edit the file <DENODO_HOME>/conf/vdp-admin/log4j2.xml and add the following below the line <Loggers>

<Logger name="com.denodo.util.logging.JavaConsoleLogging" level="debug" />

7. Restart the VDP Administration Tool to apply the changes to this file.
8. You will find the Kerberos debug messages in the local file <DENODO_HOME>/logs/vdp-admin/vdp-admin.log.

Note: If you want to enable Kerberos debug mode for Denodo 7 update 20190312 or older or Denodo 6, please check this section of the VDP Administration Guide (for the VDP server) and this one for the VDP Administration Tool, since the instructions may differ from the ones described above.

Kerberos Debug Mode in Southbound connections

For those cases where it is only needed to debug southbound connections, the Kerberos log debugging mode can be enabled by following these steps:

1. Add -Dsun.security.krb5.debug=true to the JVM options of the VDP server. Run the <DENODO_HOME>/bin/regenerateFiles.sh/.bat script from a command line after adding this option..
2. Edit the file <DENODO_HOME>/conf/vdp/log4j2.xml and add the following line right below the line <Loggers>:

3. Restart Virtual DataPort to apply the changes to this file.

You will find the Kerberos debug messages in <DENODO_HOME>/logs/vdp/vdp.log.

For the Web Design Studio, edit the file <DENODO_HOME>/conf/design-studio/DesignStudioBackend.properties and add the following configuration property:

kerberos.debug=true

Then, restart the Denodo embedded web container to apply the change. You will find the Kerberos messages in <DENODO_HOME>/logs/design-studio/design-studio-backend.log.

For the VDP administration tool, you have to edit the file <DENODO_HOME>/conf/vdp-admin/log4j2.xml and do the same change as for the VDP server. Then, restart the administration tool to apply the change. You will find the Kerberos messages in <DENODO_HOME>/logs/vdp-admin/vdp-admin.log.

Kerberos Debug Mode Output

The output of the Kerberos debugging provides a lot of information regarding the authentication process, it is recommended to enable this mode when configuring Kerberos. Hence, if the authentication process does not work as expected the debugging logs can be reviewed in order to gather information about the issue.

Some useful lines that can be searched for in the log are the following:

• Commit Succeeded: This means that VDP Server has been authenticated successfully in the AD, so it is likely that the problem faced will be related to the client configuration.
• Found unsupported keytype (18) for <Kerberos Server principal>: This means that Java Cryptography Extension (JCE) is not installed in the VDP Server.
  Ignore this error if in the Active Directory, the user account created for the Virtual DataPort server has the AES-256 encryption disabled.
  If AES-256 encryption is enabled, we recommend disabling it. If you want to use AES-256, install the JCE in the VDP server and all its clients.
  You will not see this message if the Denodo server runs with the latest update of Java 8 because it already includes the JCE (Denodo 7.0 ships with the latest update of Java 8).

Kerberos Most Common Issues

Kerberos Northbound Most Common Issues

• Server Principal is not correct:

• Error: Error authenticating client with kerberos: No valid credentials provided (Mechanism level: Server not found in Kerberos database (7))
• Sometimes the principal is set looking like a http url: HTTP://host1.subnet1.contoso.com@CONTOSO.COM, but remember that the prefix is “HTTP/” without the colon and the extra slash: HTTP/host1.subnet1.contoso.com@CONTOSO.COM.

• LDAP Data source URI is not correct:

• Error: LDAP: error code 32 - 0000208D
• Usually the URI contains the node of the LDAP where the users should be searched, for instance ldap://ad.denodo.com:389/DC=contoso.com,DC=com, but the suffix DC=contoso.com,DC=com should be instead included in the User base field of the Kerberos configuration, so a correct LDAP Server URI has to be of the form ldap://ad.denodo.com:389/

• The User base configured, for instance “DC=contoso.com,DC=com”, does not contain the username used in the authentication. Note that this node of the Active Directory represents the scope where the users are searched in.

• In order to detect this situation, enable the LDAP logging categories of the section “Debugging the LDAP configuration” within the KB article How to configure a VDP database with LDAP authentication. Then, check in the logs whether the user was found in the LDAP or not.

• Kerberos krb5 configuration file is included though it is not required, this file is needed only under those conditions:

• VDP Server runs on Windows and the host does not belong to a Windows domain.
• VDP Server runs on Linux.
• Kerberos Server does not return “forwardable” tickets by default.

• Role names in VDP does not match LDAP roles:

• VDP is configured for using case insensitive identifiers by default (identifiers charset is Restricted), with this configuration the comparison of roles is case insensitive and when the roles are imported from the LDAP the names are converted to lowercase.
• On the other hand, when the Unicode option is selected for identifiers charset, the comparison will be case sensitive so the role names in Denodo have to match exactly the name of the groups in AD.

• Attribute with user name in the Kerberos configuration does not contain the domain name, but Kerberos authentication uses the name with the domain appended:

• For instance the LDAP attribute sAMAccountName returns user instead of user@CONTOSO.COM. To solve this, a different LDAP attribute which includes the domain appended to the username can be used or check the option “Avoid domain name for authorization” in the Kerberos server configuration wizard.

• The VDP Admin Tool has configured “Use user/password” Kerberos authentication and the file VDBAdminConfiguration.properties includes the property vdbDataSource.vdpAdminDataSource.principal.

• Error: Client not found in Kerberos database (6)
• This property is only required when using “Use ticket cache” and “Use keytab” options so remove the property if it appears in the configuration file.

• VDP Server and/or clients do not join the Kerberos realm but the JVM properties java.security.krb5.realm and java.security.krb5.kdc are not included nor there is a krb5 file.

• These properties need to be included both in server and clients JVM or in the krb5 file.

• The Service Principal Name should be used instead of the user name in the Server principal field of the Kerberos configuration.

• Do not forget to regenerate the keytab for this user account.

• If a keytab file is generated for a user account instead of the SPN, the same user cannot be used for authenticating with the VDP Admin Tool with the option “Use user/password”:

• Error: Pre-authentication information was invalid (24)
• Configure a different user account for the VDP Admin Tool.

• The krb5.conf file is configured for using UDP

• Error: java.net.SocketTimeoutException: Receive timed out
• Sometimes the Kerberos tickets are larger than the maximum packet size sent over UDP so change the configuration of the file in order to use TCP

• The krb5 file does not include the entry "default_domain = CONTOSO.COM" in the realms section.
• The user account that authenticates in the VDP Admin Tool uses a different encryption algorithm that is configured in the keytab:

• Error: Error authenticating user: Failure unspecified at GSS-API level (Mechanism level: Invalid argument (400) - Cannot find key of appropriate type to decrypt AP REP - RC4 with HMAC)
• In case that the VDP Server is placed in a UNIX environment, the same configuration should be applied to the account configuration of the Active Directory for the user configured in the Server principal field of Kerberos.

• The krb5.ini file was not configured to support the encryption level from the System Ticket Cache is stored in.

• Error: authentication error: No valid Kerberos authentication for user: Failure unspecified at GSS-API level (Mechanism level: AES256 CTS mode with HMAC SHA1-96 encryption type not in permitted_enctypes list
• Install the JCE as documented in the section "Installing the Java Cryptography Extension (JCE)" of the Denodo Platform Installation Guide.
• Update krb5.ini file for including specific algorithm and restarting the VDP server.

• Using HTTP SPNEGO, if the Kerberos token sent from the browser is too large it can be rejected by Tomcat’s HTTP connector, remember to do the same for the HTTPS connector if you are using HTTPS:

• Error: HTTP 400 Bad Request
• Change the connector configuration from:
  <Connector port="${com.denodo.tomcat.http.port}"
                maxThreads="150" …. />
  to:
  <Connector port="${com.denodo.tomcat.http.port}" maxHttpHeaderSize="65536"
                maxThreads="150" …

• Specifically for the Solution Manager Web Administration Tool, if the Kerberos Token is still too large after modifying the maxHttpHeaderSize as specified in the previous point, a message  like An error occurred while communicating with the server will pop up when performing Kerberos based Single Sign-On in Solution Manager Web Administration Tool. To solve this problem perform the following steps:

• Backend Error: HTTP 400 Bad Request / Frontend Error: An error occurred while communicating with the server
• Stop the Solution Manager Web Administration Tool, Solution Manager Server and License Manager Server.
• Add the following property in  <SOLUTION_MANAGER_HOME>/conf/solution-manager/SMConfigurationParameters.properties and <SOLUTION_MANAGER_HOME>/conf/license-manager/LMConfigurationParameters.properties file.

        For Denodo 9.0

           server.max-http-request-header-size=65535

        For Denodo 8.0 and 7.0:

        server.max-http-header-size=65535

• Restart the License Manager server, Solution Manager server and Solution Manager Web Administration Tool.

• Using HTTP SPNEGO, the http requests from the browser must contain the Fully Qualified Domain Name:

• In order to authenticate into VDP server, HTTP/<FQDN> must be the Service Principal Name defined in VDP server. The beginning of the requested URLs must follow the pattern http://www.<FQDN> or http://<FQDN> so the browser requests a Kerberos ticket for HTTP/<FQDN>.

• In ODBC client connections, Active Directory is blocking VDP from utilizing the account provided.

• Error: com.denodo.vdb.vdbinterface.server.odbc.ODBCBackend [] - Error: authentication error: No valid Kerberos authentication for user.
• To resolve this, it is needed to adjust the value of userWorkstations attribute in Active Directory in order to enable VDP to access this account.

• In the VDP Administration Tool running on Windows with the Denodo 6 or Denodo 7 update 20190312 or earlier, the option “Use Single Sign-On with system ticket cache” was selected but the Windows Registry was not modified

• Error: GSSException: No valid credentials provided (Mechanism level: Failed to find any Kerberos TGT)
• Modify the Windows Registry in order to make the session key for TGT accessible.

• In Denodo Platform versions up to 6.0, the Java Cryptography Extension (JCE) is required for AES 256 encryption but the extension is not installed:

• Error: GSSException: No valid credentials provided (Mechanism level: Failed to find any Kerberos tgt)
• Install the JCE as documented in the section "Installing the Java Cryptography Extension (JCE)" of the Denodo Platform Installation Guide

Kerberos Southbound Most Common Issues

• With some JDBC data sources, the Denodo VDP server is on a different domain than the Kerberos server but the files core-site.xml, hdfs-site.xml and mapred-site.xml are not included in the classpath:

• Copy the files to <DENODO_HOME>/conf or <DENODO_HOME>/conf/vdp

Finally, remember to restart the VDP Server after applying any configuration change.

References

Setting-up Kerberos Authentication

Kerberos Authentication

Connecting to Virtual DataPort using Kerberos Authentication

How to configure a VDP database with LDAP authentication

Troubleshooting