The official documentation for SSO in Openfire is at SSO Configuration. Please read that document first to understand the concepts used.
SSO Configuration for Windows
The following instructions were used with Openfire 3.4.1 running on Windows Server 2003 and Spark 2.5.8 running on Windows XP SP2 clients. Both server and client’s are all joined to the same Windows Active Directory domain. I have also included instructions on how to get SSO working for Spark clients running on Mac OS X Tiger.
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).
Kerberos is a time-sensitive protocol. Make sure your Openfire server’s clock is synchronized with the KDC host/Domain Controller. Normally, if both your KDC host and Openfire server are joined to the same Windows Active Directory domain they are in sync. 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.
You will need the setspn.exe and ktpass.exe utilities from the Windows Support and Resource Kit tools installed on your KDC host. Use the links below for your version of Windows 2000.
Windows 2000 SP4 Support Tools
Windows 2000 SP3 Support Tools
Windows 2000 SP2 Support Tools
You will also need the Windows 2000 setspn.exe utility
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.
Configure Windows for Openfire SSO support.
-
Log onto your KDC host/Domain Controller using an Domain Administrator account and install the utilities you just downloaded for your version of Windows.
-
Create a new user account with a username/logon name of “xmpp-openfire” and a secure password. The user only needs to be a member of the “Domain Users” group.
-
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.
-
Create a Kerberos XMPP SPN for the account you just created using the setspn utility:
setspn -A xmpp/servername.domain.com@REALM.COM xmpp-openfire
Note: “servername.domain.com” should be the fqdn (fully qualified domain name) of your Openfire server. This must be the NetBIOS/network name of the Windows server Openfire is running on plus the Active Directory domain.
For example:
If the Windows NetBIOS/Network name of your Openfire server is “WINSERVER01” and your Windows AD (Active Directory) domain name is “intranet.com” then the fqdn of your server would be “winserver01.intranet.com”. You can add a CNAME using a different hostname and domain later if you wish, but for the purpose of this document you must use the Windows AD fqdn.
Also, “REALM.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 map the Kerberos XMPP SPN to the “xmpp-openfire” username.
ktpass -princ xmpp/servername.domain.com@REALM.COM -mapuser xmpp-openfire@AD_domain.com -pass * -ptype KRB5_NT_PRINCIPAL
Note: “xmpp-openfire@AD_domain.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 the password for the “xmpp-openfire” user account.
- The next step is creating your keytab file. I have had people tell me that they got a good keytab file using Windows utilities to create their keytab and others, including myself, only had success when using the Java/JRE ktab utility to create the keytab file. Below shows both methods, if you try one and it does not work, check your Openfire warn.log and see if it reports things like “Checksum Failed” or other messages related to a bad keytab file. If it does, then use the other method to create your keytab file and replace your old one and restart Openfire and try again.
The Java ktab utility is located in the “jre\bin” directory of your Java installation directory. You should be running Java/JRE 1.6 or higher.
Using the Java ktab utility to create your keytab file:
ktab -k xmpp.keytab -a xmpp/servername.domain.com@REALM.COM
Note: The ktab utility will prompt you for the password for the “xmpp-openfire” account you created earlier.
Using the Windows ktpass utility to create your keytab file:
ktpass -princ xmpp/servername.domain.com@REALM.COM -mapuser xmpp-openfire@AD_domain.com -pass * -ptype KRB5_NT_PRINCIPAL -out xmpp.keytab
Note: “xmpp-openfire@AD_domain.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 ktpass utility will prompt you for the password for the “xmpp-openfire” account you created earlier.
- The ktab or ktpass 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.
Configure Openfire for SSO + Kerberos using GSSAPI.
- On your Windows based Openfire server, create a GSSAPI configuration file named “gss.conf” in your Openfire conf directory. Here’s an example of what the “gss.conf” file should look like:
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
realm="REALM.COM"
principal="xmpp/servername.domain.com@REALM.COM"
debug=true;
};
Note: The last line of the gss.conf file “debug=true” will tell Openfire to debug and log any GSSAPI errors. This may be usefull while setting up SSO to track down any problems but once you have everything working you can set it to “debug=false”. Also, make sure you use “/” instead of “” in the keyTab path, even on Windows.
- Create a Kerberos configuration file named “krb5.ini” in your Windows installation directory. Usually “C:\WINNT” or “C:\WINDOWS”. You will also need a copy of this file in the Windows installation directory on all your Spark clients. Here’s an example of what the “krb5.ini” file should look like:
[libdefaults]
default_realm = REALM.COM
default_tkt_enctypes = rc4-hmac des3-cbc-sha1 des-cbc-crc des-cbc-md5
default_tgs_enctypes = rc4-hmac des3-cbc-sha1 des-cbc-crc des-cbc-md5
permitted_enctypes = rc4-hmac des3-cbc-sha1 des-cbc-crc des-cbc-md5 [realms]
REALM.COM = {
kdc = kdc1.domain.com
admin_server = kdc1.domain.com
default_domain = domain.com
} [domain_realms]
domain.com = REALM.COM
.domain.com = REALM.COM
For example, if my Windows Active Directory domain was named “intranet.com” then my Kerberos realm would be “INTRANET.COM” (case is important for realm name) and my KDC host/Domain Controller was named “dc1” then my krb5.ini would look like this:
[libdefaults]
default_realm = INTRANET.COM
default_tkt_enctypes = rc4-hmac des3-cbc-sha1 des-cbc-crc des-cbc-md5
default_tgs_enctypes = rc4-hmac des3-cbc-sha1 des-cbc-crc des-cbc-md5
permitted_enctypes = rc4-hmac des3-cbc-sha1 des-cbc-crc des-cbc-md5 [realms]
INTRANET.COM = {
kdc = dc1.intranet.com
admin_server = dc1.intranet.com
default_domain = intranet.com
} [domain_realms]
intranet.com = INTRANET.COM
.intranet.com = INTRANET.COM
- Enable GSSAPI in Openfire by adding the following section to your “openfire.xml” configuration file:
<!-- sasl configuration --> <sasl> <mechs>GSSAPI</mechs> <!-- Set this to your Keberos realm name which is usually your AD domain name in all caps. -->
<realm>REALM.COM</realm> <gssapi> <!-- You can set this to false once you have everything working. -->
<debug>true</debug> <!-- Set this to the location of your gss.conf file created earlier -->
<!-- "/" is used in the path here not "\" even though this is on Windows. -->
<config>C:/Program Files/Openfire/conf/gss.conf</config> <useSubjectCredsOnly>false</useSubjectCredsOnly> </gssapi> </sasl>
<authorization> <classList>org.jivesoftware.openfire.auth.DefaultAuthorizationPolicy</classList> </authorization>
-
If your Openfire service is still running log into the WebAdmin and add/set the “xmpp.fqdn” property to the fqdn of your Openfire server, if Openfire is not currently running then start it and set the property. We used “servername.domain.com” as the fqdn in all the examples above.
-
Restart your Openfire server.
Configure Windows Spark clients for SSO + Kerberos.
-
Place a copy of the “krb5.ini” file we created on the Openfire server earlier in the Windows installation directory on your Spark client. Usually this is “C:\WINNT” or “C:\WINDOWS”.
-
Add the following values to the Windows registry of all your Spark clients to allow Java to access the Windows Kerberos ticket 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, SP3… :
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos
Value Name: AllowTGTSessionKey
Value Type: REG_DWORD
Value: 1
-
Restart your Windows client machines for these changes to take effect.
-
Once the XP machine is back up, log onto the machine using a domain user account.
-
Start the Spark client. If you get any login errors ignore them for now.
-
Configure your Spark client and enable the SSO Login option on the SSO tab. On the SSO tab, Spark should report what username it will attempt to use when logging into the Openfire server. If it reports something about “Unable to find principal” then you’ve done something wrong. Go back to the “Configure Windows Spark clients for SSO + Kerberos” section of this document.
Configure Mac OS X Spark clients for SSO + Kerberos.
Before you begin this process you need to make sure you are running Mac OS X Tiger 10.4.3 or higher and the latest Java 5.0 from Apple. If you’re not or you’re not sure, use the Software Update to download and install the latest Mac OS X 10.4 Tiger update and the latest Java 5.0 from Apple. You must also have your machine correctly bound to the Windows Active Directory domain.
-
Go to Utilities and start the Terminal application.
-
Run the following command at the prompt to create a symbolic link to the Mac Kerberos configuration file:
sudo ln -s /Library/Preferences/edu.mit.Kerberos /etc/krb5.conf
Note: You will need administrative access to successfully complete this command. sudo will prompt you for the admin password.
-
Restart your Mac client machines for these changes to take effect.
-
Once the machine is back up, log onto the machine using a domain user account.
-
Start the Spark client. If you get any login errors ignore them for now.
-
Configure your Spark client and enable the SSO Login option on the SSO tab. On the SSO tab, Spark should report what username it will attempt to use when logging into the Openfire server. If it reports something about “Unable to find principal” then you’ve done something wrong. Go back to the “Configure Mac OS X Spark clients for SSO + Kerberos” section of this document.
All done! Give it a whirl and see if this works for you. This worked for me after nothing else did so hopefully everyone can benefit from this document.