External Authentication

Content

Overview

LabVantage External Authentication uses LDAP (Lightweight Directory Access Protocol) to verify contact information from an LDAP server (Directory System Agent).

Here is an example of basic External Authentication functionality:

1.		When someone logs onto LabVantage, External Validation sends the entered Username and Password to the Application Server.

2.		The LabVantage Application Server calls the LDAP Server (LDAP URL) and sends it the DN (Distinguished Name associated with the Username) and account defined by the External Validation rules set in the Authentication Property Manager.

3.		If the DN is defined in the account and the Password is correct, the LDAP server sends a verification to the Application Server.

4.		The Application Server checks to see if the verified user is a LabVantage User registered in the LabVantage Database. If so, it logs the User onto LabVantage. If not, the attempted logon fails, unless the External Validation rules tell the Application Server to create a new LabVantage User.... in which case, a new LabVantage User is created for the user verified through LDAP authentication.

These additional configuration features are also available:

•	When automatically creating a LabVantage User from an LDAP User, LabVantage allows using a specific User Template to create the LabVantage User based on the User's LDAP attributes.
•	When an existing LabVantage User logs on through External Authentication, LabVantage can synchronize the LabVantage User's Job Types based on the User's LDAP attributes.

LabVantage External Authentication has been evaluated with Microsoft Active Directory (does not have anonymous binding) and Oracle Internet Directory (anonymous binding was also evaluated).

References

Top

RFC 1777, set forth by the Internet Engineering Task Force, describes the current LDAP specification. The IETF provides access to many other documents concerning LDAP operation and command syntax (such as RFC 2255 for URL format). Visit www.ietf.org for information that is not specific to LabVantage.

Authentication Property Manager

Top

The following properties specify External Validation rules. All properties except "Default User To Create" are mandatory.

Property Name

Description

Enable LDAP Authentication

"Yes" enables the External Authentication feature through the LDAP server. A user with an "Authentication Type" of "Internal" (defined on the User Maintenance Page) uses LabVantage authentication.

"No" disables the External Authentication feature through the LDAP server and uses LabVantage authentication. The user's "Authentication Type" is ignored.

NOTE:

You must restart the application server after enabling External Authentication.

Disabling External Authentication does not require a restart.

Call LDAP for ESignature

"Yes" calls the LDAP Server every time a user verification is requested during a LabVantage session (such as logon, verification through Electronic Signature, and so on).

"No" calls the LDAP Server only during logon. Subsequent user verifications (such as Electronic Signature) are based on the single logon password validation, which is used throughout the entire LabVantage session.

Sync LDAP User Password to LabVantage

By default, LabVantage synchronizes a User's LDAP password with his LabVantage password. This option breaks this association to prevent LabVantage from storing the LDAP password.

LDAP URL with Base DN

URL of the LDAP Server with the Distinguished Name of the Directory Information Tree root. This is not a full LDAP URL that specifies various attributes, a scope, and filter settings. LabVantage uses this only to find the LDAP Server. Accordingly, use the following syntax to specify this value:

ldap://host:port/dc

where

•	host is the name of the LDAP Server, e.g., dc2.hal.com
•	port is the LDAP Server port (defaults to 389)
•	dc is the DNS domain name, e.g., dc=hal, dc=com specifies the domain hal.com

Example: dc2.hal.com:389/dc=hal,dc=com finds the DNS with hal in the .com top level domain.

Root User DN

Distinguished Name of a user in the account. Root User DN and Root User Password (below) are not required if the LDAP Server allows anonymous binding.

Example: The binding string cn=mobutu,cn=users,dc=hal,dc=com specifies a DN, where:

cn=mobutu	Common name of the user.
cn=users	Common name of the container users.
dc=hal,dc=com	Domain hal.com.

Root User Password

Password used by the LDAP Server to verify the person identified by the Root User DN.

The RDN for the User Search

Relative Distinguished Name used to search for users in the Directory Information Tree.

You can search for a user in multiple LDAP tree nodes, provided each userid on the LDAP server is unique. To do this, use a double-pipe (||) as separators. For example...

cn=users||cn=specialusers,cn=users||cn=people

...searches both the specialusers and people nodes of the users tree.

In addition to searching for users LDAP tree nodes defined by this property, LabVantage also searches all subtree nodes for the user if a user is not in the defined node.

Attribute Name of User ID

Attribute used by the LDAP Server as the logon name of the user. If using Microsoft Active Directory, this would generally be SAMAccountName. The user�s logon name would then be taken from the SAMAccountName attribute.

Secondary LDAP Servers

Allows additional LDAP servers to be defined with the property "LDAP URL with Base DN". All other properties for additional servers are assumed to be the same.

The primary server is defined by "LDAP URL with Base DN", which will be the server that authenticates users. If the primary server is not available, a warning message is written to the log, and the next available LDAP server will be used to authenticate users. If all servers are unavailable, an error is generated. The "Test Connection" button indicates a successful connection only if all servers test successfully. "Test Connection" opens a dialog that shows the "Current LDAP Server", which is the server being used for user authentication.

LDAP To LV User Mapping

Allows a new LabVantage User to be automatically created for someone who is verified through LDAP authentication but not currently in the LabVantage Database, or synchronize LDAP attributes to an existing LabVantage User on User Logon.

Property Name

Description

User Mapping Option

Determines how the LabVantage User is created, or synchronized if the User exists:

Option

Description

Basic

The "Basic" option makes these properties available: "Create User", "User Template", and "User Column Value Mappings".

This is the fundamental configuration mode. You can create the LabVantage User from a User (SDI) Template, and set the value of additional columns in the SysUser table (which override the User Template).

To maintain backward-compatibility with older LabVantage versions, this is option set in the OOB configuration.

Advanced

The "Advanced" option makes these properties available: "Create User", "User Column Value Mappings", and "Advanced User Mapping".

This configuration mode provides these advanced features:

•	When automatically creating a LabVantage User from an LDAP User, a specific User Template can be used to create the LabVantage User based on the User's LDAP attributes.
•	When an existing LabVantage User logs on through External Authentication, the LabVantage User's Job Types will be synchonized based on the User's LDAP attributes.

Create User

Determines if a new LabVantage User is created after LDAP authentication if the user does not exist in the LabVantage database.

User Column Value Mappings

Column values in the SysUser table to use when creating a new LabVantage User. These override values in the User Template.

Property Name	Description
Identifier	Unique identifier for this item, rendered as an ID attribute in the HTML tag.
ColumnId	Column Id in the SysUser table.
Value	Value of the column.

You can use variables to synchronize a user's attributes defined on the LDAP Server with those defined in LabVantage. In order to do this, each user name on the LDAP Server must be unique.

For example, suppose name is an attribute that defines a user's name on the LDAP Server. To use the value of the LDAP Server's name attribute as the LabVantage sysuserid, you would specify:

Column Id	sysuserid
Value	[name]

Use one of these formats when specifying variables for the Value property:

•

[LDAPname]

where

LDAPname is the user's attribute on the LDAP Server

•

[LDAPname(n,x)case]

where

•	n = minimum character length
•	x = maximum character length
•	case = upper or lower case (U or L) - this is optional

Examples:

[name(0,10)] means the value of the name attribute, from 0 to 10 characters in length.

[name(0,10)U] means the name attribute, from 0 to 10 characters in length, upper case.

Advanced User Mapping

Provides options when creating the LabVantage User based on the User's LDAP attributes.

Property Name

Description

Create User Template Mappings

When automatically creating a LabVantage User from an LDAP User, this allows a specific User Template to be used to create the LabVantage User based on the User's LDAP attributes.

Property Name	Description
Id	Unique identifier for this item, rendered as an ID attribute in the HTML tag.
Mapping Expression	Groovy expression to determine which User Template to use to create the LabVantage User. The first User Template where the Groovy expression evaluates to "true" will be used to create the User. If none evaluate to "true", no Template is used to create the User.
User Template	User Template used to create the LabVantage user. Note in "Mapping Expression" (Above) that this will the first User Template where the Groovy expression evaluates to "true".

User Job Type Mappings

When an existing LabVantage User logs on through External Authentication, this synchronizes the LabVantage User's Job Types based on the User's LDAP attributes.

Property Name	Description
Id	Unique identifier for this item, rendered as an ID attribute in the HTML tag.
Mapping Expression	Groovy expression to synchronize the LabVantage User's Job Types based on the User's LDAP attributes. Any Job Type in the collection where the corresponding Groovy expression evaluates to "true" will be added to the User if it does not already exist. Any existing Job Type that is not in the evaluated set of Job Types is removed from the User. If the collection has no item defined, no synchronization of Job Types occurs.
Job Type	Job Type to synchronize to user if Mapping Expression evaluates to true. Note in "Mapping Expression" (above) that this will be any Job Type in the collection where the corresponding Groovy expression evaluates to "true".

NOTE:

Available variables for the Groovy expression are:

•	ldapuser.[attribute] (a semicolon-separated string of attribute values).
•	ldapuser.[attribute]List (a List object of attribute values).

Below are two examples of Groovy expressions for a typical Active Directory configuration. Note that attribute names are different for different LDAP servers, and any LDAP attribute can be used. The following examples uses the "memberof" attribute.

•

Is the User a member of the "Development" group?

Using exact match:

ldapuser.memberofList.contains( 'CN=Development,OU=Department Universal Security Groups,OU=SecurityGroups,DC=lims,DC=com');

Using simple string contents:

ldapuser.memberof.indexOf( 'CN=Development')>=0;

•

Is the User a member of both the "Development" and "Support" groups?

ldapuser.memberof.indexOf( 'CN=Development')>=0 && ldapuser.memberof.indexOf( 'CN=Support')>=0;

LDAP to User Message Mappings

Allows LDAP error messages to be displayed in a more user-friendly manner:

Property Name

Description

LDAP Error Contains

Accepts a literal string. LabVantage will match this string to the error message issued by the LDAP server. When a match is found, the "User Message" is displayed (below).

User Message

Message displayed when a match is found. Accepts a literal text string. Also accepts two tokens:

•	[currentuser] returns the SysUserId.
•	[ldaperrormessage] returns the original error message from the LDAP server.

For example, this can be a string such as "Password expired" or "User not found for [currentuser]".

If these values are not specified, a generic message is issued to maintain backward-compatibility.

These buttons are available:

Save

Saves all changes.

Test Connection

Pings the LDAP server and reports a success or failure message.

Java API

The BaseAuthentication API provides hooks for customized external authentication code. The DefaultAuthentication API provides default implementations of the authenticateUser and createUser methods (but not the synchronizeUser method) for LDAP V2- and V3-compatible servers.