LDAP Integration

Monitor includes an interface to LDAP that can provide authentication services, extract user and display user attributes throughout the various pages in the web interface, and drive custom groups of users for reporting purposes.

Configure the LDAP Interface

To configure the interface to LDAP, first copy the configuration template, $VOVDIR/etc/config/ldap/ldap.cfg, to the licmon.swd/config directory. This configuration template is self-documented, with every possible configuration item explained:

Example Configuration: $VOVDIR/etc/config/ldap/ldap.cfg
# LDAP interface configuration file.
# Should be placed in the SWD/config directory.
# All settings are required unless specified otherwise.
# Unused optional settings should be commented out.

############
###SERVER###
############
#Server host that is running LDAP.
# Required.
set LDAP(host)				ldapsrv

# Port through which LDAP communication occurs.
# Optional, defaults to 389.
set LDAP(port)				389

# SSL.# Set to 1 if LDAP server requires SSL to connect.
# Set to 0 if SSL is not required.
set LDAP(ssl)                           0

# Search base. Required. The highest level of the LDAP data information tree
# (DIT) that contains the information sought by the RTDA application.
set LDAP(base)				dc=my,dc=company,dc=com

# Bind DN. Required if LDAP system does not allow for anonymous binding.
# Most LDAP implementations provide a public, unprivileged user for third-party
# application use if anonymous binding is not permitted.
# Comment-out if binding is not required.
set LDAP(bindDn)			cn=ldapmgr,ou=People,dc=my,dc=company,dc=com

###############
#### PEOPLE ###
############### 
#People search base. Optional, speeds up searches by narrowing them to LDAP
# entries that are for people based on their tree location. This is prepended to
# the LDAP base specified above. If all users are not located in the tree
# location, comment-out this setting.
set LDAP(peopleBase)			ou=People

# People object class. Optional, speeds up searches by narrowing them to LDAP
# entries that are for people based on their object class. This is added to the
# filter specification when searches are requested.
set LDAP(peopleSearchObjectClass)	account

# Relative distinguished name (RDN) used to search for users. Required.
# This should be set to the name of the LDAP attribute that contains the unique
# login name that is used by the operating system.
set LDAP(peopleSearchRdn)		uid

# Attributes that are returned from search and displayed on the user LDAP
# information page (reachable by clicking the LDAP folder icon in the web UI).
# Required.
set LDAP(peopleReturnAttrib)		{cn uid}

# Attribute ordering and mapping to human-readable headings for display in the
# user LDAP information page. Optional. If commented-out, attributes and values
# will be returned as they are named and ordered in LDAP.
set LDAP(map)                           { {cn AS Name} {uid AS "User ID"} }

# Attribute that contains the user e-mail address. Optional. Switches mailto
# links in the web UI to use the LDAP email address as opposed to using the user
# name. This setting is only used if this functionality is configured in the
# SWD/config/web.cfg file.
set LDAP(emailAttribute)                mail

################
#### GROUPS ####
################
# Group search base. Optional, speeds up searches by narrowing them to LDAP
# entries that are for groups based on their tree location. This is prepended to
# the LDAP base specified above. If all groups are not located in the tree
# location, comment-out this setting.
set LDAP(groupBase)                     ou=Groups

# Group object class. Optional, speeds up searches by narrowing them to LDAP
# entries that are for groups based on their object class. This is added to the
# filter specification when searches are requested.
set LDAP(groupSearchObjectClass)        groupOfNames

# Relative distinguished name (RDN) used to search for groups. Required. This
# should be set to the group attribute that contains the name of the group.
set LDAP(groupSearchRdn)                cn

# Attribute used to denote a user as a group member. Required. This should be
# set to the repeated group attribute that contains a member name.
set LDAP(groupMemberAttrib)             member

########################
##### CUSTOM GROUPS ####
######################## 
# Define LDAP attributes and/or groups to use for populating group memberships
# in the LM DB. These definitions are read by "vovldap_update_memberships",
# which is called once every week by the "live_lm_update_memberships_from_ldap"
# liveness script. These definitions establish a group membership starting at
# the time LDAP is is queried and ending 10 years later. The formats are:
# set LDAP(attribute,<customGroupType>) <ldapAttributeName>
# set LDAP(groups,<customGroupType>)    {<ldapGroupName1>, <ldapGroupName2>,...}
# set LDAP(attribute,location)    l
# set LDAP(attribute,department)  ou
# set LDAP(groups,divison)        {Engineering, Maintenance}

##################
#### FAILOVER ####
################## 
# Number of additional servers that should be contacted if the primary server
# is either down or does not contain the information being sought. Failover
# is used solely for authentication services.
# set LDAP(failoverServers) 1
# Copy and modify any of the primary settings above to match that of each
# failover server. Any primary setting that is not redefined below will be used
# in the failover configuration as well. For each primary setting that is
# overridden, use LDAP_FO_N(X) instead of LDAP(X), where N is the failover
# server number and X is the setting. Example, where the primary server is
# ldapsrv1, the failover servers would be:# set LDAP_FO_1(host)    ldapsrv2
# set LDAP_FO_2(host)    ldapsrv3
# EOF

Set the Bind Password

If anonymous binding is not allowed by the LDAP system, a bind account must be defined in the configuration and a password must be set. A utility is provided that is used to store the LDAP bind account password inside the Monitor server. This password will be used any time LDAP is interacted with. The utility is vovldap_setup and is called in this manner:
% vovproject enable licmon
% vovldap_setup setpassword secret
The utility can also be used to show the existing password as well as the overall configuration that has been established in the configuration file referred to above. The complete usage syntax for this utility is:

vovldap_setup: Usage Message
  
  A utility to manage certain LDAP integration configuration items.
  
  USAGE:
      % vovldap_setup [OPTIONS]
  
  OPTIONS:
      -h                         -- This help.
      -v                         -- Increase verbosity. Repeatable.
      setpassword       <passwd> -- Password for user to bind with
                                    primary server.
      setfopassword <#> <passwd> -- Password for user to bind with
                                    failover server(s).
      showconfig                 -- Show the current configuration.
      showpasswords              -- Show the current passwords.
  
  EXAMPLES:
      % vovldap_setup showconfig
      % vovldap_setup setpassword secret
      % vovldap_setup setfopassword 1 secret
  

Once the configuration file is in-place and the bind password is set (if applicable), the LDAP interface will be activated, enabling the LDAP folder icon links in the web interface. However, for the LDAP connection to work, the settings in the configuration file must be modified to match that of the LDAP system that is being connected to.

Authentication

Refer to Security for details on configuring LDAP authentication.

Display User Information

The presence of the LDAP configuration file mentioned above enables the LDAP icon to appear anywhere a user name is printed in the various report pages in the web UI. This icon, when clicked, will extract the attributes specified in the LDAP configuration file and display them in a pop-up window. The peopleReturnAttrib setting shown in the configuration example above specifies which attributes to return. The map setting allows for renaming the attributes into user-friendly names, as well as specifying the display order of the attributes.

Obtain E-mail Addresses

Some reports in Monitor contain a mail icon that allows for quickly e-mailing a user or group of users. By default, this icon represents a mailto link that is composed of the user name as reported to Monitor by the license server manager being monitored. This link can also be populated with the e-mail address populated in LDAP for the specified user by defining the e-mail attribute that is used by LDAP. Additionally, the following line must be set in the web interface configuration to enable the lookup to be performed in the web interface:
set VOVLM(ldapEmail) 1

Obtain Custom Group Definitions From LDAP

In addition to displaying user information found in LDAP, Monitor can also utilize LDAP attributes for defining custom group definitions. In the example above, the last configuration lines specify that:
  • The "l" LDAP attribute is to be used to map users into the custom group entitled "location".
  • The "ou" LDAP attribute is to be used to map users into the custom group entitled "department".
  • Members from the "Engineering" and "Maintenance" LDAP groups are populated into the custom group entitled "division".

Refer to the Project and Group Management section of this manual for details on how to extract and populate custom group definitions using LDAP.

Test LDAP

A utility, vovldap_query, has been provide that can be used to test the connection to LDAP, as well as lookup attributes at the command line. The utility's usage syntax is:

vovldap_query: Usage Message
  
  SYNOPSIS:
      Utility to perfom LDAP lookups.
      
  USAGE:
      % vovldap_query <ARGUMENTS> [OPTIONS]
  
  ARGUMENTS:
      da <dn>                -- Get attributes for specified DN.
      dn <user>              -- Get DN for specified user.
      gm <group>             -- Get members for specified group.
      ua <user>              -- Get attributes for specified user.
      ug <user>              -- Get groups for specified user.
      um <attribute=value>   -- Get users matching specified attribute
                                and value.
      
  OPTIONS:
      -v                     -- Increase verbosity
      -q                     -- Quiet
      -attributes "names"  -- List of attributes to constrain da/ua
                                search result.
      -orderandmap           -- Order and map result per configuration file.
  
  EXAMPLES:
      % vovldap_query ua jchen
      % vovldap_query ua jchen -orderandmap
      % vovldap_query ua jchen -attributes "cn mail"
      % vovldap_query um "l=New York"