Unanet Authentication / Single Sign-On

This functionality is only available for On-Premise (self hosted) customers and is not available for those customers with an On Demand Subscription.

Unanet can be configured to authenticate users using several techniques. These various configurations can also be used in conjunction with one another. This help page will discuss the configuration requirements for each type of setup in further detail.

Note that in order to allow single sign-on, your IE and Firefox users will need to make a one time browser configuration change.  See the Configure Internet Explorer and Configure Firefox sections below.

Topics covered on this help page include:

Platform Considerations

While the External Authentication should work on any supported platform, the Automatic Login  feature is currently only supported for customers using the following combination of components:


Browser ID/Password Dialog Box

When using the Automatic Login feature, your users may still encounter a browser userid and password dialog window (depending on their browser and its configuration).

Internet Explorer Browsers

See Configuring Internet Explorer notes below regarding browser  configuration for avoiding dialog window.

Firefox Browsers

See Configuring Firefox notes below regarding browser configuration for avoiding dialog window.

Configuring Advanced Authentication

In order to configure alternative authentication, you need to consider the following items.

User Name Requirements

In order for your system to authenticate with an Active Directory domain, your Unanet usernames will need to match the corresponding usernames in your Active Directory domain.  Likewise, usernames in your authenticating Active Directory domains must be unique across all of the authenticating domains.  It is perfectly legal in Active Directory to have duplicate usernames as long as the users are in different domains.  Unanet, however, will identify users exclusive of their authenticating domain, causing duplicate usernames to be viewed as the same user.

Property Settings

To enable this feature, add the following property to your unanet.properties file (note, you cannot configure the  Authentication Type (unanet.authentication) property via the User Interface, it must be established in the unanet.properties file).  


Authentication Configuration File

This file is used to control the various methods that Unanet will use to attempt authentication and the sequence in which each method will be attempted.  You may need to configure more than one option, for example, if most of your users will be using their LAN access yet you also have subcontractors that do not have LAN ids.    

For Tomcat, you will need to edit the  jaas.config file.

Tomcat Configuration

Create a file named jaas.config located in your Unanet /config directory (details below).  You can base your file on the sample-jaas.config file (which is supplied with your software installation also located in the /config directory).

The Java Virtual Machine (JVM) in which Tomcat (and Unanet) is running must know the location of the jaas.config file. If you are running on a Linux or UNIX platform, then you must configure the CATALINA_OPTS environment variable to include:

- Djava.security.auth.login.config=/your/path/to/unanet/config/jaas.config


If you are running as a service on Windows, then you must run the "Configure Tomcat" program from the Windows menu. Then select the "Java" tab and edit the "Java Options" to include:



Using, of course, the correct location of your jaas.config file.

If Tomcat is running under IIS using Integrated Windows Authentication, you will need to ensure that IIS authentication credentials are passed through to the Unanet application.  To do so, you must edit the Tomcat server.xml file and ensure that the Connector entry for protocol="AJP/1.3" has the following attribute defined tomcatAuthentication=”false”.

Configuration File Content

This file will be made up of a Unanet container with one or more authentication modules specified.  The Unanet container is simply the word  "unanet" followed by an open bracket, followed by the authentication methods, followed by a closing bracket (see example below).

unanet {
com.unanet.security.IisLoginModule sufficient domain="YOURDOMAIN";
com.unanet.security.NtlmLoginModule sufficient balance="true" domain="YOURDOMAIN";
com.unanet.security.SmbLoginModule sufficient  balance="true" domain="YOURDOMAIN";
com.unanet.security.UnanetLoginModule required;


Unanet provides four Authentication modules, each enabling a distinct authentication method.





Each authentication module line is comprised of the following elements:

Login Module Name - valid values include:

Required Indicator - valid values include:

Balance Option - This option is only applicable to the com.unanet.security.SmbLoginModule or com.unanet.security.NtlmLoginModule login modules.  When set to "true", the login module will rotate through the available controllers defined in your domain when authenticating users.

IMPORTANT: This option should only be set to "true" if the specified domain of the login module is a Pre-Windows 2000 (NetBIOS) domain name.

If the specified domain is not a Pre-Windows 2000 (NetBIOS) domain name (ie Active Directory DNS domain name), this option should not be used at all.

Domain – Active Directory domain.  In the configuration file example above, replace "YOURDOMAIN" with the name of your Active Directory domain.  This value can either be the Pre-Windows 2000 (NetBIOS) domain name or the Active Directory DNS domain name.  This attribute is not applicable with the UnanetLoginModule option.  

To verify that you are using the correct value, you could execute the following command from a windows command prompt to see what your domain is named:  


  C:\>  net view /domain




Active Directory Pre-Authentication

If using the com.unanet.security.NtlmLoginModule to authenticate against a domain controller that requires SMB signatures (Windows 2003 does by default), you will need to provide a domain user id to perform "preauthentication" against the domain controller so that a proper SMB signing key can be generated.

The preauthentication id must be a valid user id in the domain and needs only to have basic privileges.  This user id will be authenticated against the domain to establish a proper SMB signing key.  Individual users being authenticated using the NtlmLoginModule will continue to use their own credentials for authentication against the Active Directory domain and not this preauthentication user's credentials.

You will need to define two java system properties to establish the preauthentication user:




For example setting:




See Tomcat Configuration above for example of how to set java system properties.

Configuring IIS

If you are using the IisLoginModule option, you'll need to edit the properties for the web servers that are used as front-ends to Tomcat.  Select the "Directory Security" tab and then click the "Edit..." button in the "Anonymous access and authentication control" section. Clear the "Anonymous access" checkbox. In the "Authenticated access" section, make sure that only "Integrated Windows authentication" is checked.

If you are authenticating users against a complex Active Directory environment (i.e. multiple authenticating domains), you will need to ensure that your JAAS configuration file contains an IisLoginModule entry for each authenticating domain.

Note: When IIS is forcing Integrated Windows Authentication, users without Active Directory credentials will be completely prevented from accessing Unanet.

Configuring Internet Explorer

If you are using either the IisLoginModule or NtlmLoginModule option, your Internet Explorer users may want to modify their browser settings.  By default, Internet Explorer will only allow automatic login for sites in its Intranet zone.  For sites not included in the specified Intranet Zones, a windows dialog box will popup requesting login information.  This popup can be avoided by having your users modify their Intranet Zone settings as described below.

IE will recognize a site as being in its Intranet zone in one of two ways.

  1. The name of the server that you are accessing does not have a dot in the name. For example, http://timesheet.

  2. The site is configured as an Intranet site for IE.


To configure the Intranet sites for IE, open IE and select "Tools > Internet Options...". Then select the "Security" tab, click on the "Local intranet" icon, and then click on the "Sites..." and finally, the Advanced button. Type the full name of the Unanet server, including protocol, in the first field. For example:



If you are using SSL, then replace "http" with "https". Then click the "Add" button. Click the "Close" and "OK" buttons to back out. Now IE should recognize the Unanet server as being part of its Intranet zone.

Configuring Firefox

If you are using either the IisLoginModule or NtlmLoginModule option, your Firefox users may want to modify their browser settings.  By default, Firefox will prevent automatic login.  Sites requiring NTLM authentication will cause a windows dialog box to popup requesting login information.  This popup can be avoided by having your users modify their Firefox settings as described below.

In the Firefox address bar type about:config.  This will display all settings for Firefox.  In the filter box type ntlm and hit the enter key.  This will narrow the display items to those pertaining to NTLM authentication.

Double click on the key entry network.automatic-ntlm-auth.trusted.uris.  This is a comma separated list of trusted servers for which automatic NTLM authentication is enabled. In the edit box displayed, enter the name of the server you are accessing.  For example, http://timesheet.  If you are using SSL, replace http with https.  Click the OK button.  Firefox should now enable automatic NTLM authentication with the Unanet server.

Example Configuration Files

Example 1

The following describes a typical configuration when using IIS as the front-end to Tomcat.  This configuration attempts to automatically login users using their Active Directory credentials (and thus bypass the Unanet login screen).

Automatic login is conditional to the user being logged in to a valid domain, having their browser configured to enable automatic login against the Unanet server, and the user’s Active Directory username matching their Unanet username.  If all of the previous conditions are met, the user will be automatically logged into the Unanet application.

If either of the first two conditions are not met, the user will be presented with an NTLM login screen by their browser. If the user is unable to provide valid Active Directory credentials, the user will be completely prevented from accessing the Unanet application by IIS.

If the user successfully authenticates against an Active Directory domain, but their Active Directory username is not recognized by Unanet, they will be presented with the Unanet login screen. At the Unanet login screen, the user can enter a username and password that will be validated against the values contained in the Unanet database.

unanet {
com.unanet.security.IisLoginModule sufficient domain="YOURDOMAIN";
com.unanet.security.UnanetLoginModule required;


Example 2

This example is similar to Example 1, except it describes a typical configuration for enabling automatic login for installations that are not using IIS.  Without IIS as a front-end, Unanet handles the management of all user authentication.  Because of this, the key difference between Example 1 and this example is that all users will be presented with the Unanet login screen, not merely those users that can provide valid Active Directory credentials.

unanet {
com.unanet.security. NtlmLoginModule sufficient balance="true" domain="YOURDOMAIN";
com.unanet.security.UnanetLoginModule required;


Example 3

This example is enables external authentication against Active Directory, but does not provide for automatic login.  All users will be presented with the Unanet login screen, at which they can be authenticated using either their Active Directory credentials or their Unanet credentials.   

unanet {
com.unanet.security.SmbLoginModule sufficient balance="true" domain="YOURDOMAIN";
com.unanet.security.UnanetLoginModule required;


In the example above,  validation proceeds as follows:

1. The user will be presented the Unanet login screen, at which they will enter their username and password and click the login button.

2. The username and password are validated against the Active Directory server domain defined.  If the validation succeeds and the username is a valid Unanet user, then the user is presented with the Unanet home page (or other specified page).  If the validation fails or the username is not valid in the Unanet database, then validation continues with the next step.

3. The username and password are validated against the encrypted password stored in the Unanet database.  If this succeeds, then the user is presented with the Unanet home page (or other specified page). If this fails, then the user is presented with the login page containing an error message. If ALL users are expected to have an Active Directory account, then the Unanet login module may be unnecessary and the line may be removed from the configuration file.  (Note:  The second word in the last line of this file should always be "required", so if you do delete the existing last line, then you must change the word "sufficient" on the preceding line to "required").  There are some reasons that you may want to leave the Unanet login module as the final fallback, such as:


If you leave the Unanet login module as the last step, but only intend it to be used by a few users, then the passwords for those users should either:


You should not set the passwords to some value common to all users, since anyone knowing this value can then log in as any user.

When the password is never set, the password column in the person table for that user is set to a string of 32 zeros.  This value will never allow the user to log in.  There is currently no way in the application to reset the user's password back to this value once the password has been set.  This could be done directly in the database, or the same effect could be accomplished by setting the user's password to some random value either directly through the Unanet user interface or via the person import.

Note: if you are using Single Sign-on and are also using the Unanet Login option, you will want to avoid using the Unanet password expiration feature.

Log out Redirect

If you are using the single sign on features, you may not want your users to see the standard Unanet login page when they click on the logout link on the main menu.  In this case, you can use the Logout Redirect URL  (unanet.logout.redirect) property to facilitate redirecting your users to a custom destination.