Kerberos authentication for JDBC data sources

Kerberos is a network authentication protocol through which a client and server can authenticate one another by communicating with a trusted third-party Key Distribution Center (KDC). You can configure your Open Liberty server to use Kerberos credentials to authenticate to a database that is backed by a Java Database Connectivity (JDBC) data source.

Applications that run on an Open Liberty server might need to access protected resources in a database, such as user account information or sales transaction records. In cases where such a database is protected by Kerberos authentication, your Open Liberty server can supply the necessary credentials to access protected resources and confirm the authenticity of the database.

Global Kerberos configuration for Open Liberty

Kerberos authentication in Open Liberty builds on the Kerberos Login Module and Java Generic Security Service (JGSS) API that are provided by the JDK.

The optional kerberos element provides configuration options for any Open Liberty features that use Kerberos credentials. If you have any Kerberos-enabled features configured for your server, you can specify this element in your server.xml file, as shown in the following example:

<featureManager>
  <feature>jdbc-4.2</feature>
</featureManager>

<kerberos keytab="${server.config.dir}/security/krb5.keytab" configFile="${server.config.dir}/security/krb5.conf"/>

This example shows a Kerberos configuration for the Java Database Connectivity feature. Several different features support the kerberos element. To determine whether a feature supports this element, see the feature documentation.

The keytab and configFile attributes are both optional. If you don’t specify these attributes, Open Liberty resolves their values according to the following priority:

  1. The default locations that are defined by the JDK, such as the {user.home}/krb5.keytab file or a location that is specified by JDK-defined system properties

  2. The default locations that are defined by the operating system, such as the /etc/krb5.keytab file or a location that is specified by operating system-defined environment variables

On the Windows operating system, the default Kerberos configuration file name is krb5.ini. On other operating systems, the file name is krb5.conf.

Kerberos configuration for JDBC data sources

To configure Kerberos authentication for JDBC data sources, you must enable the Java Database Connectivity feature. For more information about JDBC data source connections, see Data source configuration. After the Kerberos global configuration is defined, a Kerberos principal can be configured on an authData element in the server.xml file, as shown in the following example:

<authData id="myKerberosAuth" krb5Principal="krbUser" krb5TicketCache="${server.config.dir}/security/krb5cc_krbUser"/>

<library id="db2DriverLib">
  <fileset dir="${server.config.dir}/db2"/>
</library>

<dataSource jndiName="jdbc/krb/basic" containerAuthDataRef="myKerberosAuth">
  <jdbcDriver libraryRef="${server.config.dir}/db2DriverLib"/>
  <properties.db2.jcc databaseName="${DB2_DBNAME}" serverName="${DB2_HOSTNAME}" portNumber="${DB2_PORT}"/>
</dataSource>

The krb5TicketCache attribute is optional. If this attribute isn’t specified, Open Liberty checks the default Kerberos credential cache location of the JDK or the operating system. The containerAuthDataRef attribute references the authData element to authenticate the database connection.

To enable portability of the configuration, the values for the databaseName, serverName, and portNumber properties are supplied by variables. For more information, see Variable substitution precedence.

Optionally, you can specify the recoveryAuthDataRef attribute on the dataSource element to use alternative values for the krb5Principal and krb5TicketCache attributes for authentication during XA recovery. If the recoveryAuthDataRef attribute isn’t specified, the authData element that is referenced by the containerAuthDataRef attribute is used for authentication during XA recovery.

The Oracle JDBC thin driver supports only the Oracle JDK or OpenJDK Kerberos implementations. If you are using the Oracle JDBC thin driver with the IBM SDK, Java Technology Edition, Version 8, you cannot authenticate with Kerberos.

Compatibility with SPNEGO authentication

Open Liberty also supports SPNEGO authentication for web authentication and JDBC data source authentication. The kerberos element is optional, but can be used to customize keytab file and configFile file locations that are used for SPNEGO authentication.

You aren’t required to configure the containerAuthDataRef or recoveryAuthDataRef attributes on your datasource element to use SPNEGO authentication with a JDBC data source. However, if you use an XA-capable data source with SPNEGO authentication, you must configure a non-SPNEGO recoveryAuthDataRef value on the data source because SPNEGO authentication cannot be used for automatic XA recovery.

For example, the following configuration enables a JDBC data source to use SPNEGO authentication to an IBM Db2 data source:

<featureManager>
  <feature>jdbc-4.2</feature>
  <feature>spnego-1.0</feature>
  <feature>appSecurity-2.0</feature>
</featureManager>

<spnego servicePrincipalNames="HTTP/my.spnego.server.com" authFilterRef="myAuthFilter"/>
<authFilter id="myAuthFilter">
  <requestUrl urlPattern="/MySpnegoServlet" matchType="contains"/>
</authFilter>

<kerberos keytab="${server.config.dir}/security/krb5.keytab" configFile="${server.config.dir}/security/krb5.conf"/>

<library id="db2DriverLib">
  <fileset dir="${server.config.dir}/db2"/>
</library>

<dataSource jndiName="jdbc/spnegoAuth">
  <jdbcDriver libraryRef="db2DriverLib"/>
  <properties.db2.jcc databaseName="${DB2_DBNAME}" serverName="${DB2_HOSTNAME}" portNumber="${DB2_PORT}"/>
</dataSource>

See also