Configure Kerberos

Sovereign executors only

Kerberos authentication is only available on sovereign executors. Managed environments don't support Kerberos.

Overview

Knime executes workflows that may try to access Kerberos-secured services such as Apache Hive™, Apache Impala™ and Apache Hadoop® HDFS™.

This guide describes how to configure your sovereign executors so that they can authenticate against Kerberos.

If you are using Kerberos authentication, you need to use user scope for deployments. Team scope is not supported with Kerberos authentication.

Prerequisites

Setting up Knime for Kerberos authentication has the following prerequisites:

For Kerberos:
- An existing Kerberos KDC such as MIT Kerberos or Microsoft ActiveDirectory
- A service principal for your Knime instance. The recommended format is knimehub/<host>@<REALM>, where:
  - <host> is the fully-qualified domain name of the machine where your sovereign executor runs,
  - <REALM> is the Kerberos realm.
- A keytab file for the Knime service principal.
- A Kerberos client configuration file (krb5.conf). Alternatively, it can be created manually (see section Setting up krb5.conf).
For Knime:
- An existing Knime instance.
- A sovereign execution environment to run the workflows that access Kerberos-secured services.

Setting up `krb5.conf`

The Knime execution context might need to read the krb5.conf file during Kerberos authentication. In that case, a valid krb5.conf file needs to be obtained. In case the location of the file is unknown or the file is not available, please contact the local administrator.

Creating `krb5.conf` file

Alternatively, a krb5.conf file can be created manually. A minimal configuration file could look like this:

ini

[libdefaults]
default_realm = MYCOMPANY.COM
forwardable = true
udp_preference_limit = 1

[realms]
MYCOMPANY.COM = {
  kdc = kdc.mycompany.com
  admin_server = kdc.mycompany.com
}

The above example declares that the Kerberos realm is called MYCOMPANY.COM and that the hostname of the Kerberos KDC is kdc.mycompany.com.
The forwardable flag is a prerequisite for some Knime nodes to make use of Kerberos constrained delegation when executed on Knime. The udp_preference_limit variable value set to 1 is to ensure that when sending a message to the KDC, the library will try using TCP over UDP connection.

Adjust the values contained in the krb5.conf file as appropriate for the setup in use. Depending on the specific setup, more configuration settings may be necessary. The krb5.conf format is fully described as part of the MIT Kerberos documentation.

Knime preferences

You need to first create an .epf preference file that will contain the Kerberos configuration preferences. The table below contains all supported Kerberos configuration options.

/instance/org.knime.kerberos/org.knime.kerberos.conf=<VALUE>

specifies the Kerberos configuration options. Replace <VALUE> with:

FILE: to use Kerberos client configuration file (krb5.conf).
DEFAULT: to use system defaults (discouraged).

REALM_KDC: to provide realm and KDC directly in the preferences file.

Preference	Description	Applies to
`/instance/org.knime.kerberos/org.knime.kerberos.authMethod=<VALUE>`	Specifies the Kerberos authentication method. Replace `<VALUE>` with: • `KEYTAB`: to use keytab and service principal (recommended for executors) • `USER_PWD`: to use username and password	All configurations
`/instance/org.knime.kerberos/org.knime.kerberos.debug=<true\|false>`	Specifies whether to enable Kerberos debug.	All configurations
`/instance/org.knime.kerberos/org.knime.kerberos.conf.file=<PATH>`	Specifies the location to `krb5.conf` file. Replace `<PATH>` with the path to `krb5.conf`.	Only applies if `FILE` is selected in the option above.
`/instance/org.knime.kerberos/org.knime.kerberos.kdc=<KDC_VALUE>`	Specifies KDC value. Replace `<KDC_VALUE>` with the IP or hostname of the KDC.	Only applies if `REALM_KDC` is selected in the first option listed above.
`/instance/org.knime.kerberos/org.knime.kerberos.realm=<REALM_VALUE>`	Specifies Realm value. Replace `<REALM_VALUE>` with the name of the realm (the name needs to be in uppercase letters).	Only applies if `REALM_KDC` is selected in the first option listed above.
`/instance/org.knime.kerberos/org.knime.kerberos.keytabFile=<PATH_TO_KEYTAB>`	Specifies the location to the keytab file. The keytab must not be stored in the profile folder, but needs to be present on the Knime executor machine(s) so that the preferences can reference it by local path.	Only applies if `KEYTAB` is selected as authentication method.
`/instance/org.knime.kerberos/org.knime.kerberos.keytabPrincipal=<PRINCIPAL_VALUE>`	Specifies the keytab service principal value.	Only applies if `KEYTAB` is selected as authentication method.
`/instance/org.knime.kerberos/org.knime.kerberos.debugLogLevel=<LOG_LEVEL>`	Specifies the log level if Kerberos debug is enabled. Replace `<LOG_LEVEL>` with either `WARN`, `DEBUG` or `ERROR`.	Only applies if Kerberos debug is enabled.

For example, a recommended Kerberos configurations for Knime executors could look like the following:

/instance/org.knime.kerberos/org.knime.kerberos.conf=FILE
/instance/org.knime.kerberos/org.knime.kerberos.conf.file=${profile:location}/krb5.conf
/instance/org.knime.kerberos/org.knime.kerberos.authMethod=KEYTAB
/instance/org.knime.kerberos/org.knime.kerberos.keytabFile=<PATH_TO_KEYTAB>
/instance/org.knime.kerberos/org.knime.kerberos.keytabPrincipal=<PRINCIPAL_VALUE>

Replace <PATH_TO_KEYTAB> with the path to the keytab file and <PRINCIPAL_VALUE> with the service principal. The keytab must not be stored in the profile folder, but needs to be present on the Knime executor machine(s) so that the preferences can reference it by local path.

Apply the profile to executors

Repeat the following steps on each executor machine:

Create a parent folder for your profiles, for example /opt/knime/profiles. Inside it, create a subfolder for the Kerberos profile: /opt/knime/profiles/kerberos.
Copy the following files into /opt/knime/profiles/kerberos:
- preferences.epf, which contains the preferences from Knime preferences
- krb5.conf, if you set org.knime.kerberos.conf to FILE
Copy the keytab file to the path you set in org.knime.kerberos.keytabFile. Store it outside the profile folder.
Open the knime.ini file in the executor's installation directory. Add the following lines right before the -vmargs line:
text
```
-profileLocation
/opt/knime/profiles
-profileList
kerberos
```
-profileLocation takes the parent folder from step 1, and -profileList takes the name of the profile subfolder. Put each flag and each value on its own line. These are launcher arguments, so they don't work below -vmargs.
Restart the executor agent so that the executor loads the profile.

On Windows, use forward slashes in the path, for example C:/knime/profiles with the profile in C:/knime/profiles/kerberos. To apply several profiles, list their subfolder names separated by commas, for example kerberos,drivers. If several profiles set the same preference, the last profile in the list wins.

Kerberos constrained delegation

With Kerberos constrained delegation, Knime runs database operations on behalf of the user who runs the workflow, instead of the executor's service principal. This is also called user impersonation. It works with Kerberos-secured databases such as Apache Hive, Apache Impala, Microsoft SQL Server, Oracle Database, and PostgreSQL.

Before you start, configure your executors to obtain a Kerberos ticket as described in Knime preferences. Then enable constrained delegation for each JDBC driver with one of the following methods:

Default JDBC parameters: Inject a JDBC parameter into every connection a workflow creates. Some drivers only need the name of the user to impersonate, which you pass with the context.workflow.username context property. Other drivers need the delegated GSS credential, which you pass with the DELEGATED_GSS_CREDENTIAL value type. For details, see Default JDBC Parameters.
Service ticket delegation: Let the executor request a Kerberos service ticket on behalf of the workflow user, using the MS-SFU Kerberos 5 extension. Use this method when the driver has no dedicated delegation parameter.
Connection initialization statement: Run an SQL statement when the connection opens. Some databases, such as Exasol, support impersonation this way.

Add the preferences from the following examples to the .epf file in your customization profile. If you use your own JDBC driver instead of a built-in one, replace the driver ID in each preference with the ID of your driver. For details, see JDBC drivers on Knime Hub and Knime Server.

Default JDBC parameters

If the driver accepts a dedicated impersonation parameter, add the following preferences. Replace <DRIVER_ID> with the ID of your driver and <IMPERSONATION_PARAM> with the name of the driver's impersonation parameter:

text

/instance/org.knime.database/drivers/<DRIVER_ID>/attributes/additional/org.knime.database.util.DerivableProperties/knime.db.connection.jdbc.properties/<IMPERSONATION_PARAM>/type=CONTEXT_PROPERTY
/instance/org.knime.database/drivers/<DRIVER_ID>/attributes/additional/org.knime.database.util.DerivableProperties/knime.db.connection.jdbc.properties/<IMPERSONATION_PARAM>/value=context.workflow.username
/instance/org.knime.database/drivers/<DRIVER_ID>/attributes/reserved/*/knime.db.connection.jdbc.properties/<IMPERSONATION_PARAM>=true

For example, the embedded Apache Hive driver uses hive.server2.proxy.user, and the proprietary Cloudera drivers use DelegationUID.

Service ticket delegation

To request a service ticket, the executor needs the service name and the fully qualified hostname of the database. To set the service name, add the following preference and replace <VALUE> with the name of the service:

text

/instance/org.knime.database/drivers/<DRIVER_ID>/attributes/additional/java.lang.String/knime.db.connection.kerberos_delegation.service/value=<VALUE>

Dedicated connector nodes pass the hostname automatically. For the generic DB Connector node, Knime extracts the hostname from the JDBC URL with the regular expression .*(?:@|/)([^:;,/\\]*).*, which works for most JDBC URLs. To use a different expression, add the following preference. Replace <VALUE> with a regular expression whose first group matches the hostname:

text

/instance/org.knime.database/drivers/<DRIVER_ID>/attributes/additional/java.lang.String/knime.db.connection.kerberos_delegation.host_regex/value=<VALUE>

Connection initialization statement

To impersonate the workflow user with an SQL statement, set a connection initialization statement that uses the context.workflow.username variable. For example, to run IMPERSONATE ${context.workflow.username}; on Exasol, add the following preference:

text

/instance/org.knime.database/drivers/<DRIVER_ID>/attributes/additional/java.lang.String/knime.db.connection.init_statement/value=IMPERSONATE ${context.workflow.username};

Example: Apache Hive

The setup for Apache Hive depends on the JDBC driver you use. You can use the embedded open-source Apache Hive JDBC driver or the proprietary Simba-based driver from Cloudera.

Register the proprietary Hive driver

Skip this step if you use the embedded Apache Hive JDBC driver. To register the proprietary driver:

Download the Hive JDBC driver from the Cloudera website.
Add HiveJDBC41.jar from the downloaded package to your customization profile.

Add the following preferences to the .epf file:

text

/instance/org.knime.database/drivers/cloudera_hive/database_type=hive
/instance/org.knime.database/drivers/cloudera_hive/driver_class=com.cloudera.hive.jdbc41.HS2Driver
/instance/org.knime.database/drivers/cloudera_hive/paths/0=${profile:location}/HiveJDBC41.jar
/instance/org.knime.database/drivers/cloudera_hive/url_template=jdbc:hive2://<host>:<port>/[database]
/instance/org.knime.database/drivers/cloudera_hive/version=2.6.0

Enable user impersonation on Hive

For the embedded Apache Hive JDBC driver, add the following preferences:

text

/instance/org.knime.database/drivers/hive/attributes/additional/org.knime.database.util.DerivableProperties/knime.db.connection.jdbc.properties/hive.server2.proxy.user/type=CONTEXT_PROPERTY
/instance/org.knime.database/drivers/hive/attributes/additional/org.knime.database.util.DerivableProperties/knime.db.connection.jdbc.properties/hive.server2.proxy.user/value=context.workflow.username
/instance/org.knime.database/drivers/hive/attributes/reserved/*/knime.db.connection.jdbc.properties/hive.server2.proxy.user=true

For the proprietary Simba-based driver, add the following preferences:

text

/instance/org.knime.database/drivers/cloudera_hive/attributes/additional/org.knime.database.util.DerivableProperties/knime.db.connection.jdbc.properties/DelegationUID/type=CONTEXT_PROPERTY
/instance/org.knime.database/drivers/cloudera_hive/attributes/additional/org.knime.database.util.DerivableProperties/knime.db.connection.jdbc.properties/DelegationUID/value=context.workflow.username
/instance/org.knime.database/drivers/cloudera_hive/attributes/reserved/*/knime.db.connection.jdbc.properties/DelegationUID=true

Example: Apache Impala

User impersonation on Apache Impala requires the proprietary Impala JDBC driver from Cloudera. The embedded open-source Apache Hive JDBC driver for Impala doesn't support user impersonation. To register the proprietary driver and enable user impersonation:

Download the Impala JDBC driver from the Cloudera website.
Add ImpalaJDBC41.jar from the downloaded package to your customization profile.

Add the following preferences to the .epf file:

text

/instance/org.knime.database/drivers/cloudera_impala/database_type=impala
/instance/org.knime.database/drivers/cloudera_impala/driver_class=com.cloudera.impala.jdbc.Driver
/instance/org.knime.database/drivers/cloudera_impala/paths/0=${profile:location}/ImpalaJDBC41.jar
/instance/org.knime.database/drivers/cloudera_impala/url_template=jdbc:impala://<host>:<port>/[database]
/instance/org.knime.database/drivers/cloudera_impala/version=2.6.0
/instance/org.knime.database/drivers/cloudera_impala/attributes/additional/org.knime.database.util.DerivableProperties/knime.db.connection.jdbc.properties/DelegationUID/type=CONTEXT_PROPERTY
/instance/org.knime.database/drivers/cloudera_impala/attributes/additional/org.knime.database.util.DerivableProperties/knime.db.connection.jdbc.properties/DelegationUID/value=context.workflow.username
/instance/org.knime.database/drivers/cloudera_impala/attributes/reserved/*/knime.db.connection.jdbc.properties/DelegationUID=true

The last three preferences set the JDBC DelegationUID parameter, which enables user impersonation. To connect without impersonating workflow users, remove them.

Example: Microsoft SQL Server

The Microsoft SQL Server JDBC driver requires a special license agreement, so Knime provides it as a separate plug-in. To install it, see Third-party Database Driver Plug-in.

To enable constrained delegation for the built-in driver, add the following preference:

text

/instance/org.knime.database/drivers/built-in-mssqlserver-9.4.0/attributes/additional/org.knime.database.util.DerivableProperties/knime.db.connection.jdbc.properties/gsscredential/type=DELEGATED_GSS_CREDENTIAL

In the Microsoft SQL Server Connector node, make the following settings:

Set Authentication to Kerberos.
In the JDBC Parameters tab, add the following parameters:
text
```
authenticationScheme=JavaKerberos
integratedSecurity=true
```

To set these parameters for all connections instead, add the following preferences:

text

/instance/org.knime.database/drivers/built-in-mssqlserver-9.4.0/attributes/additional/org.knime.database.util.DerivableProperties/knime.db.connection.jdbc.properties/authenticationScheme/type=literal
/instance/org.knime.database/drivers/built-in-mssqlserver-9.4.0/attributes/additional/org.knime.database.util.DerivableProperties/knime.db.connection.jdbc.properties/authenticationScheme/value=JavaKerberos
/instance/org.knime.database/drivers/built-in-mssqlserver-9.4.0/attributes/additional/org.knime.database.util.DerivableProperties/knime.db.connection.jdbc.properties/integratedSecurity/type=literal
/instance/org.knime.database/drivers/built-in-mssqlserver-9.4.0/attributes/additional/org.knime.database.util.DerivableProperties/knime.db.connection.jdbc.properties/integratedSecurity/value=true

For more information, see the Microsoft SQL Server documentation on constrained delegation.

Example: Oracle Database

The Oracle JDBC driver requires a special license agreement, so Knime provides it as a separate plug-in. To install it, see Third-party Database Driver Plug-in.

To enable constrained delegation for the built-in driver, add the following preference:

text

/instance/org.knime.database/drivers/built-in-oracle-19.14.0/attributes/additional/java.lang.String/knime.db.connection.kerberos_delegation.service/value=oracle

Knime doesn't use the service name for Oracle Database. Any non-empty value enables constrained delegation.

In the Oracle Connector node, set the authentication method to Kerberos. In the JDBC Parameters tab, add the parameter oracle.net.authentication_services with the value (KERBEROS5), including the brackets.

Example: PostgreSQL

To enable constrained delegation for the built-in PostgreSQL driver, add the following preference:

text

/instance/org.knime.database/drivers/built-in-postgres-42.3.5/attributes/additional/java.lang.String/knime.db.connection.kerberos_delegation.service/value=postgres

The default service name for PostgreSQL is postgres. If your database uses a different service name, replace postgres with it.

With Kerberos authentication, the PostgreSQL JDBC driver logs in with the operating system user by default, which fails for workflows that run on an executor. Depending on your database configuration, set the user name to one of the following:

The Kerberos principal name including the realm, for example User@REALM.COM
The Kerberos principal name without the realm
The context.workflow.username context property

To use the principal name including the realm, add the following preference:

text

/instance/org.knime.database/drivers/built-in-postgres-42.3.5/attributes/additional/org.knime.database.util.DerivableProperties/knime.db.connection.jdbc.properties/user/type=GSS_PRINCIPAL_NAME

To use the principal name without the realm, add the following preference:

text

/instance/org.knime.database/drivers/built-in-postgres-42.3.5/attributes/additional/org.knime.database.util.DerivableProperties/knime.db.connection.jdbc.properties/user/type=GSS_PRINCIPAL_NAME_WITHOUT_REALM

To use the name of the workflow user, add the following preferences:

text

/instance/org.knime.database/drivers/built-in-postgres-42.3.5/attributes/additional/org.knime.database.util.DerivableProperties/knime.db.connection.jdbc.properties/user/type=CONTEXT_PROPERTY
/instance/org.knime.database/drivers/built-in-postgres-42.3.5/attributes/additional/org.knime.database.util.DerivableProperties/knime.db.connection.jdbc.properties/user/value=context.workflow.username

Configure Kerberos ​

Overview ​

Prerequisites ​

Setting up krb5.conf ​

Creating krb5.conf file ​

Knime preferences ​

Apply the profile to executors ​

Kerberos constrained delegation ​

Default JDBC parameters ​

Service ticket delegation ​

Connection initialization statement ​

Example: Apache Hive ​

Register the proprietary Hive driver ​

Enable user impersonation on Hive ​

Example: Apache Impala ​

Example: Microsoft SQL Server ​

Example: Oracle Database ​

Example: PostgreSQL ​

Configure Kerberos

Overview

Prerequisites

Setting up `krb5.conf`

Creating `krb5.conf` file

Knime preferences

Apply the profile to executors

Kerberos constrained delegation

Default JDBC parameters

Service ticket delegation

Connection initialization statement

Example: Apache Hive

Register the proprietary Hive driver

Enable user impersonation on Hive

Example: Apache Impala

Example: Microsoft SQL Server

Example: Oracle Database

Example: PostgreSQL