Kerberos support is available to clients of the Content Engine Web Services API, the Content Engine .NET API, and the Content Engine COM API. This support includes the Enterprise Manager and Capture applications. Many third-party COM and Web-service-based applications are also available that can take advantage of this Kerberos support.
Content Engine running on Windows servers can use Kerberos for single sign-on (SSO) authentication. This is also known as "integrated login" since Content Engine takes advantage of an earlier Windows login to securely establish a user’s identity without asking the user for a password again.
Kerberos facilitates user authentication over an untrusted network of disparate systems. One feature of Kerberos allows the issuing of a service ticket that can be used to authenticate a client with a particular service. In short, the client contacts a Key Distribution Center (KDC), which is a domain controller (DC) on a Windows system, and asks for a ticket to a service with some Service Principal Name (SPN). The KDC knows everyone’s password keys and uses the client’s key to decrypt the request, and then uses the SPN's key to encrypt the service ticket, which it passes back to the client.
The KDC also creates a short-term "session" key specifically for this ticket which can be used by both the client and the service. The client passes this ticket plus some additional encrypted timestamp information to the service, which then uses its own password key to decrypt parts of the ticket, learns the name of the client and also checks the timestamp information for the integrity of ticket, thus authenticating the client if everything is okay. These service tickets are good for some period of time, typically 8 or 10 hours, and can be reused by the client anytime during that period that it needs to authenticate itself to the service.
See also the "Kerberos Credentials" section of Web-Services-Based Client Authentication Via Ws-Security.
Since Kerberos can be difficult to get working correctly, the first step is to make sure that a number of prerequisites are met.
Only Windows clients can use Kerberos authentication, although either Windows or UNIX Content Engine server systems can accept Kerberos credentials. Content 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 UNIX Content Engine servers you must use Windows Active Directory as your directory service. In the Windows case, each Content Engine server must be the member of an Active Directory domain.
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.
NOTE You must log on using a domain account. Logging on a Windows client system as a local account will not work.
A Windows server system also needs to be a member of some domain (not a workgroup), but there is no restriction on whether the logged on account is in the domain or local. UNIX servers need only access to Active Directory.
The client system and the Content Engine server system should be in the same domain (or, in the case of UNIX servers, access the same Active Directory) unless the steps described in Cross-Realm Kerberos authentication have been followed.
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) are recommended.
1. Content Engine needs at least the 1.4.2 Java™ runtime environment (JRE), but it is recommended that the 1.4.2 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 follows:
set JAVA_HOME=e:\j2sdk1.4.2_11
%JAVA_HOME%\bin\ktab
2. The Java virtual machine (JVM) requires that there be a Kerberos configuration file specifying such values as the following samples:
[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.mycompany.com
}
[domain_realm]
.mydom.mycompany.com = MYDOM.MYCOMPANY.COM
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.
On Windows systems, except for the cases described in the IMPORTANT note below, this must be saved in the c:\winnt\krb5.ini file. Use c:\winnt even if Windows is installed in c:\windows or some other drive. An alternative 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:/cemp/config/krb/krb5.conf
IMPORTANT: With Sun JDK 1.6 and Oracle JRocket JDK 1.6, krb5.ini must be located
in the Windows %Systemroot%
location. (The default for %Systemroot%
is c:\windows.)
On UNIX this file should be /etc/krb5/krb5.conf and on Linux®, this file should be /etc/krb5.conf.
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.
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 Engine server. The problem is that the Web application layer must typically do actions for (impersonate) any number of users. This impersonation is not supported by .NET’s WSE 2.0 API and is not supported in the current release.
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 Engine. This will work because the application server itself uses Kerberos to authenticate the user and then this identity is propagated to Content Engine. Setup for this scenario is beyond the scope of this topic, but see WebLogic’s Configuring Single Sign-On with Microsoft Clients: http://e-docs.bea.com/wls/docs81/secmanage/sso.html.
A Kerberos Service Principal Name (SPN) is simply a name chosen to represent some service (Content Engine on a particular server in our case). The SPNs used by Content Engine should always be in one of these two:
FNCEWS/cemp01
FNCEWS/cemp01@MYDOM.EXAMPLE.COM
The leading FNCEWS is the Content Engine service name and is needed on all its SPNs. The other parts of the SPN show where the Content Engine server resides, as a simple DNS name or a simple DNS name qualified with a domain.
As an example, the Content Engine server undistinguished DNS name (the host name) might be MYCEMP01 and its domain might be MYDOM.EXAMPLE.COM. In this case the two SPNs would be:
FNCEWS/mycemp01
FNCEWS/my cemp01@MYDOM.EXAMPLE.COM
The host name should always be lower case and the domain name always upper case. Windows systems are mostly case-insensitive but not everything is, so care should be used to always use the proper case.
The SPN “identity” is a Windows domain user account that has been mapped to the SPN. This special user account has a password and from that the Key Distribution Center (KDC) derives a key, which will be used to encrypt parts of the Kerberos ticket. This key is a shared secret that is known only to the KDC, which issues Kerberos tickets, and to the service itself (Content Engine in this case).
With these definitions of SPN and the identity account, this brings up a number of questions and their answers…
How does the client know what the SPN is? In the case of Enterprise Manager, it derives this from the URL it uses to connect to the Content Engine server. If that URL is, for instance, http://mysvr:9080/wsi/FNCEWS40SOAP, it uses an SPN of FNCEWS/mysvr. If the URL is, http://mysrv.mydom.example.com:9080/wsi/FNCEWS40SOAP, it uses FNCEWS/mysvr@MYDOM.EXAMPLE.COM. Other .NET clients are use a simple algorithm like this or directly specify the SPN.
How does the KDC know about the SPN and how does it know what key to use with that? The answer, on Windows systems, is that there must be one domain user account set up (with some password, of course), this user account must be specifically mapped to one or more SPNs and that account provides the key. The KDC is referred to on Windows systems as a Domain Controller.
How does the Content Engine server know what its SPN is? Well it actually does not need to know this, but it can figure out the name of the identity user account by using FNCEWS_ + host_name (for example, FNCEWS_mycemp01 for our example Content Engine server named MYCEMP01 ). If some other identity user account name must be used for some reason, as it would if this server was a member of a cluster, the name can be directly specified by the serviceAccountName option (see “KrbServiceLoginModule Options” and “Using Kerberos with a Cluster of Content Engine Servers”).
How does the Content Engine server know what key to use for decrypting its part of a Kerberos ticket? It does this by logging on to the identity user account by using the password stored in a keytab, a special Kerberos table of users and their passwords. This special login gets the Kerberos Ticket Granting Ticket (TGT), which in turn gives the server access to its key.
The following steps of making an SPN Identity are not trivial, partly because Windows allows Kerberos interoperability with Java and UNIX, but has never tried to make it user friendly.
As mentioned earlier the SPNs should be in the form
FNCEWS/host_name
FNCEWS/host_name@DOMAIN.COM
where you should substitute your own Content Engine name for host_name and that server's domain for DOMAIN.COM. The host name should be an undistinguished (i.e., no dots in it) DNS name and all lower-case. The domain name should be all upper-case. In the example setup, the host name is MYCEMP01 and it is in the MYDOM.EXAMPLE.COM domain, so the two SPNs would be FNCEWS/mycemp01 and FNCEWS/mycemp01@MYDOM.EXAMPLE.COM.
If this is a cluster, set host_name to the cluster name (see “Using Kerberos with a Cluster of Content Engine Servers”).
Case matters when choosing the SPNs! Make sure the host name is lowercase and the domain name is uppercase.
Create an AD domain user account that will be the “identity” behind the SPN. This account will be mapped to the SPNs in the next step and, crucially, has a password which, through some hashing, serves as a symmetric encryption/decryption key for parts of the Kerberos tickets.
The name of this account should be FNCEWS_ + host_name and will generally be similar to the short SPN name chosen above with an underscore ( _ ) in place of the slash ( / ). There are two exceptions to this, however: 1) for clusters, where host_name would be a cluster name instead; and 2) if the derived FNCEWS + host_name name would be longer than 20 characters, as it would with host_names longer than 13 characters. The latter exception is because of a bug on some versions of WebSphere's Java with long User Principal Names (UPNs) and complications on all platforms if the UPN does not match the “User Logon Name (pre-Windows 2000)” name, which is also restricted to 20 characters or less. If either of these exceptions holds, then you must choose a 20 character or shorter unique user name (for example, FN_long_user_name_12) and configure the Kerberos login module to use this new name by setting the serviceAccountName option (see “KrbServiceLoginModule Options”). This “identity” user account name is case-sensitive and should be remembered as it will be needed when creating this account and for some later steps.
To create the account, open the Active Directory Users and Computers tool on a Domain Controller in the Content Engine server ’s Windows domain. Create a Windows domain user (not computer) account that will be used for the SPN. This account must be in the same domain as that of the Content Engine system. Enter the “identity” user account name, make sure the “Password never expires” is checked and nothing else, and then enter a password for that account and confirm it. Remember this password as it will be needed later.
Using the “Active Directory Users and Computers” snap-in again, select the account you just created, right-click it and then select “Properties…” from the menu. Select the “Account” tab and then check “Use DES encryption types for this account” (you will need to scroll down to the bottom of the “Account Options” control to find this option).
This “identity” user account should not be used for other purposes other than acting as a Kerberos identity for a single Content Engine server or cluster. In particular this account should not be shared by several Content Engine servers unless, of course, they are all in the same cluster.
After the “identity” user account is created, it must be mapped to the proper SPNs. This is done by using Microsoft's setSPN utility, which is available on Windows 2003 Servers (and later). Windows 2000 Servers also have a setSPN utility, but this will have to be downloaded from the Internet. Type something like these two lines in a command window on a Windows Content Engine system or a Windows Domain Controller system.
setSPN –a FNCEWS/mycemp01 FNCEWS_mycemp01
setSPN –a FNCEWS/mycemp01.mydom.example.com FNCEWS_mycemp01
(Substitute in the SPN you have chosen and the name of the “identity” account just created for mycemp01 and the domain mydom.example.com ).
Microsoft's ktpass utility is another way to map SPNs, but do not use this for CEs on Windows systems! This utility is needed for Unix Kerberos realms, which are not yet supported.
To avoid having Content Engine prompt for the SPN’s password each time it needs it, set up a keytab (key table) that has the identity user’s proxy account and password. Do this by entering a command line to run the "ktab" Java utility on the Content Engine server system. This command line varies depending on the type of the application server.
On Windows-based WebLogic or JBoss application servers, enter:
%JAVA_HOME%\bin\ktab –a FNCEWS_mycemp01@MYDOM.EXAMPLE.COM
On Windows-based WebSphere application servers, enter (on a single line):
%JAVA_HOME%\bin\java com.ibm.security.krb5.internal.tools.Ktab –a FNCEWS_ cemp01@MYDOM.EXAMPLE.COM
On UNIX-based application servers, replace %JAVA_HOME%\bin\
with ${JAVA_HOME}/bin/
in the lines above.
After typing this line, enter the password when prompted.
The user name is case-sensitive and must be exactly the same case in the ktab command line as the user name defined in Windows Active Directory. For instance, if the user account was created with the name “FNCEWS_myname”, then there might be mysterious, hard-to-identify problems later if “FNCEWS_MyName” were used on the ktab command.
Notice the underscore ("_") between FNCEWS and the system name. FNCEWS_mysystem is the accountname, not the SPN, which has a slash "/" delimiter instead (as in FNCEWS/mysystem). If you mistakenly enter the SPN, simply run ktab again using the account name. You can clean up these mistakes by deleting bad entries using the same command line as above, but substituting -d (delete) for the -a switch.
The ktab utility is part of the JDK distribution and this will create a file named krb5.keytab in the logged on account’s "home" directory. This home directory would be something like:
c:\Documents and Settings\administrator.MYDOM\
(Windows)
/home/username
(Unix)
NOTE Logging on as another user will change this home directory, which can be a problem if the krb5.keytab file is different in that directory or even absent.
Since the keytab contains sensitive information (encrypted passwords), you
as the administrator would probably not want to use the default keytab as above.
Instead, you would probably want to put restrictive file-system permissions
on the keytab so that only a minimum number of accounts can even read it. To
do this, specify an extra option, -k path / mykeytab
, on the ktab command
line.
To enable Kerberos under WebLogic, you must set up a special Engine Kerberos Service Authentication Provider, as follows:
To enable Kerberos under WebSphere, do the following steps:
com.filenet.engine.authentication.kerberos.login.KrbServiceLoginModule
com.ibm.ws.security.server.lm.ltpaLoginModule
com.ibm.ws.security.server.lm.wsMapDefaultInboundLoginModule
To enable Kerberos under JBoss, do the following steps:
<!-- Kerberos login module -->
<login-module code=
"com.filenet.engine.authentication.kerberos.login.KrbServiceLoginModule"
flag="sufficient">
<module-option name = "debug">true</module-option>
</login-module>
<application-policy name="FileNetP8KerberosService">
<authentication>
<login-module code="com.filenet.api.authentication.jboss.login.FnClientLoginModule"
flag="required">
</login-module>
</authentication>
</application-policy>
The KrbServiceLoginModule (or WebLogic Engine Kerberos Authentication Provider) does the Kerberos service authentication on the Content Engine server. This login module has several options that can change its behavior:
For example, if tgtLoginConfigName=KrbTgtLogin, then there could be a JAAS configuration entry such as:
KrbTgtLogin {
com.sun.security.auth.module.Krb5LoginModule required
debug=true useKeyTab=true storeKey=true
keyTab="c:/etc/krb5.keytab";
};
If this is not set, the default is to use an internal configuration that is tailored for the application server. It is recommended that this option not be set as the default will almost always work correctly.
keytabPath="file:/c:/etc/krb5.keytab"
(WebSphere)keytabPath="c:/etc/krb5.keytab"
(WebLogic, JBoss,
or other potentially supported application servers)
C:/Documents and Settings/mike.MYDO/krb5.keytab
. The keytabPath option needs to be used when the application server is running as a Windows service or if the keytab is not in the default location.
cacheSize - specifies the size of the ticket cache used on JBoss application servers. This cache works around "request is replayed" errors that happen because of the way that JBoss sometimes uses a Kerberos ticket twice during a normal authentication and triggers the error on the second use. This defaults to 100 on JBoss and is ignored on other application servers. It is recommended that this option not be set, unless running on JBoss servers that have been getting “Request is a replay” errors, in which case you could try values greater than 100.
To use Kerberos on the client, see "Using Kerberos on the Client" in Working with Security in the Content Engine API Developer's Guide.
The SPN used for a cluster is different than that used for individual Content Engine servers. For a cluster, pick a unique SPN, say FNCEWS/cluster01, and create a single domain user, FNCEWS_cluster01, that will be the Kerberos identity account for that SPN. Run the setspn utility to map this SPN to this identity account by typing:
setspn -a FNCEWS/cluster01 FNCEWS_cluster01
setspn -a FNCEWS/cluster01.mydom.example.com FNCEWS_cluster01
All Content Engine servers must then be set up to use this cluster-wide identity rather than the server-name identity normally used. Do this as follows:
For WebSphere and JBoss (and other potentially supported application servers):
Add a new option, serviceAccountName=FNCEWS_cluster01, to the JAAS configuration for KrbServiceLoginModule on each application server.
For WebLogic:
Set the Service Account Name option for the Engine Kerberos Authentication Provider.
In cases where one client references a server's URL directly (recommended for Enterprise Manager) and another client could reference the cluster URL of that server (possible with customized .NET clients), then there must be additional SPN mappings to the same identity account. For example:
setspn -a FNCEWS/cluster01 FNCEWS_cluster01
setspn -a FNCEWS/cluster01.mydom.example.com FNCEWS_cluster01
setspn -a FNCEWS/mycemp01 FNCEWS_cluster01
setspn -a FNCEWS/mycemp01.mydom.example.com FNCEWS_cluster01
setspn -a FNCEWS/mycemp02 FNCEWS_cluster01
setspn -a FNCEWS/mycemp02.mydom.example.com FNCEWS_cluster01
It is important to remember the following items:
Finally, it is extremely important that no single SPN be mapped to more than one identity account. For example, the following two setspn commands, even if they were done at different times would cause unexpected "The network path not found" errors on the clients:
setspn -a FNCEWS/mycemp01 FNCEWS_mycemp01
setspn -a FNCEWS/mycemp01 FNCEWS_cluster01
This example has the same SPN, FNCEWS/mycemp01, mapped to two different identities: FNCEWS_mycemp01 and FNCEWS_cluster01. Unfortunately, this can occur innocently enough by starting with only a single Content Engine server and later expanding to a cluster of Content Engine servers. Likewise, there is no way to check for duplicates of this sort in Microsoft's setSPN utility. See the later "Solving Kerberos Problems" topic for what to do if this error condition occurs.
Multiple Windows domains, where the clients are in one or more domains and the Content Engine server is in another, can be made to work with Kerberos but special considerations must be taken into account. The first is that the domains (or realms in Kerberos terminology) must accept the identity established in another domain. This means that one domain "trusts" another.
There are three major ways that Windows systems have of establishing this domain to domain trust:
Domain forests were introduced in Windows 2000 Server and allow one or more hierarchical domain trees with parent/child relationships. In the forest, the trust is transitive in that one domain trusts another domain no matter where it is in the forest. Windows 2003 Server went one step further and allowed transitive trusts from one forest to another, although these "inter-forest" trusts are only available if both forests have been promoted to Windows 2003 mode. External trusts originated in Windows NT and are explicit trust links that are set up between one domain and another that are not transitive in that if domains A and B trust each other and domains B and C trust each other, then this does not imply that A trusts C or C trusts A. Two-way external trusts mean that each domain trusts the other (one-way external trusts are not supported by Kerberos).
These different type of domain to domain trusts work well with Kerberos authentication, although each domain must have its directory configuration set up in the GCD and the application server must have LDAP providers set up for each domain. The GCD directory configuration is done using Enterprise Manager (right-click the P8 domain name, select Properties from the menu, click Directories and add a new configuration for each domain).
The second consideration for cross-domain Kerberos is that the SPNs will most often need an “ @ ” qualifier, such as FNCEWS/mycemp01@MYDOM.EXAMPLE.COM. The shorter, unqualified SPN, like FNCEWS/mycemp01, can also be used in some cases, but might have problems if the server name mycemp01 is ambiguous as that name appears more than once in a forest or if that shorter form is used with an external two-way trust or transitive two-way trust. If the shorter SPN does not work, then the .NET client will likely get "The network path was not found" error.
Enterprise Manager also needs special handling for cross-domain Kerberos authentication as it tries to derive the SPN from the configured Content Engine server URL. There will often be cases where the URL will need a fully qualified domain name to get the correct SPN. For example, a Content Engine URL of http://mycemp01.mydom.example.com:9080/wsi/FNCEWS40SOAP will be turned into an SPN of FNCEWS/mycemp01@MYDOM.EXAMPLE.COM, which should work. A shorter, unqualified URL such as http://mycemp01:9080/wsi/FNCEWS40SOAP would produce an SPN of FNCEWS/mycemp01, which might not work.
A final note is that the client's domain from Kerberos's point of view is the domain of the logged-on user, which will not necessarily be the domain of the client system. For instance, a client system is in domain NORTH that trusts the domain SOUTH and the user as logged onto the system as Frank@SOUTH; in this case Kerberos will use SOUTH as the client's domain.
Troubleshooting problems with Kerberos can be a bit complex, given the number of computers and amount of software that can be involved.
The error codes that follow are displayed in bold italic (for example, "KDC has no support for encryption type (14)"). Note, however, that exact wording depends on the application server vendor and version. The following examples use mycemp01 as the Content Engine server name and MYDOM.MYCOMPANY.COM as the Windows domain name.
In most cases, the important part of the error will be towards or at the end of the error message. For instance, if the error message returned by the client was "WSE594: InitializeSecurityContext call failed with the following error message: The network path was not found. ", the important part of this message is the "The network path was not found. "
"Unable to connect to the remote server. No connection could be made because the target machine actively refused it."
If you get this error, carefully check the URL, particularly the associated port number, that you are using to connect to Content Engine. Also make sure that Content Engine is running.
"The network path was not found"
This error might indicate one of several underlying problems:
1. Enterprise Manager has a bad Content Engine server URL.
Enterprise Manager calculates the Kerberos SPN by taking the host part of the URL and prefixing it with FNCEWS/, so that, for example, a URL of http://mycemp01:9080/wsi/FNCEWS40SOAP/ would yield an SPN of FNCEWS/mycemp01. This should match the SPN previously set up for the server. It will also turn fully qualified domain names like http://mycemp01.mydom.example.com:7001/wsi/FNCEWS35DIME/ into an SPN of FNCEWS/mycemp01@MYDOM.EXAMPLE.COM. These derived SPNs usually work well, but can sometimes have problems. Particularly watch out for URLs that are not DNS names, like http://localhost:9080/wsi/FNCEWS40SOAP/ or similarly ones using IP addresses, like http://123.45.67.89:7001/wsi/FNCEWS40SOAP as these will yield bad SPNs.2. The SPN is correct, but was never mapped by the setspn utility to the corresponding "identity" user account, FNCEWS_mycemp01 in this example. Try running " setspn –l FNCEWS_mycemp01 " to list the SPNs that have been mapped to this account. Check for misspellings, such as " _ " or " \ " instead of " / ".
3. The SPN was mapped to more than one "identity" account. One option to check for this is to use the LDIFDE.EXE utility (part of Microsoft's Windows 2003 Server support tools) to dump the account information to a text file by issuing a command like " LDIFDE –d "dc=mydom,dc=mycompany,dc=com" -f mydom.txt ". Then open the mydom.txt file with a text editor and search for the SPN string, " FNCEWS/mycemp01 " in this example. If duplicates are found, you can remove an extra one by typing something like "setspn -d FNCEWS/mycemp01 FNCEWS_baduser".
4. The SPN is not known in the client's domain. This situation can arise if the client's logged-on user domain and Content Engine Windows domains are either not the same or are not in the same Windows domain "forest" where the domains implicitly trust each other. See the Cross-realm Kerberos authentication section for a work-around for Windows domains that use external or transitive two-way trusts.
5. The SPN had one of the above problems and was recently fixed. In this case the .NET framework has cached the bad result and the only way to clear this is to reboot the client system. It is a good idea to reboot the client anytime .NET reports a "The network path was not found" error.
"There are currently no login servers available to service the login request."
This error can sometimes be caused because of connectivity problems between the client and domain controller systems for all involved domains. If the connectivity seems to be okay, this error might also mean that the time servers on the client and server are too far out of sync, particularly in cross-domain setups. Usually the servers must have times within 5 minutes of each other, but sometimes having them even 1 minute out of sync can cause problems.
"A specified login session does not exist. It might already have been terminated."
This could mean that the client workstation's logged-on user is a local account and not a domain account. Kerberos requires that the logged-on user is a domain user account.
There might be other less common problems with the client. One way to see if the message is even making it to the Content Engine server is to turn on Kerberos Service debugging on the Content Engine server. Do this by setting debug=true in the JAAS configuration for the KrbServiceLoginModule on WebSphere or, on WebLogic, by setting the Debug option to true for the Kerberos Service Authentication Provider. If the request is getting through to the Content Engine server, the server's console or log will have additional debug lines for each request.
If the Kerberos problem does not seem to be on the client, turn on Kerberos Service debugging. Do this by setting the debug=true option in the JAAS configuration for the KrbServiceLoginModule on WebSphere; on WebLogic do it by setting the Debug option to true for the Kerberos Service Authentication Provider.
What follows are a few of the more common Kerberos problems. Some error messages will have a number, for example (9), that represents a standard Kerberos error code. This number can appear in either the message itself or, as is the case with WebSphere, as the minor error code for the error. Here are the problems:
"The client or server has a null key (9)"
This could indicate that the Content Engine server has not had the AllowTgtSessionKey_fix_for_Krb5LoginModule.reg registry patch applied. This patch is necessary on certain later service packs and versions of Windows.
"KDC has no support for encryption type (14)"
"Cannot find key of appropriate type to decrypt AP REP - RC4 with HMAC"
"Cryptographic key type rc4-hmac not found"
These errors might mean that the "identity" domain user account does not have the "Use DES encryption types for this account " option set. Another possibility is that the wrong ktab utility was used (say the Sun ktab utility was used on a WebSphere system). It can also mean on WebSphere systems that the krb5.ini file does not have these settings in the [libdefaults] section:
default_tgs_enctypes = des-cbc-md5 des-cbc-crc
default_tkt_enctypes = des-cbc-md5 des-cbc-crc
"Password has expired - change password to reset (23)"
The "identity" user account's password must be changed. Also remember to run the ktab utility on the Content Engine server to change the keytab's password if necessary.
"Pre-authentication information was invalid (24)"
The most likely error is that the user name and password in the keytab does not exactly match the user name and password of the “identity” user account given when creating the account. Notice that this match is case-sensitive for both the user name and the password. This could also mean that the keytab file was not found for the user account (in the FNCEWS_mycemp01@MYDOM.EXAMPLE.COM form), but there should also be a "could not find user in keytab" error prior to this. There is also the possibility that the system clocks are too far out of sync, see the "Clock skew too great " error.
"Integrity check on decrypted field failed (31)"
This could mean that "identity" user account mapped to the SPN which the client used does not match the user account that the Content Engine KrbServiceLoginModule used. A possible reason for this is that the login module's serviceAccountName is not set to the correct mapped SPN name for a cluster.
This error can also occur on a WebSphere system if the user name in the keytab does not exactly match the user name (case-sensitive) given when the “identity” user account was created. This means that the case of the user name given in the ktab command really matters!
"Request is a replay (34)"
This request has the same Kerberos token as an earlier request. This is probably because a .NET client is reusing a KerberosToken (or KerberosToken2 ) object rather than re-constructing it for each request. If on JBoss, then this might mean that the cacheSize option's value is too small and must be increased. For the security minded, it could also mean that intruders are trying to impersonate users using a "replay attack" (but, seriously, only consider this for a production system which has been using Kerberos for a while and has all the bugs worked out).
"Clock skew too great (37)"
This error can happen if the clocks on the client machine and the Content Engine server are more than some number of minutes apart. Commonly this is 5 minutes, but can also be 1 minute. The fix for this is to more closely synchronize the clocks on the two machines.
"The user could not be found in the keytab"
"Key for the principal FNCEWS_mycemp01@MYDOM. EXAMPLE.COM not available in default key tab"
"No Kerberos creds in keytab for principal FNCEWS_mycemp01@MYDOM.EXAMPLE.COM"
These errors could either indicate that the "identity" user (for example, FNCEWS_mycemp01@MYDOM. EXAMPLE.COM ) was not in the keytab or that the keytab file itself could not be found. Use "ktab" by itself from the command line to list the contents of the default keytab file and check for misspellings. The keytab file is, by default, the c:\Documents and Settings\ <user> \krb5_keytab file. Where <user> is the name of the account that the application server is running as. Note that if the application server is running as a service, there will probably be no corresponding <user> directory and it is best if the keytabPath="c:/my_keytab" KrbServiceLoginModule option is used to specify what and where the keytab is.
"Could not create default AuthorizationToken during propagation login"
This is a WebSphere error that probably means that the security mechanism is set to "SWAM" rather than "LTPA". See the notes above on setting up WebSphere on how to change this.
"Principal user@MYDOM.EXAMPLE.COM not found"
This error can occur if the GCD does not have a directory configuration for the MYDOM.EXAMPLE.COM Active Directory. In Enterprise Manager, right-click the name of the P8 domain and select "Properties" from the menu and then click Directories.
This error can also happen in a multi-domain environment if the GCD does not have the directory configuration for a client domain set up, as each client domain must individually have its directory configuration set up.
"JAAS configuration FileNetP8KerberosService not found"
This error will occur if the FileNetP8KerberosService JAAS configuration entry has not yet been configured.
"Cannot get kdc for realm MYDOM.EXAMPLE.COM"
This error can happen if the kdc= line in the Content Engine krb5.ini file has not been edited correctly to reference the primary domain controller for the MYDOM.EXAMPLE.COM domain. Another possibility is that the Kerberos configuration file, krb5.ini, cannot be found by the Content Engine as it is either not in the c:\winnt directory or the –Djava.security.krb5.conf= setting is wrong.
This can also happen in a multi-domain setup which uses external two-way trusts if the Content Engine krb5.ini file has not been set up to configure each client domain.
“Null key”
This error can happen on WebSphere systems if the server's SPN identity (for example, FNCEWS_mysys@MYDOM.COM ) cannot be found in the Content Engine server's currently configured keytab.
It can also happen if the keytab file itself cannot be found for some reason, such as using the default keytab, but that keytab was created by one user and the app server is running as another (a particular problem if the app server is running as a Windows service). One fix for this is to specify the keytabPath option for the KrbServerLoginModule, for example, keytabPath="c:/config/keytab".
“Null name”
This error will occur on WebSphere systems if the identity user name used for Kerberos's identity account is longer than 20 characters. The default identity user name is derived by Content Engine to be the string FNCEWS_ + host_name. Unfortunately this default name will be too long if host_name itself is 14 or more characters long. If this is the case, this can be fixed by using some other name for this identity user account and specifying that name in the serviceAccountName option for KrbServiceLoginModule. For example, serviceAccountName=FN_long_host_name_123).
Another possibility, also on WebSphere servers, is that the encryption type of the key saved in the keytab does not match the encryption type used when encrypting the Kerberos ticket. One way for this to happen is if the “identity” account does not have the “Use DES encryption types for this account” option set in the account's property dialog. (See “Step 1 - Create an Active Directory domain user account”.)
This problem might require setting the ‑-Dcom.ibm.security.jgss.debug=all and -‑Dcom.ibm.security.krb5.Krb5Debug=all properties on the JVM to diagnose as described below.
There can be many other Content Engine server Kerberos problems. If Kerberos Service debugging is not enough to isolate the problem, try turning on additional system debugging, which will give even more information. Content Engine WebLogic and JBoss servers can specify the sun.security.krb5.debug property, usually on the Java command line with -Dsun.security.krb5.debug=true. This produces a lot of trace output on the JVM's console. There are two Java command line switches for Content Engine WebSphere servers:
-Dcom.ibm.security.jgss.debug=all
-Dcom.ibm.security.krb5.Krb5Debug=all
which also provide extra messages in WebSphere's log.
“Kerberos authentication fails due to WAS initial naming context not set”
Attempting to perform a Kerberos login with either EM or the AuthnTest utility results in a "Web services Kerberos credential invalid" error, and WebSphere "Failure to obtain initial naming context" errors. These errors indicate that WebSphere did not initialize the Java naming factory, which is required for Kerberos authentication.
Open the WAS admin console and expand Servers, click Application servers, click <server name>, then expand Java and Process Management on the right, click Process Definition, click Java Virtual Machine and then enter the following argument text in the Generic JVM arguments box (with a space to separate it from other args, if needed):
-Djava.naming.factory.initial=com.ibm.websphere.naming.WsnInitialContextFactory
Click Apply and Save, then restart WebSphere.