SSO Configuration

Version 9

    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

    1. 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.
    2. Create a Service Principal and Keytab for Openfire. This makes Kerberos aware of Openfire. You'll do this on the KDC host.
    3. Transfer the Keytab File to the Openfire Host. This provides a place for Openfire to cache credential information.
    4. Values in this file set the GSSAPI's policy for interacting with Kerberos.
    5. Edit Openfire Configuration to Add Kerberos Support. The new values will configure Openfire's support for authentication providers, including Kerberos via the GSSAPI.
    6. Testing. Check for the correct amount of network traffic.
    7. 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.

    1. Log into the kadmin command.
    2. 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

       

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

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

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

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

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

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

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

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

    1. Change directory into the jre\bin folder within your Openfire installation directory or your Java installation directory.

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

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

    1. Create a file "gss.conf" in the openfire conf directory.

    2. 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 &lt;provider&gt; 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 &lt;provider&gt; 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 &lt;auth type="GSSAPI"&gt; 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 &lt;providers&gt; section of openfire.xml and make sure that you have something listed for &lt;authorization&gt;. What should be listed in this section has changed from version to version. A common problem is having multiple &lt;provider&gt; sections. Openfire will only use one &lt;provider&gt; 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.