Connect to an LDAP Server

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

# 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

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 vovserver. This password will be used to connect to the LDAP server. 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
  

After LDAP integration and configuration is complete, you can configure Altair Accelerator products to attempt authentication using the LDAP server by adding this line to the project's policy configuration file, <project>.swd/policy.tcl.

set config(enableLdap) 1

After the line has been added, you must get the server to notice the change by by issuing the following commands at the command line:

% vovproject enable licmon
% vovproject reread

In addition to displaying user information found in LDAP, the Altair Accelerator products 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".

The vovldap_query utility has been provided 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"