LDAP Integration

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

# LDAP Binding Distinguished Name
# If the LDAP server allows anonymous connections (binding), then the bindDN
# line should be commented out.  Otherwise, binding to the LDAP server
# requires this correctly configured bindDn string to use in concert with the
# bind # password.  The bind password is specified elsewhere -- via
# "vovldap_setup setpassword".
# An LDAP "distinguished name" contains a list of key-value pairs similar to
# the template shown here.
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 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.

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

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".

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:
    -attributes "names"  -- List of attributes to constrain da/ua
                              search result.
    -orderandmap           -- Order and map result per configuration file.
    -q                     -- Quiet.
    -v                     -- Increase verbosity.

EXAMPLES:
    % vovldap_query ua jchen
    % vovldap_query ua jchen -orderandmap
    % vovldap_query ua jchen -attributes "cn mail"
    % vovldap_query um "l=New York"