Using Kerberos Authentication

Kerberos authentication is a trusted third-party authentication service. Kerberos authentication can take advantage of the user name and password maintained by the operating system to authenticate users to the database or use another set of user credentials specified by the application.

DB2

Oracle

Microsoft SQL Server

Sybase

Verify that your environment meets the requirements listed in Table 7-2 before you configure DataDirect XQuery for Kerberos authentication.

Table 7-2. Kerberos Authentication Requirements
Component	Requirements
Database server	The database server must be running one of the following databases: DB2: DB2 v8.1 or higher for Linux/UNIX/Windows Oracle: Oracle 11g Oracle 10g (R1 and R2) Microsoft SQL Server: Microsoft SQL Server 2008 Microsoft SQL Server 2005 Microsoft SQL Server 2000 Microsoft SQL Server 2000 Enterprise Edition (64-bit) Service Pack 2 or higher Sybase: Sybase 12.5.1 or higher
Kerberos server	The Kerberos server is the machine where the user IDs for authentication are administered. The Kerberos server is also the location of the Kerberos Key Distribution Center (KDC). If using Windows Active Directory, this machine is also the domain controller. DB2, Oracle, and Sybase: Network authentication must be provided by one of the following methods: Windows Active Directory on one of the following operating systems: Windows Server 2003 Windows 2000 Server Service Pack 3 or higher MIT Kerberos 1.4.2 or higher Microsoft SQL Server: Network authentication must be provided by Windows Active Directory on one of the following operating systems: Windows Server 2003 Windows 2000 Server Service Pack 3 or higher

Configuring Kerberos Authentication

During installation, DataDirect XQuery installs the following files required for Kerberos authentication in the /lib subdirectory of your DataDirect XQuery installation directory:

krb5.conf is a Kerberos configuration file containing values for the Kerberos realm and the KDC name for that realm. DataDirect XQuery installs a generic file that you must modify for your environment.

JDBCDriverLogin.conf file is a configuration file that specifies which Java Authentication and Authorization Service (JAAS) login module to use for Kerberos authentication. This file is configured to load automatically unless the java.security.auth.login.config system property is set to load another configuration file. You can modify this file, but DataDirect XQuery must be able to find the JDBC_DRIVER_01 entry in this file or another specified login configuration file to configure the JAAS login module. Refer to your J2SE documentation for information about setting configuration options in this file

Set the AuthenticationMethod connection property to kerberos. See the DB2, Oracle, Microsoft SQL Server, and Sybase connection properties tables in Database Connection Properties for more information about setting a value for this property.

Modify the krb5.conf file to contain your Kerberos realm name and the KDC name for that Kerberos realm by editing the file with a text editor or by specifying the system properties, java.security.krb5.realm and java.security.krb5.kdc.

NOTE: If using Windows Active Directory, the Kerberos realm name is the Windows domain name and the KDC name is the Windows domain controller name.

For example, if your Kerberos realm name is XYZ.COM and your KDC name is kdc1, your krb5.conf file would look like this:

[libdefaults]

default_realm = XYZ.COM

[realms]

XYZ.COM = {

kdc = kdc1

}

If the krb5.conf file does not contain a valid Kerberos realm and KDC name, an exception is thrown.

If using Kerberos authentication with a Security Manager on a Java 2 Platform, you must grant security permissions to the application and DataDirect XQuery. See Permissions for Kerberos Authentication for an example.

Permissions for Kerberos Authentication

Using DataDirect XQuery on a Java 2 Platform with the standard Security Manager enabled requires certain permissions to be set in the security policy file of the Java 2 Platform. This security policy file can be found in the jre/lib/security subdirectory of the Java 2 Platform installation directory.

NOTE: Web browser applets running in the Java 2 plug-in are always running in a JVM with the standard Security Manager enabled.

To run an application on a Java 2 Platform with the standard Security Manager, use the following command:

Refer to your Java 2 Platform documentation for more information about setting permissions in the security policy file.

To use Kerberos authentication with DataDirect XQuery, the application and code bases must be granted security permissions in the security policy file of the Java 2 Platform as shown in the following examples.

DB2

grant codeBase "file:/install_dir/lib/-" { 
   permission java.lang.RuntimePermission "getProtectionDomain"; 
   permission java.util.PropertyPermission "java.security.krb5.conf", "read"; 
   permission java.util.PropertyPermission "java.security.auth.login.config",
      "read", "write"; 
   permission javax.security.auth.AuthPermission 
      "createLoginContext.JDBC_DRIVER_01"; 
   permission javax.security.auth.AuthPermission 
      "createLoginContext.DDTEK-JDBC"; 
   permission javax.security.auth.AuthPermission "doAs"; 
   permission javax.security.auth.kerberos.ServicePermission 
      "krbtgt/your_realm@your_realm", "initiate"; 
   permission javax.security.auth.kerberos.ServicePermission 
      "principal_name/db_hostname@your_realm", "initiate"; 
};

principal_name is the service principal name registered with the Kerberos Key Distribution Center (KDC) that identifies the database service.

your_realm is the Kerberos realm (or Windows Domain) to which the database host machine belongs.

Oracle

grant codeBase "file:/install_dir/lib/-" { 
 permission java.lang.RuntimePermission "getProtectionDomain"; 
   permission java.util.PropertyPermission "java.security.krb5.conf", "read"; 
   permission java.util.PropertyPermission "java.security.auth.login.config",
      "read", "write"; 
   permission javax.security.auth.AuthPermission 
      "createLoginContext.JDBC_DRIVER_01"; 
   permission javax.security.auth.AuthPermission 
      "createLoginContext.DDTEK-JDBC"; 
   permission javax.security.auth.AuthPermission "doAs"; 
   permission javax.security.auth.kerberos.ServicePermission 
      "krbtgt/your_realm@your_realm", "initiate"; 
   permission javax.security.auth.kerberos.ServicePermission 
      "principal_name/db_hostname@your_realm", "initiate"; 
};

your_realm is the Kerberos realm (or Windows Domain) to which the database host machine belongs.

principal_name is the service principal name registered with the Kerberos Key Distribution Center (KDC) that identifies the database service.

Microsoft SQL Server

grant codeBase "file:/install_dir/lib/-" { 
   permission java.lang.RuntimePermission "getProtectionDomain"; 
   permission java.util.PropertyPermission "java.security.krb5.conf", "read"; 
   permission java.util.PropertyPermission "java.security.auth.login.config",
      "read", "write"; 
   permission javax.security.auth.AuthPermission 
      "createLoginContext.JDBC_DRIVER_01"; 
   permission javax.security.auth.AuthPermission 
      "createLoginContext.DDTEK-JDBC"; 
   permission javax.security.auth.AuthPermission "doAs"; 
   permission javax.security.auth.kerberos.ServicePermission 
      "krbtgt/your_realm@your_realm", "initiate"; 
   permission javax.security.auth.kerberos.ServicePermission 
      "MSSQLSvc/db_hostname:SQLServer_port@your_realm", "initiate"; 
};

your_realm is the Kerberos realm (or Windows Domain) to which the database host machine belongs.

SQLServer_port is the TCP/IP port on which the Microsoft SQL Server instance is listening.

Sybase

grant codeBase "file:/install_dir/lib/-" { 
permission java.lang.RuntimePermission "getProtectionDomain"; 
   permission java.util.PropertyPermission "java.security.krb5.conf", "read"; 
   permission java.util.PropertyPermission "java.security.auth.login.config",
      "read", "write"; 
   permission javax.security.auth.AuthPermission 
      "createLoginContext.JDBC_DRIVER_01"; 
   permission javax.security.auth.AuthPermission 
      "createLoginContext.DDTEK-JDBC"; 
   permission javax.security.auth.AuthPermission "doAs"; 
   permission javax.security.auth.kerberos.ServicePermission 
      "krbtgt/your_realm@your_realm", "initiate"; 
   permission javax.security.auth.kerberos.ServicePermission 
      "principal_name/db_hostname@your_realm", "initiate"; 
};

your_realm is the Kerberos realm (or Windows Domain) to which the database host machine belongs.

principal_name is the service principal name registered with the KDC that identifies the database service.

Specifying User Credentials with Kerberos Authentication

By default, when Kerberos authentication is used, DataDirect XQuery takes advantage of the user name and password maintained by the operating system to authenticate users to the database. By allowing the database to share the user name and password used for the operating system, users with a valid operating system account can log into the database without supplying a user name and password.

There may be times when you want to use another set of user credentials. For example, many application servers or Web servers act on behalf of the client user logged on the machine on which the application is running, rather than the server user.

If you want to use user credentials other than the server user’s operating system credentials, include code in your application to obtain and pass a javax.security.auth.Subject used for authentication as shown in the following example.

import javax.security.auth.Subject; 
import javax.security.auth.login.LoginContext; 
 
import javax.xml.xquery.*; 
import com.ddtek.xquery.xqj.DDXQDataSource; 
 
//  The following code creates a javax.security.auth.Subject instance 
//  used for authentication. Refer to the Java Authentication  
//  and Authorization Service documentation for details on using a  
//  LoginContext to obtain a Subject. 
  
LoginContext lc = null; 
Subject subject = null; 
  
try { 
    lc = new LoginContext("JaasSample", new TextCallbackHandler()); 
    lc.login(); 
    subject = lc.getSubject(); 
}  
catch (Exception le) { 
    ... // display login error 
} 
  
DDXQDataSource xqDataSource = new DDXQDataSource(); 
 
//  This application passes the javax.security.auth.Subject 
//  to the driver by executing the driver code as the subject 
  
XQConnection con =  
   (XQConnection) Subject.doAs(subject, new PrivilegedExceptionAction() { 
      public Object run() { 
        XQConnection con = null; 
        try { 
         xqDataSource.setProperty(DDXQDataSource.JDBCURL, 
           "jdbc:xquery:db2://myServer:50000;databaseName=jdbc"); 
         con = xqDataSource.getConnection(); 
        } 
        catch (Exception except) { 
         ... //log the connection error 
         return null; 
        } 
         
        return con; 
      } 
   }); 
  
//  This application now has a connection that was authenticated with  
//  the subject. The application can now use the connection. 
 
XQExpression xqExpression = con.createExpression(); 
String  xquery = "for $holding in collection('holdings')/holdings  
                  return $holding"; 
XQSequence   xqSequence = xqExpression.executeQuery(xquery); 
  
... // do something with the results

Obtaining a Kerberos Ticket Granting Ticket

To use Kerberos authentication, the application user first must obtain a Kerberos Ticket Granting Ticket (TGT) from the Kerberos server. The Kerberos server verifies the identity of the user and controls access to services using the credentials contained in the TGT.

If the application uses Kerberos authentication from a Windows client, the application user does not need to explicitly obtain a TGT. Windows Active Directory automatically obtains a TGT for the user.

If the application uses Kerberos authentication from a UNIX or Linux client, the user must explicitly obtain a TGT. To explicitly obtain a TGT, the user must log onto the Kerberos server using the kinit command. For example, the following command requests a TGT from the server with a lifetime of 10 hours, which is renewable for 5 days:

Refer to your Kerberos documentation for more information about using the kinit command and obtaining TGTs for users.