Content Platform Engine, Version 5.2.1            

Kerberos prerequisites

Since Kerberos can be difficult to get working correctly, the first step is to make sure that a number of prerequisites are met.

A running, non-Kerberos setup of Content Platform Engine prerequisite

The Content Platform Engine that you wish to configure for Kerberos authentication must be in a working state, meaning it has already been installed and configured (without Kerberos), and can be run successfully. You must be able to start the Administration Console for Content Platform Engine and log in with a username and password.

System prerequisites

Only Windows clients can use Kerberos authentication, although either Windows or non-Windows Content Platform Engine server systems can accept Kerberos credentials. Windows-based Content Platform Engine server systems must use Windows 2003 or later. .NET clients should use Windows 2000 or later systems. Earlier versions of Windows, such as Windows NT® or Windows 98, do not support Kerberos.

Regardless of whether you use Windows or non-Windows Content Platform Engine servers you must use Windows Active Directory as your directory service.

Domain and account prerequisites

A Windows client system needs to be in a domain (not a workgroup) and the user needs to be logged on as some type of domain account. You must log on using a domain account. Logging on a Windows client system as a local account will not work.

All of the client systems should be in the same domain unless you follow the steps described in Cross-realm Kerberos authentication.

The Content Platform Engine server system will need network access to the Active Directory system. A Windows server system can be a member of some domain or may be in a Window's workgroup as long as it has access to the Active Directory. If authenticating cross-realm, that is, when clients can be in domains other than that of the SPN identity account's domain, then it will be helpful if the Content Platform Engine server system is a member of the SPN identity account's domain (see Cross-realm Kerberos authentication).

Stand-alone .NET client prerequisites

A .NET stand-alone client needs at least .NET 1.1 and WSE 2.0 installed on the Windows system, although .NET 2.0 and WSE 3.0 (or later) configured for WCF are recommended.

Content Platform Engine Java server prerequisites
  1. Content Platform Engine needs at least the 1.6 Java™ runtime environment (JRE), but it is recommended that the equivalent Java™ Development Kit (JDK) be installed to make use of some debugging utilities. Although not required, the JAVA_HOME environment variable can be set to allow the Java tools in the JDK to be accessed on Windows systems, as in this example:
    set JAVA_HOME=e:\j2sdk1.5.0_36
    %JAVA_HOME%\bin\ktab
  2. The Java virtual machine (JVM) requires that there be a Kerberos configuration file specifying such values as the following:
    [libdefaults]
      default_realm = MYDOM.EXAMPLE.COM
      kdc_timesync = 1
      ccache_type = 4
      forwardable = true
      proxiable = false
      default_tgs_enctypes = des-cbc-md5 des-cbc-crc
      default_tkt_enctypes = des-cbc-md5 des-cbc-crc
    
    [realms]
      MYDOM.EXAMPLE.COM = {
        kdc = mydomainsys:88
        admin_server = mydomainsys
        default_domain = mydom.example.com
      }
    
    [domain_realm]
      .mydom.example.com = MYDOM.EXAMPLE.COM
      mydom.example.com = MYDOM.EXAMPLE.COM

    This sample uses DES encryption security. RC4-HMAC security can also be used but will require that Content Platform Engine be running either on a WebSphere 6 or WebLogic with Java 6 (or later) platform. See Using RC4-HMAC Security.

    Be careful of upper / lower case use in this file. Realm names should always be upper case (MYDOM.EXAMPLE.COM) and Windows domain names should always be lower case (mydom.example.com).

    A sample of this file can be found at installdir\FileNet\ContentEngine\Kerberos\krb5.ini that you must edit for the particular installation. The Kerberos realm values (equivalent to Windows domains) should be adjusted as well as the kdc(Kerberos Key Distribution Center, which is the Primary Domain Controller on Windows systems) and admin_server values.

    If the Content Platform Engine server's Java Virtual Machine (JVM) is 1.5, this file should be saved on Windows systems in the c:\winnt\krb5.ini file, even if Windows is installed in c:\WINDOWS or is on some other drive. A 1.6 or later JVM should place this file in the Windows system directory (for example, c:\WINDOWS). An alternative to using c:\winnt\krb5.ini (or c:\WINDOWS\krb5.ini ) is to save the file elsewhere and specify its location as an argument when starting up the JVM, as in:

    -Djava.security.krb5.config="c:/ce/config/krb/krb5.conf"

    On non-Windows servers, this file should be /etc/krb5/krb5.conf and on Linux®, this file should be /etc/krb5.conf. Non-Windows systems may also use the -Djava.security.krb5.config argument to specify another location.

    In multiple-domain situations, the kbr5.ini (or krb5.conf ) file should specify the SPN identity account's domain/realm and need not specify those of the client systems. See Cross-realm Kerberos authentication .

  3. Microsoft increased security in Windows 2000 SP4, Windows XP SP2 and Windows 2003 and in doing so broke Java's ability to use the system's cached Kerberos Ticket Granting Tickets (TGTs) for integrated logins. This can be patched by running <installdir>\FileNet\Content Engine\Kerberos\AllowTgtSessionKey_fix_for_Krb5LoginModule.reg. This uses RegEdit to add a new value to the Windows system registry which will disable the new security feature. This registry edit can also be used harmlessly on early Windows Service Packs.
  4. Windows 2008 R2 and later servers do not support DES by default and using RC4-HMAC is recommended for those servers. If the lesser strength DES must be used, it can be enabled by following the directions in Microsoft's KB977321.
  5. DES encryption will also no longer work in Active Directory 2003 domains after a Windows 2008 R2 domain controller joins. This must be fixed by installing the Microsoft hotfix KB978055.
Middleware, Web application servers

In general Kerberos is not supported in those cases where a .NET stand-alone client is going through a Web application layer before going to the Content Platform Engine server. The problem is that the Web application layer must typically do actions for (impersonate) any number of users. This impersonation is possible, but doing so is beyond the scope of this topic.

The exception to this rule is that browser-based clients can use SPNEGO authentication (which uses either Kerberos or NTLM authentication) and connect to a Web application, which in turn calls Content Platform Engine. This will work because the application server itself uses Kerberos to authenticate the user and then this identity is propagated to Content Platform Engine using container-managed authentication. Setup for this scenario is beyond the scope of this topic.



Last updated: March 2016
p8psn021.htm

© Copyright IBM Corporation 2016.