Kerberos authentication details

Kerberos description and introduction

Kerberos is a third party network authentication protocol that employs a system of shared secret keys to securely authenticate a user in an unsecured network environment. A three-tiered system is used in which encrypted tickets (provided by a separate server called the Kerberos Key Distribution Center, or KDC for short) are exchanged between the application server and client rather than a text user ID and password pair. These encrypted service tickets (called credentials) have a finite lifetime and are only understood by the client and the server. This reduces the security risk, even if the ticket is intercepted from the network. Each user, or principal in Kerberos terms, possesses a private encryption key that is shared with the KDC. Collectively, the set of principals and computers registered with a KDC are known as a realm.

A key feature of Kerberos is that it permits a single sign-on environment whereby a user only needs to verify his identity to the resources within the Kerberos realm once. When working with DB2 database, this means that a user is able to connect or attach to a DB2 database server without providing a user ID or password. Another advantage is that the user ID administration is simplified because a central repository for principals is used. Finally, Kerberos supports mutual authentication which allows the client to validate the identity of the server.

Kerberos set-up

DB2 database system and its support of Kerberos relies upon the Kerberos layer being installed and configured properly on all machines involved prior to the involvement of DB2 database. This includes, but is not necessarily limited to, the following requirements:

1. The client and server machines and principals must belong to the same realm, or else trusted realms (or trusted domains in the Windows terminology)
2. Creation of appropriate principals
3. Creation of server keytab files, where appropriate
4. All machines involved must have their system clocks synchronized (Kerberos typically permits a 5 minute time skew, otherwise a preauthentication error may occur when obtaining credentials).

For details on installing and configuring Kerberos please refer to the documentation provided with the installed Kerberos product.

The sole concern of DB2 database system will be whether the Kerberos security context is successfully created based on the credentials provided by the connecting application (that is, authentication). Other Kerberos features, such as the signing or encryption of messages, will not be used. Furthermore, whenever available, mutual authentication will be supported.

The Kerberos prerequisites are as follows:

• For the AIX, Solaris operating environment, and Linux platforms, the IBM® Network Authentication Service (NAS) Toolkit v1.4 or higher is required. You can download NAS Toolkits at https://www.ibm.com/services/forms/preLogin.do?source=dm-nas
• For the Windows platforms, there are no prerequisites.

Kerberos and client principals

The principal may be found in either a 2-part or multi-part format, (that is, name@REALM or name/instance@REALM). As the "name" part will be used in the authorization ID (AUTHID) mapping, the name must adhere to the DB2 database naming rules. This means that the name may be up to 30 characters long and it must adhere to the existing restrictions on the choice of characters used. (AUTHID mapping is discussed in a later topic.)

The principal itself must be capable of obtaining outbound credentials with which it may request and receive service tickets to the target database. This is normally accomplished with the kinit command on UNIX or Linux, and is done implicitly at logon time on Windows.

Kerberos and authorization ID mapping

Unlike operating system user IDs, whose scope of existence is usually restricted to a single machine, Kerberos principals have the ability to be authenticated in realms other than their own. The potential problem of duplicated principal names is avoided by using the realm name to fully qualify the principal. In Kerberos, a fully qualified principal takes the form name/instance@REALM where the instance field may actually be multiple instances separated by a "/", that is, name/instance1/instance2@REALM, or it may be omitted altogether. The obvious restriction is that the realm name must be unique within all the realms defined within a network. For the DB2 database manager to provide a simple mapping from the principal to the AUTHID, a one-to-one mapping between the principal name, that is, the "name" in the fully qualified principal, and the AUTHID is desirable. A simple mapping is needed because the AUTHID is used as the default schema by the DB2 database manager and should be easily and logically derived. As a result, the database administrator needs to be aware of the following potential sources of confusion:

• Principals with the same name but from different realms will be mapped to the same AUTHID.
• Principals with the same name but on different instances will be mapped to the same AUTHID.

Giving consideration to the above, the following recommendations are made:

• Maintain an unique namespace for the name within all the trusted realms that will access the DB2 database server
• All principals with the same name, regardless of the instance, should belong to the same user.

Kerberos and server principals

On UNIX or Linux, the server principal name for the DB2 database instance is assumed to be <instance name>/<fully qualified hostname>@REALM. This principal must be able to accept Kerberos security contexts and it must exist before starting the DB2 database instance since the server name is reported to DB2 database by the plugin at initialization time.

On Windows, the server principal is taken to be the domain account under which the DB2 database service started. An exception to this is the instance may be started by the LocalSystem account, in which case, the server principal name is reported as host/<hostname>; this is only valid if both the client and server belong to Windows domains.

Windows does not support greater than 2-part names. This poses a problem when a Windows client attempts to connect to a UNIX server. As a result, a Kerberos principal to Windows account mapping may need to be set up in the Windows domain if interoperability with UNIX Kerberos is required. (Please refer to the appropriate Microsoft documentation for relevant instructions.)

You can override the Kerberos server principal name used by the DB2 server on UNIX and Linux operating systems. Set the DB2_KRB5_PRINCIPAL environment variable to the desired fully qualified server principal name. The instance must be restarted because the server principal name is only recognized by the DB2 database system after db2start is run.

Kerberos keytab files

Every Kerberos service on UNIX or Linux wishing the accept security context requests must place its credentials in a keytab file. This applies to the principals used by DB2 database as server principals. Only the default keytab file is searched for the server's key. For instructions on adding a key to the keytab file, please refer to the documentation provided with the Kerberos product.

There is no concept of a keytab file on Windows and the system automatically handles storing and acquiring the credentials handle for a principal.

Kerberos and groups

Kerberos is an authentication protocol that does not possess the concept of groups. As a result, DB2 database relies upon the local operating system to obtain a group list for the Kerberos principal. For UNIX or Linux, this requires that an equivalent system account should exist for each principal. For example, for the principal name@REALM, DB2 database collects group information by querying the local operating system for all group names to which the operating system user name belongs. If an operating system user does not exist, then the AUTHID will only belong to the PUBLIC group. Windows, on the other hand, automatically associates a domain account to a Kerberos principal and the additional step to create a separate operating system account is not required.

Enabling Kerberos authentication on the client

The clnt_krb_plugin database manager configuration parameter should be updated to the name of the Kerberos plugin being used. On the supported platforms this should be set to IBMkrb5. This parameter will inform DB2 database that it is capable of using Kerberos for connections and local instance-level actions if the AUTHENTICATION parameter is set to KERBEROS or KRB_SERVER_ENCRYPT. Otherwise, no client-side Kerberos support is assumed.

Optionally, when cataloging a database on the client, an authentication type may be specified:

   db2 catalog db testdb at node testnode authentication kerberos target 
      principal service/host@REALM

However, if the authentication information is not provided, then the server sends the client the name of the server principal.

Enabling Kerberos authentication on the server

The srvcon_gssplugin_list database manager configuration parameter should be updated with the server Kerberos plugin name. Although this parameter may contain a list of supported plugins, only one Kerberos plugin may be specified. However, if this field is blank and AUTHENTICATION is set to KERBEROS or KRB_SERVER_ENCRYPT, the default Kerberos plugin (IBMkrb5) is assumed and used. Either the AUTHENTICATION or SVRCON_AUTH parameter should be set to KERBEROS or KRB_SERVER_ENCRYPT if Kerberos authentication is to be used depending upon whether it is used for everything or just for incoming connections.

Creating a Kerberos plugin

There are several considerations you should consider when creating a Kerberos plugin:

• Write a Kerberos plugin as a GSS-API plugin with the notable exception that the plugintype in the function pointer array returned to DB2 database in the initialization function must be set to DB2SEC_PLUGIN_TYPE_KERBEROS.
• Under certain conditions, the server principal name may be reported to the client by the server. As such, the principal name should not be specified in the GSS_C_NT_HOSTBASED_SERVICE format (service@host), since DRDA® stipulates that the principal name be in the GSS_C_NT_USER_NAME format (server/host@REALM).
• In a typical situation, the default keytab file may be specified by the KRB5_KTNAME environment variable. However, as the server plugin will run within a DB2 database engine process, this environment variable may not be accessible.

zSeries and System i compatibility

For connections to zSeries and System i®, the database must be cataloged with the AUTHENTICATION KERBEROS parameter and the TARGET PRINCIPAL parameter name must be explicitly specified.

Neither zSeries nor System i support mutual authentication.

Windows issues

When you are using Kerberos on Windows platforms, you need to be aware of the following issues:

• Due to the manner in which Windows detects and reports some errors, the following conditions result in an unexpected client security plug-in error (SQL30082N, rc=36):
  • Expired account
  • Invalid password
  • Expired password
  • Password change forced by administrator
  • Disabled account

  Furthermore, in all cases, the DB2 administration log or the db2diag log files will indicate "Logon failed" or "Logon denied".

• If a domain account name is also defined locally, connections explicitly specifying the domain name and password will fail with the following error: The Local Security Authority cannot be contacted.

  The error is a result of Windows locating the local user first. The solution is to fully qualify the user in the connection string. For example: name@DOMAIN.IBM.COM

• Windows accounts cannot include the @ character in their name because the character is assumed to be the domain separator by the DB2 Kerberos plug-in.
• When interoperating with a non-Windows platform, ensure that all Windows domain server accounts and all Windows client accounts are configured to use DES encryption. If the account used to start the DB2 service is not configured to use DES encryption, the DB2 server will fail to accept Kerberos contexts. In particular, DB2 will fail with an unexpected server plug-in error, and will log that the AcceptSecurityContext API returned SEC_I_CONTINUE_NEEDED (0x00090312L).

  To determine if Windows accounts are configured to use DES encryption, look under Account properties in the Active Directory. A restart might be required if the account properties are changed.

• If the client and server are both on Windows, then the DB2 service can be started under the LocalSystem account. However, if the client and server are in different domains, the connection might fail with an invalid target principal name error. The workaround is to explicitly catalog the target principal name on the client using the fully qualified server host name and the fully qualified domain name, in the following format: host/server hostname@server domain name

  For example: host/myhost.domain.ibm.com@DOMAIN.IBM.COM

  Otherwise, you must start the DB2 service under a valid domain account.