|
|
|
|
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.
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 server.
Automatic Login - Finally, you can configure Unanet to work in conjunction with your Active Directory domain in order to automatically grant access to the user (using NTLM) once they have been authenticated with their network login.
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 (Supported Platforms)
Authentication Configuration File (JRun and Tomcat specific instructions)
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)
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:
JRun / IIS
JRun (stand-alone)
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.
In order to configure alternative authentication, you need to consider the following items.
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.
Add this property to your unanet.properties file:
|
unanet.authentication=jaas |
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.
Depending on your servlet engine, you will either edit the auth.config file (JRun) or jaas.config file (Tomcat).
Servlet Engine Specific Considerations
JRun Configuration
Add a new section to the auth.config file located in your JRun directory (details below). You can base your changes on the examples in the sample-jaas.config file (which is supplied with your software installation also located in the /config directory).
If you are using the default JRun server, then you should find it at JRun4/servers/default/SERVER-INF/auth.config. If you are using a different JRun server then just replace "default" with the name of your JRun server (you'll be adding to the end of the auth.config file).
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”.
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 { |
Unanet provides four 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 NTLM challenge response negotiation and only permits valid Active Directory users access to the Unanet application.
Requires that the IIS front-end is forcing Window Integrated Authentication, and that the 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, or 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/NTLM 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 as long as the fully qualified UPN name is unique, Unanet authentication does not recognize users as distinct in that situation.
NTLMLoginModule
Permits automatic login 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 as long as the fully qualified UPN name is unique, Unanet authentication does not recognize users as distinct in that situation.
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.
UnanetLoginModule
Permits manual login via the Unanet login screen using credentials stored in the Unanet database.
Is required when using the command-line import
Each authentication module line 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 against Active Directory via NTLM, and Unanet maps the authenticated users to Unanet user ids based on their Active Directory username.
com.unanet.security.NtlmLoginModule – Enables automatic login by directly authenticating against Active Directory using NTLM. .
com.unanet.security.SmbLoginModule – Enables external authentication against Active Directory using the Unanet login page.
com.unanet.security.UnanetLoginModule - This is the 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.
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 -------------------- Your_Domain_name_will_appear_here |
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.
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 JRun or 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.
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.
The name of the server that you are accessing does not have a dot in the name. For example, http://timesheet.
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.
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 1
The following describes a typical configuration when using IIS as the front-end to either JRun or 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 { |
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 { |
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 { |
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:
Not all users have Active Directory accounts (e.g., contractors); or
You may have automated processes that need access to Unanet, but don't otherwise require an Active Directory account (e.g. you use the command line import utility).
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.
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 unanet.logout.redirect property to facilitate redirecting your users to a custom destination.
