ART Wiki

A Reporting Tool

Brought to you by: eliboni, tanyona

Integrated Windows Authentication

Labels: manual (35)

Authors:

Integrated Windows Authentication

ART uses the spnego library available at http://spnego.sourceforge.net/ to provide Integrated Windows Authentication functionality. These instructions are largely based on the documentation found on that project's website.

Prerequisites

You need to have at least 3 separate machines as follows

Active Directory server (or other KDC server)
Application server (a different machine where the application server e.g. Tomcat is installed)
Client machine(s) (from where you'll access ART)

On the Active Directory server

Create a user in AD to be used for authentication purposes. This user doesn't need to have access to log in to computers. e.g. a user named spnego. Set the password to never expire
Create spns that point to the application server/spnego user combination using the setspn command. Use syntax like below
```
setspn -A HTTP/app-server spnego
setspn -A HTTP/app-server.domainname spnego
```

Replace app-server with the appropriate machine name of the application server, my.domain.com with the domain name and spnego with the username of the domain account to be used for spnego access. If you'll also be accessing the web application on the application server via ip address e.g. http://192.168.56.101:8080/art, also create spns for the ip address. Examples

    setspn -A HTTP/app-server spnego
    setspn -A HTTP/app-server.my.domain.com spnego
    setspn -A HTTP/192.168.56.101 spnego
    setspn -A HTTP/192.168.56.101.my.domain.com spnego

On the Application server

Create a file in the ART_HOME\WEB-INF directory named login.conf with the following details

spnego-client {
    com.sun.security.auth.module.Krb5LoginModule required;
};

spnego-server {
    com.sun.security.auth.module.Krb5LoginModule required
    storeKey=true
    isInitiator=false;
};

Create a file in the ART_HOME\WEB-INF directory named krb5.conf with the following details. Replace MY.DOMAIN.COM with your domain name. For the kdc parameter, use the fully qualified domain name of the AD server.

[libdefaults]   
    default_realm = MY.DOMAIN.COM
    default_tkt_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
    default_tgs_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
    permitted_enctypes   = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc

[realms]
    MY.DOMAIN.COM  = {
        kdc = ad-server.my.domain.com
        default_domain = MY.DOMAIN.COM 
}

[domain_realm]
    .MY.DOMAIN.COM = MY.DOMAIN.COM

Edit the ART_HOME\WEB-INF\web.xml file and add a filter as below. Replace the spnego.preauth.username and spnego.preauth.password parameter values with the details of the domain account created to enable spnego access. Replace the spnego.krb5.conf and spnego.login.conf parameter values with the full path of the respective files. Leave all the other parameters as they are. The spnego filter mapping must come before other filter mapping elements.

<filter>
    <filter-name>SpnegoHttpFilter</filter-name>
    <filter-class>net.sourceforge.spnego.SpnegoHttpFilter</filter-class>

    <init-param>
        <param-name>spnego.allow.basic</param-name>
        <param-value>true</param-value>
    </init-param>

    <init-param>
        <param-name>spnego.allow.localhost</param-name>
        <param-value>false</param-value>
    </init-param>

    <init-param>
        <param-name>spnego.allow.unsecure.basic</param-name>
        <param-value>true</param-value>
    </init-param>

    <init-param>
        <param-name>spnego.login.client.module</param-name>
        <param-value>spnego-client</param-value>
    </init-param>

    <init-param>
        <param-name>spnego.krb5.conf</param-name>
        <param-value>C:\tomcat\webapps\art\WEB-INF\krb5.conf</param-value>
    </init-param>

    <init-param>
        <param-name>spnego.login.conf</param-name>
        <param-value>C:\tomcat\webapps\art\WEB-INF\login.conf</param-value>
    </init-param>

    <init-param>
        <param-name>spnego.preauth.username</param-name>
        <param-value>spnego</param-value>
    </init-param>

    <init-param>
        <param-name>spnego.preauth.password</param-name>
        <param-value>spnego</param-value>
    </init-param>

    <init-param>
        <param-name>spnego.login.server.module</param-name>
        <param-value>spnego-server</param-value>
    </init-param>

    <init-param>
        <param-name>spnego.prompt.ntlm</param-name>
        <param-value>true</param-value>
    </init-param>

    <init-param>
        <param-name>spnego.logger.level</param-name>
        <param-value>1</param-value>
    </init-param>
</filter>
<filter-mapping>
    <filter-name>SpnegoHttpFilter</filter-name>
    <url-pattern>*.jsp</url-pattern>     
</filter-mapping>

On the client machine

The Default Authentication Method for ART needs to have been set to Auto (done in the Settings page)
Login to a client machine using a domain account
Access the ART home page as usual

Omitting the credentials box

Firefox
By default, firefox will still display a credentials box requiring a user to enter their domain username and password. To avoid this, do the following
- In the address bar, type about:config
- In the filter box, type network.negotiate
- Double click on the network.negotiate-auth.trusted-uris option and enter the url of the application server (excluding the http part and including port number if not port 80) e.g. app-server:8080
If the credentials box is still displayed, set the following options in a similar way
- network.negotiate-auth.delegation-uris
- network.automatic-ntlm-auth.trusted-uris
IE
For IE, the credentials box may be displayed if you access the web application using an ip address. To avoid this, do the following
- Under internet options, security, local intranet, sites, click on advanced and add the url to the application server e.g. http://192.168.56.101:8080

Using a keytab file

Instead of having the spnego username and password in plain text in the web.xml file, you can use a keytab file to hold these credentials. Take the following steps on the application server

Stop tomcat
Copy the file ART_HOME\WEB-INF\krb5.conf to the windows directory e.g. C:\windows
Rename the file to krb5.ini
Open a command prompt window, cd to the ART_HOME\WEB-INF directory and type a command with syntax like the following
```
ktab -a <spnego user> <spnego password> -k <file name>
```

E.g.

    ktab -a spnego spnego -k art.keytab

Edit the ART_HOME\WEB-INF\login.conf file to have contents like the following. Set the full path to the keytab file and the spnego username (principal) as per your configuration

spnego-client {
    com.sun.security.auth.module.Krb5LoginModule required;
};

spnego-server {
    com.sun.security.auth.module.Krb5LoginModule required
    storeKey=true
    useKeyTab=true
    keyTab="file:///c:/tomcat/webapps/art/WEB-INF/art.keytab"
    principal=spnego;
};

Edit the ART_HOME\WEB-INF\web.xml file. Make the spnego.preauth.username and spnego.preauth.password parameters blank. i.e.

<init-param>
    <param-name>spnego.preauth.username</param-name>
    <param-value></param-value>
</init-param>

<init-param>
    <param-name>spnego.preauth.password</param-name>
    <param-value></param-value>
</init-param>

Restart tomcat

You should have integrated authentication as before

Changing the spnego user

If you need to change the AD user used to enable spnego access, first delete the spns associated with the application server and then create new ones for the desired user. An spn for a given server can only refer to a single user. To delete the spns, you can use syntax similar to the following

    setspn -D HTTP/app-server spnego
    setspn -D HTTP/app-server.my.domain.com spnego