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.

• Unanet Authentication - The default application behavior is to authenticate a user using the user id and password stored in the Unanet database.

• External Authentication - - Unanet can be configured to authenticate users against an Active Directory Domain or SAML Identity Provider.

• Automatic Login - Finally, you can configure Unanet to work in conjunction with your Active Directory Domain or SAML Identity Provider to automatically grant access to the user once they have been authenticated to Active Directory or Identity Provider.

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   (Supported Platforms)

• Configuring Advanced Authentication

• • User Name Requirements

  • Property Settings

  • Authentication Configuration File   (Tomcat specific instructions)

• Unanet Login Module Options

• Active Directory Pre-Authentication   (only necessary when used with  NtlmLoginModule)

• Configuring IIS   (only necessary when used with IisLoginModule)

• Configuring Internet Explorer   (only necessary when used with IisLoginModule or NtlmLoginModule)

• Configuring Firefox   (only necessary when used with IisLoginModule or NtlmLoginModule)

• Log out Redirect

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:

• Tomcat / IIS

• Tomcat (stand-alone)

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

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:

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

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

IisLoginModule

• Leverages an IIS front-end to permit automatic login using Active Directory credentials.  IIS manages the authentication challenge-response and only permits authenticated Active Directory users access to the Unanet application.

• Requires that the IIS front-end is forcing Windows Integrated Authentication, and that anonymous login is disabled.  This implies that every user attempting to access the Unanet application through the IIS front-end is required to have valid Active Directory credentials.  If a user cannot authenticate via Active Directory credentials, they will be denied access by IIS before they ever get to the Unanet application.

• Active Directory Authentication in a complex forest requires a specific IisLoginModule entry in the JAAS Application definition for each domain that is expected to authenticate users via IIS for the Unanet application.  Any user that has been authenticated by IIS against a trusted forest domain that is not defined in the Unanet JAAS Application definition will be denied application access.

• For Unanet authentication to uniquely map Active Directory users to Unanet usernames, Active Directory usernames must be unique across the entire Active Directory forest.  Unanet authentication maps Active Directory users to Unanet usernames via user login name, not their fully qualified UPN login.  While Active Directory allows for duplicate user login names across a forest if the fully qualified UPN name is unique, Unanet authentication does not recognize users as distinct in that situation.

SamlLoginModule

• Leverages a SAML Identity Provider to authenticate users.  The SAML Identity Provider manages the authentication challenge-response, and only presents users authenticated by the Identity Provider to the Unanet application.

• Requires that the Unanet application is using SSL and the HTTPS protocol.

• Requires that assertions returned by the SAML Identity Provider are signed.

• Requires that the Subject NameId returned for users authenticated via the SAML Identity Provider uniquely map to Unanet usernames.

SMBLoginModule

• Permits manual login via the Unanet login screen using Active Directory credentials.

• For Unanet authentication to uniquely map Active Directory users to Unanet usernames, Active Directory usernames must be unique across the entire Active Directory forest.  Unanet authentication maps Active Directory users to Unanet usernames via user login name, not their fully qualified UPN login.  While Active Directory allows for duplicate user login names across a forest as long as the fully qualified UPN name is unique, Unanet authentication does not recognize users as distinct in that situation.

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

• Permits automatic login via NTLM using Active Directory credentials.  Directly manages the NTLM challenge-response negotiation.

• When authenticating against a Windows 2003 Active Directory Server that requires SMB signing, a valid Active Directory pre-authentication id must be defined to prevent unverifiable signature errors during NTLM authentication requests.  By default, Windows 2003 Active Directory Server requires SMB signing.

• For Unanet authentication to uniquely map Active Directory users to Unanet usernames, Active Directory usernames must be unique across the entire Active Directory forest.  Unanet authentication maps Active Directory users to Unanet usernames via user login name, not their fully qualified UPN login.  While Active Directory allows for duplicate user login names across a forest if the fully qualified UPN name is unique, Unanet authentication does not recognize users as distinct in that situation.

UnanetLoginModule

• Permits user authentication via the Unanet login screen, using credentials stored in the Unanet database.

• Required when using the command-line import.

Each authentication module entry is comprised of the following elements:

Login Module Name - valid values include:

• com.unanet.security.lisLoginModule - Enables automatic login through an IIS front-end.  IIS authenticates users against Active Directory and Unanet maps the authenticated users to Unanet user ids based on their Active Directory username.

• com.unanet.security.SamlLoginModule - Enables authentication against a SAML Identity Provider.  The Identity Provider authenticates users and Unanet maps the authenticated users to Unanet user ids based on the Subject Name Id returned by the Identity Provider.

• com.unanet.security.SmbLoginModule – Enables external authentication against Active Directory using the Unanet login page.

• com.unanet.security.NtlmLoginModule – Enables automatic login by directly authenticating against Active Directory using NTLM.

• com.unanet.security.UnanetLoginModule - The default Unanet default login method, which uses the Unanet database for authentication.

Required Indicator - valid values include:

• Required - The LoginModule is required to succeed.  If it succeeds or fails, authentication still continues to proceed down the LoginModule list.

• Requisite - The LoginModule is required to succeed.  If it succeeds, authentication continues down the LoginModule list.  If it fails, control immediately returns to the application (authentication does not proceed down the LoginModule list).

• Sufficient - The LoginModule is not required to succeed.  If it does succeed, control immediately returns to the application (authentication does not proceed down the LoginModule list). If it fails, authentication continues down the LoginModule list.

• Optional - The LoginModule is not required to succeed.  If it succeeds or fails, authentication still continues to proceed down the LoginModule list.

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.

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:  

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

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.

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.

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.   

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:

• Never be set

• Set to some value unknown to the user, or

• Set directly in the database to some value (e.g., a string of 32 zeros).  

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.