Contelligent - Single-Sign-On with Contelligent

1) Introduction and Requirements
2) Configuring Windows Group Policies
3) Active Directory Server Preparation
4) Configuring the Contelligent server
5) Launching the Contelligent client
6) Configuring the web browser
7) Multiple host names
8) Feedback

Print version

1) Introduction and Requirements

In modern corporate environments, users have become used to Single-Sign-On (SSO) without being aware of it. The most common case is that of a Windows-based shop where clients can access resources like file shares or web pages on all machines in the network without having to reenter their passwords. With modern Windows versions (Windows 2000/XP on the clients and Windows 2000/2003 on the server), it is now easily possible to integrate Contelligent with this mechanism.

Some background: With the release of Windows 2000, Microsoft completely changed the way their systems performed authentication with each other. Where during the NT4 era Windows employed a proprietary protocol, this was now changed to a far more powerful system marketed under the name Active Directory.

Under the hood, Active Directory (AD for short) consists of several well-established technologies: Most notably an LDAP directory service as a central store for domain configuration and user data, and a Kerberos 5 implementation for SSO network authentication.

Now, what does that mean? LDAP stands for Lightweight Directory Access Protocol, as specified in RFC 2251. A Windows Active Directory server always provides an LDAP service through which clients with proper authorization can access any data relevant to the domain. This ranges from user accounts and group memberships over lists of important file shares to domain policies.

Kerberos is an authentication protocol designed for safe usage even in unsecured network environments. Microsoft also provides an introduction to Kerberos.

In order to configure your Contelligent installation for SSO, you will need to meet the following requirements: (Note that the specified minimum versions are important!)

Contelligent 9.0.13 or newer
Windows domain controller: Windows 2000 Server or Windows 2003 Server (latest service pack required)
Windows client: Windows 2000 Professional or Windows XP Professional (latest service pack required)
Java 1.4.2_07 or newer 1.4.x on both Contelligent client and server systems (Java 1.5 is not supported for Contelligent 9.0)
Browser: At least Internet Explorer 6.0 or Firefox 1.0.3

If you would like to use RC4-HMAC encryption instead of DES, there are the following requirements additionally:

Contelligent 9.1.0 or newer
Windows domain controller: Windows Server 2003 R2 (latest service pack required)
Windows client: Windows XP Professional (latest service pack required)
Java 1.5.0_07 or newer on both Contelligent client and server systems

In place of Windows XP Professional, you can also use the Domain-enabled editions of Windows Vista and Windows 7 (named Business, Professional, Enterprise and Ultimate).

The target audience of this document are expert users proficient in administration of Windows servers, since some preparation on the Windows side is necessary to set up SSO. Also, previous experience in editing Contelligent configuration files is necessary.

All examples, provided screenshots and paths are for a setup consisting of Windows 2000 Server and Contelligent installed on JBoss 3.2.5 application server running on a Linux system.

2) Configuring Windows group policies

First, you will have to set up certain domain policies in order to enable Contelligent to hook into the Windows authentication mechanism. For this, you can download an administrative template file here: Download Contelligent SSO Administrative Template

Transfer this template to the directory "inf" below your "windows" or "winnt" directory on your Active Directory server. (See Figure 1)

Figure 1: The proper location for the ADM file

Now open a group policy that will be applied to both the client machines as well as all users that are intended to use the SSO functionality. (See Figures 2 and 3)

Figure 2: Opening the domain properties

Figure 3: Opening the policy editor

Once you are in the Group Policy Editor, make sure that the options "Show Policies Only" and "Show Configured Policies Only" are both disabled (see Figure 4). If one of them is enabled, you will not be able to follow the next steps.

Figure 4: The options that have to be disabled

Now click the node "Administrative Templates" and select "Add/Remove Templates" from the context menu. (Figure 5)

Figure 5: The "Add/Remove Templates" entry

You will get a dialog window listing all available policy templates for this policy. By clicking the "Add..." button, you will get a file picker dialog where you can select the "contelligent-sso.adm" file. (Figures 6 and 7)

Figure 6: The "Add/Remove Templates" dialog

Figure 7: Selecting the template file

Now close the dialog. The template is now available for your policy. First navigate to "Computer Configuration\Administrative Templates\System\Logon" and enable the policy entries "Enable Kerberos Tickets for Windows 2000 SP3/SP4, 2003" and "Enable Kerberos Tickets for Windows XP SP2". (Figure 8)

Figure 8: Policies for Computer Configuration

There is also a user-dependent entry which you can find under "User Configuration/Administrative Templates/Windows Components/Internet Explorer". Set "Enable Integrated Windows Authentication" to "Enabled" here. (Figure 9)

Figure 9: Policy for User Configuration

If your client is using Windows 7 and you are using the DES encryption types, you will also have to reenable DES support, as described by Microsoft at: http://technet.microsoft.com/en-us/library/dd560670%28WS.10%29.aspx

That step is not necessary if using the RC4 encryption type, as Windows 7 supports that by default.

3) Active Directory Server Preparation

Now, there are a few tasks we still have to do on the Active Directory server. If using DES encryption instead of RC4-HMAC, you have to change every user account to use DES encryption. Also make sure that the flag "Account is sensitive and cannot be delegated" is not set since that would prevent SSO from working. (See Figure 10)

Figure 10: Configuring an account for DES encryption

After the DES flag is enabled, the user must change his password at least once for the change in encryption type to take effect. Again, this is not necessary when using RC4-HMAC.

Finally, with either encryption type, Contelligent needs two new user accounts for communication with the AD server; one for logging in to the LDAP service and one for Kerberos. For the LDAP account, simply create a regular domain user account. Apart from having to be in the domain users group no special settings or permissions are required for this account. Make sure, the user account will never have to change its password. Write down the username and password for this account, as you will need this later. For the examples in this document, we will use the username "ldap-contell".

The Kerberos account is a little harder to create, since you will have to use a tool from the Windows Support Tools. These are not automatically installed when you set you your server, but can be found on the Windows Server install CD under \SUPPORT\TOOLS. Run the file SETUP.EXE found in that directory. This will install KTPASS.EXE, a command line utility for configuring this kind of Kerberos account.

Now start by creating another regular domain user, which again should have a never expiring password. For our examples, we will use the username "krb-contell". Now, as a domain admin user, run the KTPASS utility as follows:

ktpass -princ HTTP/examplehost.yourdomain.com@YOURWINDOWSDOMAIN.COM -pass somethingsecret -mapuser krb-contell -out c:\contell.host.keytab

Of course, you will have to fill in the proper values for your environment. Be aware that the "HTTP/examplehost.yourdomain.com@YOURWINDOWSDOMAIN.COM" parameter is case-sensitive and the "HTTP" must be in uppercase. The "examplehost.yourdomain.com" part has to be replaced with exactly the hostname that you will later use to access your Contelligent server (without the http protocol part or a port number). "YOURWINDOWSDOMAIN.COM" is supposed to be the Windows 2000 compatible name of your Windows domain (not the NT4 name). For the password ("somethingsecret" in the example), just pick something hard to guess since you won't be needing this password later. The "krb-contell" part must be the name of the Kerberos domain user you just created and the final part "c:\contell.host.keytab" is where KTPASS will create a key file that you must transfer to your Contelligent server system.

The output should then look similiar to the following:

C:\Documents and Settings\Administrator>ktpass -princ HTTP/krusty.c1-fse.de@C1-FSE.DE -pass ufg7fj4ju -mapuser krb-contell -out c:\contell.host.keytab Successfully mapped HTTP/krusty.c1-fse.de to krb-contell. Key created. Output keytab to c:\contell.host.keytab: Keytab version: 0x502 keysize 58 HTTP/krusty.c1-fse.de@C1-FSE.DE ptype 1 (KRB5_NT_PRINCIPAL) vno 1 etype 0x1 (DES-CBC-CRC) keylength 8 (0x0123456789abcdef) Account has been set for DES-only encryption. C:\Documents and Settings\Administrator>

For Windows Server 2003, the command syntax has slightly changed. Here is an example call using RC4-HMAC encryption:

ktpass -princ HTTP/krusty.c1-fse.de@C1-FSE.DE -pass ufg7fj4ju -mapuser krb-contell@c1-fse.de -crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPAL -mapOp set -out c:\contell.host.keytab

4) Configuring the Contelligent server

Now we are ready to set up the Contelligent server itself. First, create a Kerberos system config file (/etc/krb5.conf for Linux) like this:

[libdefaults] default_realm = YOURWINDOWSDOMAIN.COM kdc_timesync = 1 ccache_type = 4 forwardable = false proxiable = false default_tgs_enctypes = des-cbc-crc des-cbc-md5 default_tkt_enctypes = des-cbc-crc des-cbc-md5 [realms] YOURDWINDOWSDOMAIN.COM = { kdc = adserverhostname:88 admin_server = adserverhostname default_domain = yourwindowsdomain.com } [domain_realm] .yourwindowsdomain.com = YOURWINDOWSDOMAIN.COM yourwindowsdomain.com = YOURWINDOWSDOMAIN.COM .yourwindowsdomain = YOURWINDOWSDOMAIN.COM yourwindowsdomain = YOURWINDOWSDOMAIN.COM

If using RC4-HMAC encryption, the lines for "default_tgs_enctypes" and "default_tkt_enctypes" must instead read:

default_tgs_enctypes = rc4-hmac default_tkt_enctypes = rc4-hmac

Open the file "jboss-3.2.5/server/default/conf/login-config.xml" in your favorite editor and add the following block at the bottom, just before the "</policy>" tag:

As always, change the parameters to match your environment. The path "/home/contelligent/contell.host.keytab" in this example has to point to the keytab file that you created on your AD server.

You should also increase the maximum HTTP header size permitted by the embedded Tomcat installation, since with Single-Sign-On HTTP headers may exceed the default of 4kb in complex Active Directory environments. Add a property maxHttpHeaderSize="32768" to your HTTP connector configuration in 'jboss-3.2.5/server/default/deploy/jbossweb-tomcat50.sar/server.xml'. If your HTTP headers become larger than this setting, Tomcat just discards the requests without any log output, which can cause a lot of trouble.

Now, navigate to your "contelligentHome/config" directory. We will have to create a new project configuration file to introduce the new user and role groups for our Windows users to Contelligent. Create a new file called "ldap-project.xml" in your editor and start by pasting the following in there:

<?xml version="1.0"?> <!DOCTYPE project PUBLIC "-//finix AG/contelligent/Project Configuration V1.1/EN" "http://www.c1-fse.de/contelligent/dtds/package-import_1_1.dtd"> <project> <security> <groups> <roleGroup groupId="ldap-roles" class="de.finix.contelligent.core.security.ADRoleGroup"> <adminRole roleId="admin" groupId="system-roles"/> <initParam name="ldapURL" value="ldap://adserverhostname:389"/> <initParam name="rootDN" value="CN=Builtin,DC=yourwindowsdomain,DC=com"/> <initParam name="listUser" value="ldap-contell"/> <initParam name="listPassword" value="password"/> <initParam name="validTime" value="300"/> <initParam name="retryTime" value="30"/> </roleGroup> <roleGroup groupId="ldap-roles2" class="de.finix.contelligent.core.security.ADRoleGroup"> <adminRole roleId="admin" groupId="system-roles"/> <initParam name="ldapURL" value="ldap://adserverhostname:389"/> <initParam name="rootDN" value="OU=Domain Groups,DC=yourwindowsdomain,DC=com"/> <initParam name="listUser" value="ldap-contell"/> <initParam name="listPassword" value="password"/> <initParam name="validTime" value="300"/> <initParam name="retryTime" value="30"/> </roleGroup> <userGroup groupId="ldap-users" negoDomains="YOURWINDOWSDOMAIN.COM" authDomains="#id#" clientlogin="true" class="de.finix.contelligent.core.security.ADUserGroup" autologin="false"> <adminRole roleId="admin" groupId="system-roles"/> <defaultRole roleId="user" groupId="system-roles"/> <initParam name="ldapURL" value="ldap://adserverhostname:389"/> <initParam name="rootDN" value="OU=Employees,DC=yourwindowsdomain,DC=com"/> <initParam name="domain" value="yourwindowsdomain.com"/> <initParam name="listUser" value="ldap-contell"/> <initParam name="listPassword" value="password"/> <initParam name="validTime" value="300"/> <initParam name="retryTime" value="30"/> </userGroup> </groups> </security> </project>

Note that the "authDomains" attribute on the ldap-users user group ("#id#") must be entered exactly like that. The "listUser" and "listPassword" parameters are the username and password of the LDAP account we set up earlier. "validTime" determines how often the principal group should retrieve new data from the LDAP server; this parameter is in seconds. "retryTime" determines how long the group should wait to retry if communication with the LDAP server failed for some reason. During this time, the group will use cached data.

The "rootDN" parameters determine the LDAP base path (DN stands for Distinguished Name) for searching users (for userGroups) or groups (for roleGroups). Be aware that although it might seem tempting, you can't set the "rootDN" parameter to match your whole directory ("DC=yourwindowsdomain,DC=com") since that way you will most likely hit a builtin query size limit in the LDAP server and retrieving the data will fail. Always operate on Organizational Units below the root.

Finally, add the parameters "-Djavax.security.auth.useSubjectCredsOnly=false -Dcontelligent.krb5.realm=YOURWINDOWSDOMAIN.COM -Dcontelligent.krb5.kdc=adserverhostname -Dcontelligent.krb5.hostnames=examplehost.yourdomain.com" to your Contelligent server start script and restart Contelligent through this.

5) Launching the Contelligent client

Now that the server is configured, we are almost ready to log in through the Contelligent client. First, you might want to make sure that the changes in the Windows domain policy have been applied to your system, by rebooting it.

The last thing you have to do to enable SSO support for your client, is to create a file ".java.login.config" in your Windows user home directory (e.g. "c:\Documents and Settings\mrating\.java.login.config").

Note that the Windows Explorer will not allow you to start a file name with a dot. To work around that, create the file as "java.login.config" (without the starting dot) and then rename it on the command prompt. The file should contain the following:

com.sun.security.jgss.initiate { com.sun.security.auth.module.Krb5LoginModule required debug=true useTicketCache=true doNotPrompt=true; }; contelligent.auth.sso.negotiate { com.sun.security.auth.module.Krb5LoginModule required debug=true useTicketCache=true doNotPrompt=true; }; contelligent.auth.sso.negotiate.preauth { com.sun.security.auth.module.Krb5LoginModule required debug=true doNotPrompt=false storeKey=true; };

Then, simply point your browser to your regular client launch page ("http://examplehost.yourdomain.com/contell/client" or similiar) and click on the "Contelligent Client" link. When the client comes up now, it should automatically log in, provided that you followed all previous configuration sections correctly. You can confirm your user data in the session module.

You will find that apart from the session module the client is no configured for your user yet, but don't worry. Simply click the key icon in the toolbar to bring up the login dialog manually and sign in using your regular admin account. That way, you will be able to configure new modules for your SSO users and roles. When you restart the client it will again sign in through SSO.

6) Configuring the web browser

For our last step, we will also configure the web browser to use SSO, so it will automatically access web pages stored in Contelligent as your Windows user. This is possible for both Internet Explorer and Firefox.

For Internet Explorer: Add the Contelligent server URL to the list of local intranet sites. To do so, open the Internet Options dialog and select the "Security" tab. There, click first on the "Local intranet" icon and then on the "Sites..." button below. Select "Advanced..." here and then type something like "http://examplehost.yourdomain.com". Do not enter a port number in this field, even if you have to enter one to access Contelligent. Click on the "Add" button then and make sure the checkbox next to "Require server verification (https:) for all sites in this zone" is not checked. Then close all dialogs using the OK button.

For Firefox: Type "about:config" (without the quotes) in the adress field and hit Enter. This should result in a long list of configuration variables being displayed. Type "nego" (again without the quotes) in the "Filter" field at the top of this list and double-click the line labeled "network.negotiate-auth.trusted-uris". A dialog with a single input field should open. Type "http://examplehost.yourdomain.com" here and click OK. If you need to enter multiple URLs into this, you can use a comma-separated list like "http://firsthost.yourdomain.com,http://secondhost.yourdomain.com". Again, make sure not to enter a port number here.

To test these settings, open the URL "http://examplehost.yourdomain.com/contell/scms/ServerInfo". Note the "scms" part: Requests through this path use SSO, whereas the old "cms" uses the old authentication system. If your browser now displays a big block of XML data, then everything went well and you are now signed in through SSO. If on the other hand an authentication dialog pops up, the SSO handshake failed and you will have to check your settings again.

7) Multiple host names

Starting with Contelligent 9.0.17 it is possible to configure the system to allow Single-Sign-On through multiple host names pointing at the same server. To do so, you first have to generate a second Kerberos principal for the additional host name on the Active Directory server, as described in section 3. Make sure to store the key for this new principal in the same keytab file as the first key, as otherwise the second key will not work. (This is a bug in the Kerberos implementation of the Sun JDK)

Now copy the extended keytab to the Contelligent server and edit the login-config.xml (see Section 4). For two host names, change the application-policy block as follows: (Changing examplehost.yourdomain.com and secondhost.yourdomain.com to your actual host names)

<application-policy name = "com.sun.security.jgss.accept"> <authentication> <login-module code = "com.sun.security.auth.module.Krb5LoginModule" flag = "required"> <module-option name = "debug">true</module-option> <module-option name = "principal">HTTP/examplehost.yourdomain.com@YOURWINDOWSDOMAIN.COM</module-option> <module-option name = "kdc">adserverhostname</module-option> <module-option name = "realm">YOURWINDOWSDOMAIN.COM</module-option> <module-option name = "storeKey">true</module-option> <module-option name = "useKeyTab">true</module-option> <module-option name = "doNotPrompt">true</module-option> <module-option name = "keyTab">/home/contelligent/contell.host.keytab</module-option> </login-module> <login-module code = "com.sun.security.auth.module.Krb5LoginModule" flag = "required"> <module-option name = "debug">true</module-option> <module-option name = "principal">HTTP/secondhost.yourdomain.com@YOURWINDOWSDOMAIN.COM</module-option> <module-option name = "kdc">adserverhostname</module-option> <module-option name = "realm">YOURWINDOWSDOMAIN.COM</module-option> <module-option name = "storeKey">true</module-option> <module-option name = "useKeyTab">true</module-option> <module-option name = "doNotPrompt">true</module-option> <module-option name = "keyTab">/home/contelligent/contell.host.keytab</module-option> </login-module> </authentication> </application-policy>

Finally, you have to add a parameter "-Dcontelligent.krb5.hostnames=examplehost.yourdomain.com,secondhost.yourdomain.com" to your Contelligent start script to let the server know which host names should be enabled for Single-Sign-On authentification.

8) Feedback

Feel free to contact support@contelligent.de if you have any questions or want to provide some feedback.

Table of Contents