Unanet Authentication / Single Sign-On

The full Single Sign-On functionality is only available for On-Premise (self hosted) customers.

SAML Single Sign-On is an available option for On Demand customers who would like to integrate with their own existing Identity Provider.  Contact Unanet Support for details.

 

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 to allow single sign-on against an Active Directory Domain, 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

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

User Name Requirements

To enable your Unanet system to authenticate users against an external source, your Unanet usernames must match with the usernames for authenticated users supplied by your external source.  If your external source is Active Directory, usernames in your authenticating Active Directory domains must be unique across all authenticating domains.  It is perfectly legal in Active Directory to have duplicate usernames if 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).  

unanet.authentication=jaas


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:

-Djava.security.auth.login.config=c:\unanet\config\jaas.config

 

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 and a semicolon (see example below).
 

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

 

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

IisLoginModule

SamlLoginModule

SMBLoginModule

NTLMLoginModule  (Note this is a deprecated method and should not be configured for new installations.  Support will be dropped for this method in an upcoming release.)

UnanetLoginModule


Each authentication module entry is comprised of the following elements:

Login Module Name - valid values include:

Required Indicator - valid values include:

 

Login Module Options – Each Login Module may additionally accept a list of login module configuration options.  If a login module accepts configuration options, these options are specified as a space-separated list of values in the form name=“value”, where name is the login module option and value is a double-quoted string containing the option’s value.  The specific options available for each Login Module are defined in detail in the Unanet Login Module Options section.

Each authentication module entry is terminated by a semicolon, and the entire configuration file entry is also terminated by a semi-colon.

 


Unanet Login Module Options

Unanet Login Modules can be configured via module-specific options. The configuration options and their descriptions are listed below for each module. Required options are in bold, and they must be specified with their value.  Options in italics, are not required and may be omitted.

IisLoginModule

domain

   
 
Active Directory domain. This value can either be the Pre-Windows 2000 (NetBIOS) domain name or the Active Directory DNS domain name.

SamlLoginModule

 

serviceProvider

 

 

 

The Service Provider’s Entity Id.  This is how the Unanet instance identifies itself to the Identity Provider.

 

acsUrl 

The Service Provider’s Assertion Consumer Service URL.  This is the Unanet instance’s URL that accepts and processes authorization responses from the Identity Provider (IdP).  This will always be the same action, regardless of Unanet instance, but the URL prefix, through context, will be specific for each Unanet instance.
  

idp

The Identity Provider’s Entity Id. This is how the Identity Provider identifies itself to Unanet.
 

idpSSOUrl

The Identity Provider’s Single Sign-On URL.  This is the URL of the Identity Provider that will respond to authentication requests from Unanet.

keystoreFile

The full path to a Java keystore file containing the Identity Provider’s signing certificate.  This file must contain the Identity Provider’s signing certificate with an alias of “idp_signing”.  Note that only the public key from Identity Provider’s signing certificate is expected in this file.
 

keystorePass

The password for the Java keystore file identified in keystoreFile.  This is the password used to create the keystore file, and is required to access the signing certificate contained within it.
 

allowIdpInitiatedSSO    

If set to “true”, allows Identity Provider initiated Single Sign-On.  If your Identity Provider presents authenticated users with a menu of accessible applications, you will want to set this option to “true” to allow the menu link to Unanet to work directly.
 

SMBLoginModule

domain

 

balance

 

 
 
Active Directory domain. This value can either be the Pre-Windows 2000 (NetBIOS) domain name or the Active Directory DNS domain name.
 
If set to “true”, the login module will rotate through the available controllers defined in your domain when authenticating users.  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 (i.e. Active Directory DNS domain name), this option should not be used at all.
 

NTLMLoginModule

domain

 

balance

 

 
 
Active Directory domain. This value can either be the Pre-Windows 2000 (NetBIOS) domain name or the Active Directory DNS domain name.
 
If set to “true”, the login module will rotate through the available controllers defined in your domain when authenticating users.  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 (i.e. Active Directory DNS domain name), this option should not be used at all.
 
Note the NTLMLoginModule is a deprecated module and should not be configured for new installations.  Support will be dropped for this method in an upcoming release.

UnanetLoginModule

 

 

The UnanetLoginModule accepts no configuration options.

 

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

  Domain

  --------------------

  Your_Domain_name_will_appear_here


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:

-Djcifs.smb.client.username=  

-Djcifs.smb.client.password=

 

For example setting:

-Djcifs.smb.client.username=jsmith

-Djcifs.smb.client.password=123!4567

 

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:

http://unanet.yourdomain.com

 

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

The following describes a typical configuration when using a SAML Identity Provider for authentication.  This configuration will redirect users to the Identity Provider for authentication.  User’s that successfully authenticate with the Identity Provider will be redirected back to Unanet and granted access to Unanet.

If the user had authenticated with the Identity Provider before accessing Unanet, the identity provider may automatically present the user to Unanet as authentic.  This would allow the user access to Unanet without requiring them to re-enter their Identity Provider credentials.  This is a function of the Identity Provider, and may or may not be available for your specific Identity Provider.

If the user successfully authenticates against the Identity Provider, but the Subject Name Id returned by the Identity Provider for the user 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.

Note that users navigating directly to the Unanet Login Page will not be automatically redirected to the Identity Provider.  They will be presented with the Unanet Login page.

unanet {

     com.unanet.security.SamlLoginModule sufficient

         serviceProvider=”https://your.company.com/unanet”

         acsUrl=”https://your.company.com/unanet /action/login/validate”

         idp=”http://your.idp.com/saml”

         idpSSOUrl=”http://your.idp.com/saml/sso”

         keystoreFile=”c:\unanet\config\saml.jks”

         keystorePass=”changeit”;

      com.unanet.security.UnanetLoginModule required;

};

 

Example 4

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.