HOWTO: SSO Configuration for Windows (Server and Clients) and Mac Clients

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.

  1. Log onto your KDC host/Domain Controller using an Domain Administrator account and install the utilities you just downloaded for your version of Windows.

  2. 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.

  3. 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.

  4. 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.

  1. 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.

  1. 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.

  1. 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.

  1. 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.

  1. 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
  1. 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>
  1. 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.

  2. Restart your Openfire server.

Configure Windows Spark clients for SSO + Kerberos.

  1. 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”.

  2. 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
  1. Restart your Windows client machines for these changes to take effect.

  2. Once the XP machine is back up, log onto the machine using a domain user account.

  3. Start the Spark client. If you get any login errors ignore them for now.

  4. 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.

  1. Go to Utilities and start the Terminal application.

  2. 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.

  1. Restart your Mac client machines for these changes to take effect.

  2. Once the machine is back up, log onto the machine using a domain user account.

  3. Start the Spark client. If you get any login errors ignore them for now.

  4. 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.

1 Like

Is there a similar procedure for Openfire on a linux server?

how os this working on linux, i experience some problems while setting up this.

The gss.conf should include the line “isInitiator=false”, at least when Kerberos is from Active Directory.

realm= is optional. (at least, it worked for me without being set)

If the openfire server is running samba and properly joined to the domain, use of ktpass (and the associated creation of a separate user account) can be skipped in favor of samba’s “net ads keytab add xmpp”. This will associate the relevant service principal with the computer account in AD instead of a user account as ktpass does. However, this will not work unless “isInitiator=false” is set in gss.conf. ‘net ads status’ can be used to verify the existence of the service principal.

For step #5

Where do we do this in the web admin page?

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.

I think I found it. I added it to system properties under server manager.

this drove me nuts t rying to get it to work for 5 days.

Fresh install, only configure AD.

Also use/ try

setspn -A xmpp/servername.domain.com@REALM.COM xmpp-openfire

setspn -A xmpp/servername.domain.com xmpp-openfire

Try both java and windows keytab. Java gives me errors on console, windows works.

I’ve gotten it to work on two servers now with this setup.

Good luck.

If anyone wants to know how to use Pidgin as a SSO client instead of Spark:

Download and install MIT Kerberos for Windows. It will run the net id mgr in the background. It seems to reference the same c:\windows\krb5.ini you should already have setup. No real configing to do inside of pidgin itself, as it just worked after I installed KfW.

I made it works - OPenFire (on RH5.4) + AD (W2k3) + Spark (win Vista).

I still have some issues:

  • SSO + OpenFire work on embedded DB, but not with MysQL. If anyone can make it work with MySQL, please give me some tips.

  • I still have trouble to get multiple AD domains. I can’t see or search the users from other domains. i.e.

I set openfire at ABC.DEF.COM, I can see all users in ABC.DEF.COM, but can’t see anyone on XYZ.DEF.COM. All the domains in AD are setup both-way trusted. I used kerberos ticket to authenticate users. I believe I missed some thing, but couldn’t figure out yet.

Any help is appreciated.

dannytrinh, how did you config the RedHat box? I’ve only been able to get SSO working using a Windows server. Did you use samba to join the linux server to the AD domain? Any special Kerberos stuff you needed to do in Linux?

I’m not sure why it should matter which DB you’re using. I wouldn’t think it’d be related to whether or not SSO works…

This has essentially worked for me by joining to AD using Samba and then using samba’s ‘net ads keytab…’ commands to generate the keytab file, in place of the whole ktpass/setspn thing.

it works fine for me (on Ubuntu) with the MySQL backend, but I didn’t have to do anything special.

1 Like

Does anyone know how to do this in a multi-domain AD environment, using the Global Catalog?

I ran through the configuration process, using port 3268 (Global Catalog) instead of 389 (LDAP). Connectivity and authentication works fine and allows users from multiple domains to authenticate. I then configured the Kerberos SSO by creating the XMPP user in the Root domain. The results are mixed. Users from the Root domain are able to login using SSO but users from any of the sub (child) domains cannot. I tried defining the multiple domaind in the krb5.ini sections as shown below, but that did not seem to help.

[realms]

ZEVEL.CORP = {

kdc = imsdc03.zevel.corp

admin_server = imsdc03.zevel.corp

default_domain = zevel.corp

}

AUBURNHILLS.ZEVEL.CORP = {

kdc = imsdc04.auburnhills.zevel.corp

admin_server = imsdc04.auburnhills.zevel.corp

default_domain = auburnhills.zevel.corp

}

[domain_realms]

zevel.corp = ZEVEL.CORP

.zevel.corp = ZEVEL.CORP

auburnhills.zevel.corp = AUBURNHILLS.ZEVEL.CORP

.auburnhills.zevel.corp = AUBURNHILLS.ZEVEL.CORP

Any ideas / help would be appreciated.

Thanks.

I think it might be helpful to add a note on your docs above that say to put the information you are adding to the openfire.xml file before

if not you get a bunch of errors and openfire wont start.

What about use Pidgin as a SSO client in CentOS? I did all the setup, but now I still can’t connect to Openfire server use Pidgin as client. I created a ticket in Openfire SSO Configuration , do you have any thoughts of it?