Windows Integrated Authentication for Crowd-enabled Applications

Description/Features

Automatic Logon to Crowd-enabled Applications in a Windows Domain.

Windows Integrated Authentication (or Integrated Windows Authentication) allows Windows domain users to log into web applications without providing an application password. This functionality can be provided through Kerberos or NTLM.

The plugin provided here implements Windows Integrated Authentication for Crowd-enabled applications (e.g.: your own applications, Atlassian Confluence, Jira, Crowd's administration console, etc.).

The latest version implements both NTLM and Kerberos.

Prerequisites

The plugin has been tested with Crowd Server 1.5.2 in a "full Windows" environment:

• Active Directory 2003
• Tomcat v5.5, v6 (Windows 2003)
• WebSphere Application Server v6.1.0.13 (NTLM version only, Windows 2003)
• MS Internet Explorer v6, v7 (Win XP, 2003)
• Mozilla Firefox v2, v3 (Win XP, 2003)

Other versions (Linux, GlassFish, Opera etc.) might work as well. Please let me know about successful deployments.

Please note that Java 6 and Windows 2003 SP1 are required to run the Kerberos implementation.

Usage

The Windows Integrated Authentication plugin is a simple servlet filter. It first checks wether the user owns a valid Crowd token or not. If not, it sends a Kerberos or NTLM challenge to the user. If the challenge succeeds, it creates a Crowd token for that user.

The target application must be linked (through Crowd's Administration Console) to a directory (Internal, LDAP etc.) that contains the same userid as the one used to logon to the Windows workstation. That userid (the one in Crowd's directory) should be either in lower case (e.g.: bruno) or upper case (e.g.: BRUNO) format, but not in a mix of them (e.g. Bruno). The format of the Windows username does not matter.

Set up Windows Integrated Authentication

First of all, install and configure Crowd SSO for your application (see Atlassian Documentation).

Then, choose either NTLM or Kerberos as an authentication method and follow the corresponding steps.

Set up NTLM Authentication

Install and Configure the servlet filter

1. Download the latest WindowsIntegratedAuth_X.X.jar, jcifs-Y.Y.Y.jar and log4j.properties from the attachments of this page
2. Copy those files to the WEB-INF/lib folder of your application
3. Copy the log4j.properties file to the WEB-INF/classes folder of your application
4. Edit WEB-INF/web.xml

Add the following lines before the other filters:

 
<filter> 
    <filter-name>VerifyCrowdNtlmTokenFilter</filter-name> 
    <filter-class>com.itekia.crowd.integration.VerifyCrowdNtlmTokenFilter</filter-class> 
    <init-param> 
        <param-name>jcifs.http.domainController</param-name> 
        <param-value>Domain_Controller_FQDN</param-value> 
    </init-param> 
    <init-param> 
        <param-name>jcifs.smb.client.domain</param-name> 
        <param-value>Windows_Domain_Name</param-value> 
    </init-param> 
    <init-param> 
        <param-name>jcifs.resolveOrder</param-name> 
        <param-value>DNS</param-value> 
    </init-param> 
    <init-param> 
        <param-name>jcifs.smb.client.username</param-name> 
        <param-value>Windows_Account_With_Read_Rights</param-value> 
    </init-param> 
    <init-param> 
        <param-name>jcifs.smb.client.password</param-name> 
        <param-value>Windows_Account_Password</param-value> 
    </init-param> 
</filter> 

jCIFS parameters are fully detailed on jCIFS's website.

Then, add the following lines before the other filter mappings:

 
<filter-mapping> 
    <filter-name>VerifyCrowdNtlmTokenFilter</filter-name> 
    <url-pattern>/*</url-pattern> 
</filter-mapping> 

The url-pattern should be the same as the one used by VerifyTokenFilter (which is provided by Atlassian). Please note that you do not need VerifyTokenFilter anymore since the Windows Integrated Authentication filter checks wether the user owns a valid Crowd token before trying an NTLM challenge. However, you might keep it for simpler integration. This would only mean that users' tokens would be validated twice.

Configure Internet Explorer and Mozilla Firefox

In Internet Explorer, go to Tools > Internet Options > Local intranet > Sites > Advanced
And add your intranet, e.g.: http://*.itekia.com

In Firefox, type about:config in the address bar.
Then edit network.automatic-ntlm-auth.trusted-uris and add your intranet, e.g.: .itekia.com

Test NTLM Authentication

Restart your application and open its home page using Firefox or Internet Explorer, e.g. http://confluence.itekia.com:8080/ or http://crowd.itekia.com:8095/crowd/

You should be logged on automatically. If not, verify that your browser is enabled for NTLM authentication (otherwise you will see an authentication popup window) and that the userid in the directory that is linked to the application is the same as the one you used to logon to your Windows Workstation.

Set up Kerberos Authentication

Configure Kerberos in Active Directory

1. Download and install the Windows Support tools from this link.
2. Create a regular Windows user in Active Directory. Let's call him crowd.
3. Type the following line in a command prompt. This will map crowd to a Kerberos Service Principal Name (SPN):

ktpass -out appsrv.keytab -princ HTTP/Fqdn_Of_Your_Application_Server@YOUR_WINDOWS_DOMAIN -mapuser crowd -pass Crowd_User_Password -ptype KRB5_NT_PRINCIPAL

For instance:

ktpass -out appsrv.keytab -princ HTTP/my.appserver.itekia.com@ITEKIA.COM -mapuser crowd -pass password -ptype KRB5_NT_PRINCIPAL

Configure Kerberos in your application server

1. Copy appsrv.keytab from Active Directory to your application server
2. Edit C:\Kerberos\jaas-krb5.conf

com.sun.security.jgss.accept {
  com.sun.security.auth.module.Krb5LoginModule required 
  storeKey=true 
  keyTab="c:\\Kerberos\\appsrv.keytab" 
  doNotPrompt=true 
  useKeyTab=true 
  realm="YOUR_WINDOWS_DOMAIN" 
  principal="HTTP/Fqdn_Of_Your_Application_Server" 
  debug=true;
};

For instance:

com.sun.security.jgss.accept {
  com.sun.security.auth.module.Krb5LoginModule required 
  storeKey=true 
  keyTab="c:\\Kerberos\\appsrv.keytab" 
  doNotPrompt=true 
  useKeyTab=true 
  realm="ITEKIA.COM" 
  principal="HTTP/my.appserver.itekia.com@ITEKIA.COM" 
  debug=true;
};

Then edit C:\Kerberos\krb5.conf

[libdefaults]
     default_realm = YOUR_WINDOWS_DOMAIN
     default_tkt_enctypes = des-cbc-md5 rc4-hmac
     default_tgs_enctypes = des-cbc-md5 rc4-hmac
[realms]
     YOUR_WINDOWS_DOMAIN = {
     kdc = Fqdn_Of_Your_Active_Directory_Server:88
     default_domain = .your_windows_domain_extension
     }
[domain_realm]
     .your_windows_domain_extension = YOUR_WINDOWS_DOMAIN

For instance:

[libdefaults]
     default_realm = ITEKIA.COM
     default_tkt_enctypes = des-cbc-md5 rc4-hmac
     default_tgs_enctypes = des-cbc-md5 rc4-hmac
[realms]
     ITEKIA.COM = {
     kdc = itekia-win2003.itekia.com:88
     default_domain = .itekia.com
     }
[domain_realm]
     .itekia.com = ITEKIA.COM

Then add the following Java options to the startup script of your application server (e.g.: you might do this in setenv.bat for a Tomcat application server):

-Djava.security.auth.login.config=C:\Kerberos\jaas-krb5.conf
-Djavax.security.auth.useSubjectCredsOnly=false
-Djava.security.krb5.conf=C:\Kerberos\krb5.conf

Install and Configure the servlet filter

1. Download the latest WindowsIntegratedAuth_X.X.jar and log4j.properties from the attachments of this page
2. Copy WindowsIntegratedAuth_X.X.jar to the WEB-INF/lib folder of your application
3. Copy the log4j.properties file to the WEB-INF/classes folder of your application
4. Edit WEB-INF/web.xml

Add the following lines before the other filters:

<filter>
    <filter-name>VerifyCrowdKerberosTokenFilter</filter-name>
    <filter-class>com.itekia.crowd.integration.VerifyCrowdKerberosTokenFilter</filter-class>
    <init-param>
        <param-name>kerberos.application.principal</param-name>
        <param-value>HTTP/Fqdn_Of_Your_Application_Server</param-value>
   </init-param>
</filter>

Then, add the following lines before the other filter mappings:

 
<filter-mapping> 
    <filter-name>VerifyCrowdKerberosTokenFilter</filter-name> 
    <url-pattern>/*</url-pattern> 
</filter-mapping> 

The url-pattern should be the same as the one used by VerifyTokenFilter (which is provided by Atlassian). Please note that you do not need VerifyTokenFilter anymore since the Windows Integrated Authentication filter checks wether the user owns a valid Crowd token before trying a Kerberos challenge. However, you might keep it for simpler integration. This would only mean that users' tokens would be validated twice.

Configure Internet Explorer and Mozilla Firefox

In Internet Explorer, go to Tools > Internet Options > Local intranet > Sites > Advanced
And add your intranet, e.g.: http://*.itekia.com

In Firefox, type about:config in the address bar.
Then edit network.negotiate-auth.trusted-uris and add your intranet, e.g.: .itekia.com

Test Kerberos Authentication

Restart your application and open its home page using Firefox or Internet Explorer, e.g. http://confluence.itekia.com:8080/ or http://crowd.itekia.com:8095/crowd/

You should be logged on automatically. If not, verify that your browser is enabled for Kerberos authentication (otherwise you will see the usual application login form) and that the userid in the directory that is linked to the application is the same as the one you used to logon to your Windows Workstation.

Version History

Limitations

The Kerberos implementation relies on Java 6. If your application server runs on an earlier version of Sun's JRE, you should consider using NTLM instead.