Windows Integrated Authentication for Crowd-enabled Applications

Name	Windows Integrated Authentication for Crowd-enabled Applications
Version	1.0
Product Versions	Crowd 1.5.2
Author(s)	Bruno Vincent
Homepage	Bruno Vincent
Price	Free
License	LGPL
JavaDocs
IssueTracking
Download	WindowsIntegratedAuth_1.0.jar
Download Source	WindowsIntegratedAuth_src_1.0.zip

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

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

Add the following lines before the other filters:

web.xml_NTLMfilter

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

Please, note that if you use jcifs-1.3.0.jar or above (that you might have downloaded from jCIFS's website), you need to add the following parameter to the latter configuration:

web.xml_NTLMfilter_jcifs-1.3.x

    <init-param>
        <param-name>jcifs.smb.client.useExtendedSecurity</param-name>
        <param-value>false</param-value>
    </init-param>

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

web.xml_NTLMmapping

<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

IE6/7 users also need to add a value to the following registry key: HKEY_CURRENT_USER/Software/Microsoft/Windows/CurrentVersion/Internet Settings/

Value Name: DisableNTLMPreAuthData Type: REG_DWORDValue: 1

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

Download and install the Windows Support tools from this link.
Create a regular Windows user in Active Directory. Let's call him crowd.
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

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

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:

jaas-krb5.conf_example

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

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:

krb5.conf_example

[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

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

Add the following lines before the other filters:

web.xml_Kerberosfilter

<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:

web.xml_Kerberosmapping

<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 > AdvancedAnd 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

Version	Release Date	Description
0.9	November 24th, 2008	Initial Version
1.0	December 26th, 2008	Kerberos Support

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.

Child pages

Description/Features

Prerequisites

Usage

Set up Windows Integrated Authentication

Set up NTLM Authentication

Install and Configure the servlet filter

Configure Internet Explorer and Mozilla Firefox

Test NTLM Authentication

Set up Kerberos Authentication

Configure Kerberos in Active Directory

Configure Kerberos in your application server

Install and Configure the servlet filter

Configure Internet Explorer and Mozilla Firefox

Test Kerberos Authentication

Version History

Limitations

43 Comments