|
|
|
|
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)
Authentication Configuration File (Tomcat specific instructions)
Configuring IIS (only necessary when used with IisLoginModule)
Configuring Internet Explorer (only necessary when used with IisLoginModule)
Configuring Firefox (only necessary when used with IisLoginModule)
You may also be interested in:
Quick Topic - Configuring SAML for Single Sign On (search for this topic in the Knowledge Center)
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.
To configure alternative authentication, you need to consider the following items.
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.
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 |
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.
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 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 and a semicolon (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 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 (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 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 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.UnanetLoginModule - The default Unanet 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 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. Note the SMBLoginModule 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 login module. 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 (i.e. Active Directory DNS domain name), this option should not be used at all.
Domain – Active Directory domain. In the configuration file example below, 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 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" check box. 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 the IisLoginModule 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 pop up 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, click on the Sites button, 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 the IisLoginModule 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 pop up 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 bear the warning of voiding your warranty, and you will accept the risk:
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://unanet.com. If you are using SSL, replace http with https. Click the OK button.
View of ntlm menu after save:
Firefox should now enable automatic NTLM authentication with the Unanet server. From here, you should be able to close the browser, open it again, and test access to your Unanet site. There should be no additional Windows pop ups requesting additional authentication.
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 { |
Example 2
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 3
This example 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 point they can be authenticated using either their Active Directory credentials or their Unanet credentials.
|
unanet { |
In the example above, validation proceeds as follows:
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 Logout Redirect URL (unanet.logout.redirect) property to facilitate redirecting your users to a custom destination.
