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.

Kerberos configuration for JDBC data sources

You can specify a Kerberos configuration in your server.xml file that provides values to any Open Liberty features that use Kerberos credentials. This configuration is optional. For more information, see Kerberos authentication for Open Liberty.

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 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 is not specified, Open Liberty resolves credential values from the keytab file that is configured in the kerberos element. If no keytab file is configured, Open Liberty resolves credential values from the default Kerberos credential cache location for the Java SDK. For more information, see Kerberos authentication for Open Liberty.

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 version 21c and earlier supports only the Oracle JDK or OpenJDK Kerberos implementations. Therefore, these versions cannot be used with the IBM SDK, Java Technology Edition, Version 8. Update to version 21c or newer of the Oracle JDBC thin driver for support of Kerberos authentication for data sources with IBM Java 8.

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