LDAP Connections

When ExtraView is configured to work directly to an LDAP server, the following functions are enabled, all without any need for custom programming within ExtraView:

  • Access to an unlimited number of LDAP fields
  • Customized mapping of one or more fields in ExtraView to one or more fields LDAP fields
  • Customized pre-population of mapped fields on the ExtraView Add and Edit Screens
  • Customized pre-population of fields through a popup link
  • The upsert of data to the ExtraView user table, based on a configuration value. Upsert is a combination of insert and update. If a record exists, it is updated, if it does not exist, it is inserted.

Setup Access Details to your LDAP Server

There are two background tasks that can be used to enhance the LDAP server performance. Only one of these should be configured at one time, and for most purposes, this should be the task titled LDAP Background Task and not the LDAP Synchronization Task.  Click on the links to see the documentation for each of these topics.

There are several behavior settings that control access to your LDAP server. These should be configured first, to provide the basic connection from ExtraView to your LDAP server. These settings are:

Setting Purpose
LDAP_USER_LOOKUP This is the basic on/off switch for LDAP. Set this to YES if you intend to use an LDAP server for user lookup
LDAP_DEFAULT_AREA This is the ID of the business area to associate with a new user who is added to ExtraView via the LDAP server. To find this number, look at the data dictionary field AREA, and click the List button. By each business area you will see the ID. It is essential that you provide a valid entry for this setting.
LDAP_DEFAULT_PROJECT This is the ID of the project within the business area to associate with a new user who is added to ExtraView via the LDAP server. To find this number, look at the data dictionary field PROJECT, and click the List button. Select the business area and you will see a list of the IDs associated with each project. Normally you will choose the DATA project within the business area. It is essential that you provide a valid entry for this setting.
LDAP_HOST This is the URL to your LDAP server. It is essential that you provide a valid entry for this setting.
LDAP_MANAGER The “Security Principal” or user accessing LDAP
LDAP_PSWRD The password to the LDAP server
LDAP_ROOT The root directory of the LDAP server or search base, e.g. ou=blahWorker, o=blah.com. It is essential that you provide a valid entry for this setting.
LDAP_ALLOWED_STALE_INTERVAL The minimum number of minutes between LDAP upsert operations on a single user. This stops ExtraView accessing the LDAP server with every operation that requires user information in order to optimize performance. After this interval, a fresh check of the LDAP server is made. The LDAP Background Task should be running for this to work
LDAP_SEARCH_FILTER LDAP filters may be defined in the behavior setting or may be defined in the Configuration.properties file. The behavior setting takes precedence over the Configuration.properties entry. LDAP filters are defined in RFC 2254. As an example, if you wanted to add a filter to only retrieve records with mycompany within the email address, you could set this as the filter: (mail=*mycompany*) The parentheses are essential.
LDAP_UPSERT This setting controls upserting LDAP information to ExtraView. THe possible values are YES or NO. When this value is NO, LDAP will not be used to add or update ExtraView user information. A valid LDAP user that is not already an ExtraView user will not be able to log in to ExtraView.

If this setting is YES, then SSO_UPSERT should always be set to a value of NO.

LDAP_UPSERT_DEFAULT_USER_ROLE If this setting contains a valid role, then this is the role a user is given when the LDAP upsert takes place. If this setting does not contain a value, then the role defined in the behavior setting named LIMITED_USER_ROLE is used instead.
LDAP_USER_LOOKUP When this behavior setting is set to YES, whenever a user performs an operation to lookup the details of another user, ExtraView will ask the LDAP server for the information. At the same time this is done, the information for the user within ExtraView, will be synchronized with the information within the LDAP record

Setting LDAP Fields in the Configuration.properties File

In the configuration file of the application server (Configuration.properties), there is a parameter named LDAP_FIELDS. These are the meta-names of the mappings to be used with LDAP. These must be comma separated, listed on one line. The following fields are mandatory and must be provided as the fields for the upsert operation:

LDAP_FIELDS = LDAP_PRIMARYKEY,
LDAP_SURNAME,
LDAP_GIVENNAME,
LDAP_COMMONNAME,
LDAP_EMAIL,
LDAP_STREET,
LDAP_CITY,
LDAP_STATE,
LDAP_POSTALCODE,
LDAP_COUNTRY,
LDAP_PHONE

Other fields may be added. They should follow the same naming convention. These represent the fields for which information will be retrieved. For example, you might add more fields such as:

  LDAP_MOBILE,
LDAP_PAGER,
LDAP_COMPANYNAME,
LDAP_DEPARTMENT,
LDAP_TITLE
LDAP_ADDITIONAL_EMAIL
LDAP_ADDRESS_LINE2
LDAP_PHONE
LDAP_HOME_PHONE
LDAP_COMPANYNAME
LDAP_FAX
LDAP_USER_DEFINED_1
LDAP_USER_DEFINED_2
LDAP_USER_DEFINED_3
LDAP_USER_DEFINED_4
LDAP_USER_DEFINED_5
LDAP_USER_DEFINED_6
LDAP_USER_DEFINED_7
LDAP_USER_DEFINED_8
LDAP_USER_DEFINED_9
LDAP_USER_DEFINED_10

Map the Fields in LDAP_FIELDS to Values in the LDAP Directory

These fields are mapped with a 1:1 relationship, similar to the following example:

LDAP_PRIMARYKEY = employeenumber
LDAP_LOGINID = uid
LDAP_SURNAME = sn
LDAP_GIVENNAME = givenname
LDAP_COMMONNAME = cn
LDAP_EMAIL = mail
LDAP_STREET = street
LDAP_CITY = l
LDAP_STATE = st
LDAP_POSTALCODE = postalcode
LDAP_COUNTRY = postaladdress
LDAP_PHONE = telephonenumber
LDAP_MOBILE = mobile
LDAP_PAGER = pager
LDAP_COMPANYNAME = displayname
LDAP_DEPARTMENT = department
LDAP_TITLE = title

Map the Fields in LDAP_FIELDS to Values in ExtraView

There can be more than one ExtraView field mapped to an LDAP_FIELD. You must prefix the name of the LDAP field meta-name with the characters EV_. For example, LDAP_PRIMARYKEY becomes EV_LDAP_PRIMARYKEY. You should separate multiple values with a comma.

EV_LDAP_PRIMARYKEY = USR_ID
EV_LDAP_SURNAME = USR_LNAME
EV_LDAP_GIVENNAME = USR_FNAME
EV_LDAP_COMMONNAME = USR_NAME
EV_LDAP_EMAIL = USR_EMAIL
EV_LDAP_STREET =  
EV_LDAP_CITY = USR_CITY
EV_LDAP_STATE = USR_STATE
EV_LDAP_POSTALCODE =  
EV_LDAP_COUNTRY =  
EV_LDAP_PHONE = USR_PHONE,USR_PHONE2
EV_LDAP_MOBILE = USR_MOBILE
EV_LDAP_PAGER =  
EV_LDAP_COMPANYNAME =  
EV_LDAP_DEPARTMENT = USR_DEPT
EV_LDAP_TITLE =  

List Fields to be Pre-populated

Ensure each of these is placed on ONE line:

Add Screen

This is a comma-separated list of ExtraView field names that are to be filled in on add screens, from values in the LDAP, and based on a search for a user. Example:

ADD_SCREEN_LDAP_FIELDS = USR_NAME, USR_TITLE, USR_DEPT, USR_EMAIL, USR_PHONE, USR_PHONE2, USR_MOBILE, USR_FAX, USR_CITY, USR_STATE, USR_BUILDING

Edit Screen

This is a comma-separated list of ExtraView field names that are to be filled in on edit screens, from values in the LDAP, and based on a search for a user. Example:

EDIT_SCREEN_LDAP_FIELDS = USR_NAME, USR_TITLE, USR_DEPT,USR_EMAIL, USR_PHONE,USR_PHONE2

Searching on the Add and Edit Screens

This is a comma-separated list of ExtraView field names whose values are to be used as the search key for filling the field values on the add or edit screens. Example:

LDAP_USER_FIELD_NAMES = USR_NAME, USR_TITLE

Specify if you want to Update ExtraView User Information with the Latest Information from the LDAP Server

If you specify YES, then when each user signs in to ExtraView, the code will upsert that user’s information to the ExtraView user table, directly from the LDAP directory.

LDAP_UPSERT = YES

If LDAP_UPSERT is NO, a user will not be able to sign on to ExtraView if they have not already been added to the system. The default value for this behavior is YES, so new users will be upserted and will be signed on.

Extending the Query Capability

When you have configured your LDAP connection to ExtraView, and you click on the search icon by a user field, a popup allows you to search the LDAP directory for users and to return one or more user’s details into the form on the screen. It is sometimes useful to configure the fields used for the query.

This is accomplished with the LDAP_SEARCH_FIELDS property within the Configuration.properties file. This is a comma-separated list of LDAP field names. The LDAP search may be filtered by these additional attributes.

For example, entering the following on a single line within the Configuration.properties file:

LDAP_SEARCH_FIELDS = SURNAME,
GIVENNAME,
PRIMARYKEY,
PHONE, COMPANYNAME

extends the search for users on user pop-ups to use the PHONE and the COMPANYNAME fields in addition to the standard fields.

User Name Lookup

There is an optional field within the Configuration.properties files named LDAP_EDIT_FIELDS_CHANGE_ON_REFRESH. When there is a parent user field mapped to an LDAP field and this is placed on an edit screen and this field is set to a value of NO, the child fields that are mapped are not altered when the parent field is changed. This allows the values of a record on the LDAP server to be placed on an edit screen and not be altered once they have been read from the LDAP server. The default value for this property is YES, allowing the child fields to be refreshed when the parent is altered.

When LDAP is configured for user lookup, and LDAP_LOGINID is configured to map to the same LDAP name as LDAP_PRIMARYKEY, the values returned for an LDAP search will contain the mapping: LDAP_PRIMARYKEY --> SECURITY_USER_ID and LDAP_LOGINID_KEY --> LOGIN_ID for the user. The primary effect of this is on user custom code that expects the LOGIN_ID to be the value returned for LDAP_LOGINID. Note that this is not the result.

User ID's

Some LDAP installations are configured to support User ID's that contain space characters. ExtraView does not support space characters within a User ID. It is considered bad practice to use User ID's that contain space characters. User ID's that contain space characters on the LDAP server cannot be mapped to User ID's in ExtraView.

Upsert of Users

If the Configuration.properties file contains the entry LDAP_UPSERT = YES, then you may specify which fields within ExtraView are updated with the upsert operation. The entry LDAP_UPSERT should be followed with an entry named UPSERT_LDAP_FIELDS. This will include all or a subset of the fields in the following list:

UPSERT_LDAP_FIELDS = LDAP_COMMONNAME, LDAP_GIVENNAME, LDAP_SURNAME, LDAP_EMAIL, LDAP_ADDITIONAL_EMAIL, LDAP_STREET, LDAP_ADDRESS_LINE2, LDAP_PHONE, LDAP_HOME_PHONE, LDAP_MOBILE, LDAP_PAGER, LDAP_COMPANYNAME, LDAP_POSTALCODE, LDAP_STATE, LDAP_CITY, LDAP_COUNTRY, LDAP_FAX, LDAP_USER_DEFINED_1, LDAP_USER_DEFINED_2, LDAP_USER_DEFINED_3, LDAP_USER_DEFINED_4, LDAP_USER_DEFINED_5, LDAP_TITLE

If the UPSERT_LDAP_FIELDS statement is not included then all the fields are assumed to be updated upon the upsert operation.

Timeouts

It is important that the connection from ExtraView to the LDAP server is extremely fast. A poor LDAP connection will introduce unacceptable performance problems into the environment. To guard against LDAP connections that do not return information in a timely manner, there are two timeouts:

TCP connection timeout. If there is general network slowness, there is a two-minute timeout period.

LDAP read timeout. This is set to one minute, and guards against a response not being received from the LDAP server. Note that Java 1.6 (or greater) is required for this timeout to work.

Pre-population of Fields from the LDAP Server

Assuming that you have set up the above configuration parameters, when you load the ExtraView add screen, the fields you selected for ADD_SCREEN_LDAP_FIELDS in Configuration.properties will pre-populate with values from the LDAP directory, according to the LDAP mappings configured in the Configuration.properties file.

In the example below, the circled fields are all pre-populated from the LDAP entry based on the current user (Campbell, Rob).

Example of fields pre-populated from an LDAP server

Popup Link Configuration

After you have decided which fields to put on your Add and Edit screen layouts, you can pick one (usually a primary identifier such as the user’s name) to have a URL link popup window beside it. This popup window will allow for dynamic searching of the LDAP directory. It will also populate multiple fields on the Add or Edit screen with the values for the primary identifier. ExtraView fields will be populated from the LDAP directory based on the mappings you set up in Configuration.properties.

First, configure the link with the appropriate URL, within the Data Dictionary. Full instructions for this are in the Data Dictionary section of this administration guide.

Data Dictionary entry where the popup link is configured

  • Set Display as URL to Yes.
  • Enter the first part of the URL, exactly as shown. Do not complete the field entry yet

    ?p_action=doDisplay&p_option=security.SearchLDAPDisplay
     

  • Append to the URL the list of fields you want populated in the following pattern, but using the fields for your installation:

    &FIELD=USR_NAME&FIELD=USR_TITLE&FIELD=USR_DEPT &FIELD=USR_EMAIL&FIELD=USR_PHONE &FIELD=USR_PHONE2&FIELD=USR_MOBILE &FIELD=USR_FAX&FIELD=USR_CITY&FIELD=USR_STATE &FIELD=USR_BUILDING

    where the pattern for each field is &FIELD=DataDictionaryName

    The final URL will look something like this:

    ?p_action=doDisplay&p_option=security.SearchLDAPDisplay &FIELD=USR_NAME&FIELD=USR_TITLE&FIELD=USR_DEPT &FIELD=USR_EMAIL&FIELD=USR_PHONE &FIELD=USR_PHONE2&FIELD=USR_MOBILE &FIELD=USR_FAX&FIELD=USR_CITY&FIELD=USR_STATE &FIELD=USR_BUILDING

Popup Link Usage

When you click on the popup link beside the primary identifier, ExtraView will open a new window, where you can search for users by typing in search criteria. This is shown in the following screen shot.

Searching for users in the LDAP directory

After using the search criteria, click on one of the results in the ID field. The fields on the parent add or edit screen will be populated with all the fields you requested.