Configuring Openfire for Use with Kerberos
Openfire server supports single sign-on (SSO) authentication through the Generic Security Services API (GSSAPI) and Kerberos. Kerberos is a security protocol in which clients authenticate with a single authentication server, then use that authentic status to request services from other server technologies. Kerberos is invisible to users, of course. When an XMPP chat client such as Spark supports GSSAPI and Kerberos, that support is handled behind the scenes.
This guide assumes youâve already set up a working Openfire server, and you have a user and auth provider already working. If you have not already set up Openfire, do so according to the official documentation before you move on. You wonât be able to test your Kerberos setup until youâve finished setting up Openfire.
Administering Kerberos is a complex subject. This content assumes that youâre either experienced with Kerberos administration or are working with someone who is. Unfamiliarity with Kerberos is the single most common reason for errors when configuring Openfire for SSO. For some introductory content on Kerberos, be sure to read the documents that are provided as an attachment to this text.
Vocabulary
There is a lot of vocabulary used in regards to SSO, so Ill try to put them here so there is a clear definition of what is being referred to.
- Authentication - The process of verifying a user really is who the user claims to be.
- Authorization - The process of taking an authenticated user and granting access to particular resources.
- SASL - Simple Authentication and Security Layer. This is the basic protocol used for authentication and authorization in the XMPP protocol.
- SASL Mechanism - Sometimes just referred to as a âMechanismâ, this is a particular method of authentication in SASL. Both the client and server need to agree on a mechanism for authentication to be successful.
- Kerberos - The name of the protocol used to authenticate users.
- Token - A special piece of information exchanged between two entities. A token will often have authentication and/or authorization information in it.
- GSSAPI - Generic Security Service Application Program Interface. A generic way of passing tokens between applications. Kerberos is the primary user of GSSAPI, but not the only.
- FQDN - Fully Qualified Domain Name. The DNS name of the server registered to the IP address the server is using.
- Username - This is an overly generic term for the name of a user. With SSO its ambiguous by itself, so whenever possible Ill try to clarify. In general Ill refer to the username as being the Openfire username, though.
- Principal - The term we use for the username of the Kerberos account. Principals can refer to more than just people, however. Takes the form of username@REALM . Note that the username portion of a principal does not need to match the username of Openfire, but it will greatly simplify things if they do.
- Service Principal - Exactly the same thing as a regular principal, but used to denote a service instead of an individual. Takes the form of service/hostname@REALM
- Keytab - A keytab is a special file that contains the âpasswordâ for a service principal, or more than one service principal. These files contain sensitive information, so they need to be protected appropriately.
Steps at a High-Level
- Start with working installations of Kerberos version 5 and Openfire 3.3.0 or later. You can Verify Your Kerberos Setup. That way if you need to troubleshoot, youâll already know that the servers are working.
- Create a Service Principal and Keytab for Openfire. This makes Kerberos aware of Openfire. Youâll do this on the KDC host.
- Transfer the Keytab File to the Openfire Host. This provides a place for Openfire to cache credential information.
- Values in this file set the GSSAPIâs policy for interacting with Kerberos.
- Edit Openfire Configuration to Add Kerberos Support. The new values will configure Openfireâs support for authentication providers, including Kerberos via the GSSAPI.
- Testing. Check for the correct amount of network traffic.
- Troubleshooting. Did you miss something?
Verify Your Kerberos Setup
This is slightly different between Unix and Windows, but the main ideas are the same.
On the system Openfire is installed on, use the klist command to confirm that the logged in user has a ticket. (klist is native to Unix; for Windows, itâs available in the Windows Resource Kit.)
If you donât have a Kerberos realm set up, do that before moving on. On Windows, Windows Active Directory is already using Kerberos; your realm name should be the âWindows Domain Name.â When you create a realm, be sure to use all uppercase letters for the realm name. While itâs perfectly valid to have a realm with lower case names, and itâs not at all typical and Java doesnât handle it well. Additionally, Windows Active Directory has the concept of Local and Domain users. The klist command will not work for Local users.
Kerberos is a time-sensitive protocol. Make sure your Openfire serverâs clock is synchronized with the KDC. Clients are often given a five-minute clock-skew, but itâs best if they can be synchronized even closer. Network Time Protocol (NTP) is the most common way of accomplishing this, but other methods may exist. A common problem for Linux based systems is having the timezone incorrectly set, resulting in what appears to be a correct time, that is perhaps several hours off.
Example outputs
Unix
$ klist
Ticket cache: FILE:/tmp/krb5cc_1000
Default principal: user@EXAMPLE.COM Valid starting Expires Service principal
06/01/07 15:43:55 06/02/07 01:43:55 krbtgt/EXAMPLE.COM@EXAMPLE.COM
renew until 06/02/07 15:43:53 Kerberos 4 ticket cache: /tmp/tkt1000
klist: You have no tickets cached
Windows
C:\> klist tgt Cached TGT: ServiceName: krbtgt
TargetName: krbtgt
FullServiceName: user
DomainName: EXAMPLE.COM
TargetDomainName: EXAMPLE.COM
TicketFlags: 0x40e00000
KeyExpirationTime: 0/39/4 0:00:10776
StartTime: 6/1/2007 15:03:03
EndTime: 6/2/2007 1:03:03
RenewUntil: 6/8/2007 15:03:03
TimeSkew: 6/8/2007 15:03:03
Verify systemâs domain name
Important! Domain names are very important when using Kerberos. You must make sure that the name of your principal created matches a DNS entry pointing to the same host. If you donât, youâre likely to see things break in odd ways. Kerberos uses reverse DNS when it is available, so to determine what name to use for the service principal, use nslookup on the IP address that Openfire will be running on.
$ nslookup jabber.example.com
Server: ns.example.com
Address: 10.11.12.1 Name: jabber.example.com
Address: 10.11.12.42
$ nslookup 10.11.12.42
Server ns.example.com
Address: 10.11.12.1 Name: srv01.example.com
Address: 10.11.12.42
So in this example, the Openfire server on jabber.example.com would use the host name srv01.example.com for the service principal. If this name does not match the âDomain Nameâ setting in Openfire (the xmpp.domain property), you must set the property xmpp.fqdn to this name as well.
Create a Service Principal and Keytab for Openfire
You must create a service principal on the KDC, and a keytab on the openfire server. The keytab holds credential information used in Kerberos interactions.
The process varies depending on whether The KDC is hosted on unix or the KDC is Active Directory.
The KDC is hosted on unix
If your KDC is hosted on a Unix computer, you can use the kadmin command line to create a principal and keytab file. To do the following, youâll need an admin account in your realm (typically user/admin@REALM.COM). The kadmin command can be run from any host that has proper access to the KDC, and does not need to be run on the KDC itself. If possible, create the keytab file on the host Openfire is installed on so you do not need to transfer the file.
- Log into the kadmin command.
- Use the addprinc command to create a new XMPP service principal that is the server name used for Openfire. The typical command syntax is:
addprinc -randkey xmpp/srv01@REALM_NAME
The exact command you use will depend on your realm policy and Kerberos implementation. The server name should be the name discovered using the nslookup command previously. In the following example, jabber.example.com is the server name and EXAMPLE.COM is the realm name:
addprinc -randkey xmpp/jabber.example.com@EXAMPLE.COM
- Use the ktadd command to create a key table (keytab) file for Openfire. Later, youâll move the keytab to the Openfire host, if applicable, and include its location in your Openfire configuration.
If your Openfire server has a keytab in /etc/krb5.keytab and the Openfire service does not run as root, create a separate keytab file from the host keytab. For example, instead of /etc/krb5.keytab, create the file at /opt/openfire/resources/jabber.keytab. The typical +ktadd+ command syntax for this is:
ktadd -k path/to/file.keytab -e encryption_type:salt xmpp/srv01@REALM_NAME.COM
At present, Java can only understand a limited number of encryption types (although Java 6 might support AES encryption for more flexibility), so you might need to make a keytab with a des3-hmac-sha1 encryption type. With this kind of keytab, a +ktadd+ command example could look like this:
ktadd -k /etc/jabber.keytab -e des3-hmac-sha:normal xmpp/jabber.example.com@EXAMPLE.COM
You might also need to download the unlimited strength Java Cryptography Extension (JCE). JCE is subject to U.S. Export Control, however, so be sure to follow the rules for your country.
The KDC is Active Directory
Shortcut for Samba users
If the Openfire server has Samba installed and joined to the domain, setting up the keytab is greatly simplified.
Joining the domain
If your openfire server is already joined to the domain, skip to #Create xmpp service principal
- Set up the samba service to use Active Directory authentication.TroubleshootingEdit smb.conf to include the following:
workgroup = EXAMPLE
security = ads
realm = example.local
use kerberos keytab = true
password server = *
Some people have had problems with using * in the password server value. If you are unable to join the domain (see below), try using the full names of a domain controller or two (separated by spaces) instead.
- Use the net command to join the domain. This will create a machine account and generate a basic system keytab.
# net -UAdministrator ads join
Replace âAdministratorâ with the name of an account authorised to add machine accounts to the domain.
- Verify that the join worked:
# net ads testjoin
Join is OK # net ads status
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: user
objectClass: computer
cn: srv01
distinguishedName: CN=SRV01,OU=Computers,DC=Example,DC=COM
...
name: SRV01
dNSHostName: srv01.example.com
servicePrincipalName: HOST/srv01.example.com
servicePrincipalName: HOST/SRV01
It may take a few minutes for this to work, particularly in a large domain. If either of the verification commands do not work, wait 5 minutes and try again.
Create xmpp service principal
Now you can add the service principal required for Openfire to authenticate.
# net ads keytab add xmpp
Confirm that the keys were properly added:
# klist -k
Keytab name: FILE:/etc/krb5.keytab
KVNO Principal
---- --------------------------------------------------------------------------
2 host/srv01.example.com@EXAMPLE.COM
2 host/srv01.example.com@EXAMPLE.COM
2 host/srv01.example.com@EXAMPLE.COM
2 host/SRV01@EXAMPLE.COM
2 host/SRV01@EXAMPLE.COM
2 host/SRV01@EXAMPLE.COM
2 SRV01$@EXAMPLE.COM
2 SRV01$@EXAMPLE.COM
2 SRV01$@EXAMPLE.COM
2 xmpp/srv01.example.com@EXAMPLE.COM
2 xmpp/srv01.example.com@EXAMPLE.COM
2 xmpp/srv01.example.com@EXAMPLE.COM
2 xmpp/SRV01@EXAMPLE.COM
2 xmpp/SRV01@EXAMPLE.COM
2 xmpp/SRV01@EXAMPLE.COM
The principals have been created, but /etc/krb5.keytab is only readable by root (as it should be!). You will need to extract just the xmpp principal to another keytab that is readable by the openfire user. To do this, use ktutil:
# ktutil
ktutil: rkt /etc/krb5.keytab
ktutil: l
slot KVNO Principal
---- ---- ---------------------------------------------------------------------
1 2 host/srv01.example.com@EXAMPLE.COM
2 2 host/srv01.example.com@EXAMPLE.COM
3 2 host/srv01.example.com@EXAMPLE.COM
4 2 host/SRV01@EXAMPLE.COM
5 2 host/SRV01@EXAMPLE.COM
6 2 host/SRV01@EXAMPLE.COM
7 2 SRV01$@EXAMPLE.COM
8 2 SRV01$@EXAMPLE.COM
9 2 SRV01$@EXAMPLE.COM
10 2 xmpp/srv01.example.com@EXAMPLE.COM
11 2 xmpp/srv01.example.com@EXAMPLE.COM
12 2 xmpp/srv01.example.com@EXAMPLE.COM
13 2 xmpp/SRV01@EXAMPLE.COM
14 2 xmpp/SRV01@EXAMPLE.COM
15 2 xmpp/SRV01@EXAMPLE.COM
ktutil: delent 1
ktutil: delent 1
ktutil: delent 1
ktutil: delent 1
ktutil: delent 1
ktutil: delent 1
ktutil: delent 1
ktutil: delent 1
ktutil: delent 1
ktutil: l
slot KVNO Principal
---- ---- ---------------------------------------------------------------------
1 2 xmpp/srv01.example.com@EXAMPLE.COM
2 2 xmpp/srv01.example.com@EXAMPLE.COM
2 2 xmpp/srv01.example.com@EXAMPLE.COM
4 2 xmpp/SRV01@EXAMPLE.COM
5 2 xmpp/SRV01@EXAMPLE.COM
6 2 xmpp/SRV01@EXAMPLE.COM
ktutil: wkt /opt/openfire/xmpp.keytab
ktutil: q
# chown openfire.openfire /opt/openfire/xmpp.keytab
# chmod 440 /opt/openfire/xmpp.keytab
The long way
If your openfire server is not running samba, itâs a little more complicated.
You will need administrative access to a Windows Domain controller. You will need to install the Windows Support Tools on a domain controller first.
If you have a Windows 2000 or Windows 2003 Active Directory domain already configured, the KDC (Kerberos Key Distribution Center) host service should already be running on your domain controller(s).
-
Create a new user account. The user only needs to be a member of the âDomain Usersâ group. The userâs Password will be set below. In the examples, the account name is xmpp-openfire
-
Enable the account options âUnable to change passwordâ, âPassword never expiresâ and âDoes not require Kerberos Preauthenticationâ on the Account tab of the user you just created.
-
Assign the serverâs xmpp Service Principal Name to the new account using the setspn utility. This step may be unnecessary on Windows 2003.
setspn -A xmpp/srv01.domain.com@EXAMPLE.COM xmpp-openfire
Note: âsrv01.domain.comâ should be the fqdn (fully qualified domain name) of your Openfire server. Also, âEXAMPLE.COMâ should be the name of your Kerberos realm, usually the same as your Windows domain name in all uppercase.
- Use the ktpass tool to Assign the serverâs xmpp SPN to the new account and generate a keytab.
ktpass -princ xmpp/srv01@EXAMPLE.COM -pass * -mapuser xmpp-@EXAMPLE.COM -ptype KRB5_NT_PRINCIPAL -out xmpp.keytab
Note: "xmpp-openfire@EXAMPLE.COM" is the full AD (Active Directory) username of the account you created above. If you do not put the name of the AD domain that the account was created in on the end, the utility may not be able to find the user account in Active Directory and report an error.
The â-pass *â parameter will tell the ktpass utility to prompt you for a new password for the âxmpp-openfireâ user account. It should be secure, but will not be needed again in most cases (but see below)
Some people have had trouble with keytabs created using this method. For those people, the following may help:
Assuming you are running your Openfire server on a Windows server and you have installed the Openfire Server that includes the JRE, follow the next few steps. If you did not use the Openfire Server installation that included the JRE, make sure you are using Java/JRE 6 (1.6.0) or higher.
-
Change directory into the jre\bin folder within your Openfire installation directory or your Java installation directory.
-
Use the Java ktab utility to create your keytab file:
ktab -k xmpp.keytab -a xmpp/srv01.domain.com@REALM.COM
Note: The ktab utility will prompt you for the password for the âxmpp-openfireâ account you created earlier.
- The ktab utility should have created a file named âxmpp.keytabâ in the current directory. Move this file into the âresourcesâ directory of your Openfire installation directory.
Mixing Server Platforms
Kerberos is a platform independent protocol, so your Openfire server may be on a different operating system than your KDC or your clients. If possible, generate the keytab on the Openfire server itself. Since it is not always possible to do this, you may have to transfer the keytab from one host to another. If your KDC is on Windows, then you will need to generate the keytab on a Windows system, such as the KDC itself, then transfer the keytab to the Openfire server. Any Windows system with the proper tools installed should be able to generate the keytab. If your KDC is on Unix, you can generate the keytab on any host that has the kadmin command installed, which should be nearly all Kerberos equipped Unix hosts.
Configure Openfireâs Use of GSSAPI
Openfire uses the Generic Security Services API to implement Kerberos support. Youâll add values to a configuration file thatâs used by the GSSAPI. Later, when configuring Openfire itself, youâll add this fileâs location, along with other Kerberos-related values, to your openfire.xml configuration file.
Note: Windows support requires either a krb5.ini or specifying the realm and KDC on the Java command line.
-
Create a file âgss.confâ in the openfire conf directory.
-
In the file, using the syntax shown below, provide Openfire (using the GSSAPI) with values that are specific your installation
The options include:
-
keyTab â Location of the keytab you created earlier. Note that the directory separator is always a â/â even when on a Windows server (see example).
-
realm â Name of the Kerberos realm that Openfire will be a part of.
-
principal â Name of the principal you created for Openfire.
-
debug â A value specifying whether to log debugging information. Leave it at âtrueâ while setting up, set it to âfalseâ later.
Hereâs an example of the configuration options and values:
com.sun.security.jgss.accept {
com.sun.security.auth.module.Krb5LoginModule
required
storeKey=true
keyTab="C:/Program Files/Openfire/resources/xmpp.keytab"
doNotPrompt=true
useKeyTab=true
isInitiator=false
realm="EXAMPLE.COM"
principal="xmpp/jabber.example.com@EXAMPLE.COM"
debug=true;
};
Put this file in the same directory as the openfire.xml is a good idea. For example, you might put it in /opt/openfire/conf/gss.conf.
Its important to leave the rest of this file alone. For complete documentation of this file, go here: http://java.sun.com/j2se/1.4.2/docs/guide/security/jgss/tutorials/LoginConfigFil e.html
Edit Openfire Configuration to Add Kerberos Support
Youâll edit the openfire.xml file to configure Openfire so that it has the information it needs to interact with Kerberos via the GSSAPI. In particular, youâll add an two new elements: <sasl> and a new <provider> element.
Add the <sasl> element to create a bridge between the Kerberos system and Openfire. The Simple Authentication and Security Layer (SASL) allows applications like Openfire to preserve loose coupling with authentication mechanisms like Kerberos. The <sasl> element configures that layer to describe which mechanisms Openfire supports and how it supports them.
Hereâs an example:
<!-- sasl configuration -->
<sasl>
<!-- Include a comma-separated list of the authentication mechanisms
to advertise support for to clients. Make sure GSSAPI is listed,
and best if it's listed first. The order of mechanisms is important;
clients should try to use the first mechanism they support
(although not all will). Some clients will try to use the most
secure first. You can add other mechanisms in order to support non-GSSAPI clients,
or clients who cannot authenticate to the realm (like Windows 9X,
off-site, and so on). Keep in mind that by allowing other mechanisms
you are compromising the security of your realm. Be sure to talk
to the Security Officer/Directory/Manager/Administrator about any
policies your organization might have before enabling less secure
mechanisms. By removing PLAIN and ANONYMOUS from the list, you will
also disable non-SASL authentications. Keep in mind that a mechanism listed here might not actually be
advertised, such as when the authProvider can't support the mechanism.
PLAIN and ANONYMOUS mechanisms also enable non-SASL authentication
(the old style XMPP auth), so removing them from this list will
disallow non-SASL authentication. -->
<mechs>GSSAPI</mechs>
<!-- <mechs>CRAM-MD5,DIGEST-MD5,PLAIN,EXTERNAL,ANONYMOUS</mechs> --> <!-- Specify the realm you used when you created the service principal
and keytab.-->
<realm>EXAMPLE.COM</realm> <!-- Mechanism-specific configuration here -->
<gssapi> <!-- Use true to turn on debugging information. This adds a lot
of noise to your log files, but it can help you spot problems
sooner in the initial setup. -->
<debug>true</debug> <!-- Specify the location of the GSSAPI configuration file you edited. -->
<config>/opt/openfire/conf/gss.conf</config> <!-- Sets the system property with the same name. You'll probably want
"false" here (the default). For more details, see
[http://java.sun.com/j2se/1.4.2/docs/api/org/ietf/jgss/package-summary.html] -->
<useSubjectCredsOnly>false</useSubjectCredsOnly>
</gssapi>
</sasl>
Add to the <provider> element to specify classes that provide an authorization mapping between authenticated principals and user names. A comma- or space-separated list is fine here. If you leave this provider out the default will be used, which might be fine for many installations. If you already have a <provider> section, you will just add to the existing one.
*Note: * This is not needed in OpenFire 3.5.0 and higher.
Hereâs an example:
<provider>
<authorization>
<classList>org.jivesoftware.openfire.auth.DefaultAuthorizationPolicy</classList>
</authorization>
</provider>
The Lazy provider has a different name in the different versions of Openfire, as the logic changes.
Openfire Versions
Provider Names
3.3.0 and prior
org.jivesoftware.openfire.sasl.LazyAuthorizationProvider
3.3.1 and later
org.jivesoftware.openfire.sasl.LooseAuthorizationPolicy
3.4.0 and later
org.jivesoftware.openfire.auth.DefaultAuthorizationPolicy
3.5.0 and later
Do not add an authorization provider
The provider names will change again in the future, and will be documented here and in the changelog.
Spark
Configure Spark for SSO usage.
-
At the login screen, click on âAdvancedâ and go to the SSO tab.
-
Click on âUse Single Sign-On via GSSAPIâ. If Spark reports what username it will use, this may be all you need to do. If you use Windows, you will need to make an additional change.
If you run Windows, you will need to modify the registry to allow Java to access the credential cache.
On Windows 2000 SP4, Windows 2003 Server and later or Windows Vista:
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos\Parameters
Value Name: AllowTGTSessionKey
Value Type: REG_DWORD
Value: 1
On Windows XP SP2 and later:
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos
Value Name: AllowTGTSessionKey
Value Type: REG_DWORD
Value: 1
Older versions of Windows do not need this registry setting.
If Spark was not able to determine a username to use with SSO, you will need to edit some âhiddenâ properties in the spark.properties file.
The four properties here are:
ssoMethod=string
ssoRealm=string
ssoKDC=string
ssoAdv=boolean
ssoMethod
Set ssoMethod to one of file, dns or manual. If not specified, the default is OS dependent. (On Windows its dns, on others its file)
Set to file to use a krb5.conf or krb5.ini (OS dependent) to determine the realm and KDC information. file is recommended for Unix installations or when a complex realm setup is needed, and DNS is not configured.
Set to dns to use DNS SRV records to determine the KDC information and TXT records to determine the realm. DNS is recommended for ease of administration, but requires additional setup from the default Windows AD DNS records.
Set to manual to use the ssoRealm and ssoKDC fields.
ssoRealm
Set this to the name of the realm to use when ssoMethod is manual.
ssoKDC
Set this to the KDC to use when ssoMethod is manual.
ssoAdv
Set this to true to allow setting the above options on the SSO tab of the advanced settings in the GUI. The default is false.
krb5.con / krb5.ini
If your system requires a krb5.conf (for Unix) or a krb5.ini (for Windows) the syntax is documented below:
[libdefaults]
default_realm = EXAMPLE.COM [realms]
EXAMPLE.COM = {
kdc = kdc.example.com
kdc = backupkdc.example.com
admin_server = kdc.example.com
default_domain = example.com
} [domain_realms]
example.com = EXAMPLE.COM
.example.com = EXAMPLE.COM
This file should be placed in either /etc/krb5.conf or C:\Windows\krb5.ini or in your OS specific location. For more details on this file syntax, see http://www.cmf.nrl.navy.mil/CCS/people/kenh/kerberos-faq.html#confdoc
DNS Records
To use DNS records, the following must be set up in your DNS zone:
SRV record
kerberos.udp.example.com Should be a valid SRV record and point to the KDC for your realm.
TXT record
_kerberos.example.com Should be a valid TXT record and contain the name of your Kerberos realm.
Example:
_kerberos._udp.example.com. 7200 IN SRV 0 0 88 kdc.example.com.
_kerberos._udp.example.com. 7200 IN SRV 1 0 88 backupkdc.example.com.
_kerberos.example.com. 7200 IN TXT "EXAMPLE.COM"
Its worth noting that on most operating systems, the hosts file (/etc/hosts or C:\Windows\System32\drivers\etc\HOSTS) will be referenced before DNS. So it is possible to do all of this without DNS; if you use these files, you need to be sure that every client and server share the same information for the server host name and IP address. Managing this is a difficult task for more than a few computers, which is why DNS is preferred, and it is suggested you remove all references to your hostname in /etc/hosts (some OS installs put the host name in the hosts file under the localhost entry, which will break many Kerberos applications).
Multi-homed servers (servers with more than one IP address) are not supported with SSO at this time, but if you know what you are doing it may be possible.
Required tools
Windows 2003
For Windows 2003 you only need to download and install the Windows 2003 Support Tools which includes both the setspn.exe and ktpass.exe utilities.
Windows 2000
ktpass.exe
Windows 2000 SP4 Support Tools
Windows 2000 SP3 Support Tools
Windows 2000 SP2 Support Tools
setspn.exe
You will also need the Windows 2000 setspn.exe utility
Testing
After all this, you will want to do some testing. A simple Smack program with debugging can show you what is happening at the stream level. You should see the mechanisms being advertised by the server, including GSSAPI. The client should respond with an <auth type=âGSSAPIâ> packet with lots of base64 stuff in it. Generally, there are going to be six packets exchanged just for authentication; if you see something much different, something went wrong.
Troubleshooting
Common Errors
Could not load configuration file C:\WINDOWS\krb5.ini (The system cannot find the file specified)
This error occurs when a krb5.ini was not created, and you did not specify via other means the realm and KDC(s) to use. Be sure to read the documentation carefully, and either set up this file or specify the information in other means.
Cannot get kdc for realm EXAMPLE.COM
This occurs when the KDC for the realm is not able to be found. For most people this will mean the krb5.ini or krb5.conf is incomplete or has a typo. However, it could mean that cross-realm authentication is being attempted and there is no knowledge of the other realm.
KDC has no support for encryption type (14)
While this looks like its an encryption type issue, the real problem is Windows is not allowing Java to get the session key from the credential cache. You need to make a modification to the registry to obtain the key.
No valid credentials provided (Mechanism level: Failed to find any Kerberos Key)
This error can occur for a few reasons, most often because of using the wrong service principal name. Double check that your DNS settings are correct, and that the service principal in the keytab matches your DNS.
username@REALM not authorized to username
This means that Kerberos is working correctly, but that authorization failed. Check what you have in your <providers> section of openfire.xml and make sure that you have something listed for <authorization>. What should be listed in this section has changed from version to version. A common problem is having multiple <provider> sections. Openfire will only use one <provider> section, so you need to combine them into one.
Things to check when it goes wrong:
- Does the client have SSO Configured properly? (If the client is Spark, see the Spark Section)
- Can the client run kinit and klist?
- Does Java have the ability to understand the encryption type Kerberos is using in the client credential cache? If not, maybe Java 6 can. Maybe the JCE is needed.
- Does Java have the ability to understand the encryption type Kerberos is using in the server keytab? If not, maybe Java 6 can. Maybe the JCE is needed.
- In Windows 2003 AD when using older versions of Java (some versions of 5, and older), you might need to set the users to âAllow DES encryption for this userâ.
- You might need to install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files (found on the same download page as Java â but not available in all countries).
- Does the User running Openfire have the ability to read the keytab (is file system permission granted?)?
- Does Java know how to read the Kerberos Credential Cache?
- Windows XP might need to tell older versions of Java that its OS name is âWindows 2000â in order to access the native credential cache (use -Dos.name=âWindows 2000â on the java command line).
- Some Unix operating systems might need to force the credential cache to a certain file by setting the environment variable KRB5CCNAME to â/tmp/krb5cc_$UIDâ
- Java 6 includes the ability to use âNative Kerberos Librariesâ on Solaris and Linux, which might help. Read the Java 6 documentation for details on how to do this.