Managing LDAP

LDAP is commonly used to access user or group information in a corporate directory. Using your corporate LDAP infrastructure to authenticate users can reduce the number of administrative tasks that you need to perform in BMC Atrium Discovery. LDAP groups can be mapped to BMC Atrium Discovery groups and hence assigned permissions on the system. The way in which BMC Atrium Discovery integrates with your LDAP infrastructure depends on the schema that is implemented in your organization.

LDAP Terms

The following terms are used in the sections describing BMC Atrium Discovery LDAP configuration:

• Directory Information Tree (DIT)— The overall tree structure of the data directory queried using the LDAP protocol. The structure is defined by the schema. Each entry in a directory is an object; one of two types:
  • Containers — A container is like a folder: it contains other containers or leaves.
  • Leaves — A leaf is an object at the end of a tree. Leaves cannot contain other objects.
• Domain Component (dc) — Each element of the Internet domain name of the company is given individually.
• Organizational Unit (ou) — Organizations in the company.
• Common Name (cn) — The name of a person.
• Distinguished Name (dn) — The complete name for a person, including the domain components, organisational unit, and common name.

An example Directory Information Tree is shown below.

dc=tideway,dc=com
      ou=engineering
            cn=Timothy Taylor
                  telephoneNumber=1234
                  email=t.taylor@bmc.com
      ou=test
            cn=Sam Smith
                  telephoneNumber=2345
                  email=s.smith@bmc.com
      ou=product management
            cn=John Smith
                  telephoneNumber=3456
                  email=j.smith@bmc.com

The login procedure

When a user attempts to log in through the user interface, BMC Atrium Discovery first checks to see whether the username represents a local account. If no local account exists, and LDAP has been configured correctly, BMC Atrium Discovery attempts to authenticate against the directory and then performs an account lookup to return the group memberships of that account. If the group mappings have been enabled, and configured correctly, then authentication takes place and the user is logged in with the local BMC Atrium Discovery rights as defined in the group mapping.

The Global Catalog

The Global Catalog is a distributed data repository that contains a searchable, partial representation of every object in every domain in a multidomain Active Directory Domain Services (AD DS) forest. The global catalog is stored on domain controllers that have been designated as global catalog servers and is distributed through multimaster replication. Searches that are directed to the global catalog are faster because they do not involve referrals to different domain controllers.

Configuring LDAP

To configure the LDAP settings:

1. From the Security section of the Administration tab, select LDAP.
   The LDAP page is displayed showing the LDAP tab.
   
   The options on this page are described below:

   Field Name	Details
   LDAP Support	Select Enabled or Disabled to enable or disable LDAP support for this appliance.
   Connection Status	Displays a message regarding the status of the connection to the LDAP server. For example: • No LDAP operations performed (last update: timestamp) • Invalid credentials (last update: timestamp) • Connection established (last update: timestamp) • Can't contact LDAP server (last update: timestamp)
   Server URI	The address of the LDAP server to connect to. For example: ldap://engineering.bmc.com:3268 or ldaps://engineering.bmc.com The default LDAP port is 389 and the default LDAPS port is 636. For multiple (failover) LDAP servers, enter a space separated list of LDAP server URIs. When using the Microsoft Active Directory group mode for LDAP, you can also use port 3268 to reference the Global Catalog. Check with your LDAP administrator to ensure that you use the correct port.
   LDAPS	Displays a message regarding the CA certificate and provides controls enabling you to upload, remove or replace a certificate. Many large enterprises have their own CAs that will provide a root CA certificate which will allow the appliance to trust the LDAP server's certificate it receives over the network. To upload a certificate, click the Browse button, select the new certificate using the file upload dialog, then click Apply. To replace an existing CA Certificate, select the Remove CA Certificate check box and click Apply. When the page is refreshed, add the new certificate as above. You should contact your organization's LDAP administrator to obtain a CA certificate. Multiple CA certificates can be uploaded by concatenating into a single file prior to upload. You cannot delete a CA certificate when LDAPS is enabled. Likewise, you cannot enable LDAPS without a CA Certificate loaded. In both these cases you will encounter a Cannot use LDAPS without a CA Certificate warning.
   Bind Username	The user name with which to connect to the LDAP server. For example, user01@bmc.com.
   Bind Password	The password that corresponds to the user name entered in the Bind Username field. Check the box to modify the password.
   Bind Timeout	The length of time that the appliance will wait before the login is assumed to have failed.
   Search Base	The location in the directory from which the LDAP search begins. For example: dc=bmc,dc=com. This restricts the search to the bmc container in the directory information tree. When you are not using group mapping (see #LDAP Group Mapping) any BMC Atrium Discovery group you enter, must be entered in lower case.
   Search Template	Specifies the template to use to search for the user name in the LDAP database. For example: (userPrincipalName=%(username)s) This queries the LDAP database for the userPrincipalName attribute which is equal to %(username)s, which is the user name string entered at the login prompt.
   Search Timeout	If no response is received from the server in this length of time, the query times out. Select a timeout value from the drop-down list.
   Search Scope	Defines how deep to search within the search base. "Base", or zero level, indicates a search of the base object only. "One level" indicates a search of objects immediately subordinate to the base object, but does not include the base object itself. This is typically used to search for objects immediately contained in the search base level. "Sub Tree" indicates a search of the base object and the entire subtree of which the base object distinguished name is the topmost object. Select the required scope from the drop-down list.
   User Cache Timeout	The appliance queries the LDAP server for user information and caches the results to avoid overloading the LDAP server. Select a timeout value from the drop-down list. Values less than 10 minutes are not recommended. You can also clear the cache manually using the Flush Cache button.
   Group Cache Timeout	The appliance queries the LDAP server for group information and caches the results to avoid overloading the LDAP server. Select a timeout value from the drop-down list. Values less than 1 hour are not recommended. You can also clear the user and group cache manually using the Flush Cache button.
   Group Mode	The group mode determines the way that the LDAP server is queried for group information, it should match the LDAP server used by your organization. Select one of the following LDAP server types from the drop-down list: •Microsoft Active Directory •SunONE Directory Server •Other
   Group Attribute on User node	The LDAP attribute name to search for when running a group query. The attribute is on the User node, and provides a list of distinguished names of groups that the user belongs to. For example, the attribute might be called "memberOf" and contain data such as "cn=sales,ou=groups,dc=bmc,dc=com". This field is user editable when the Other Group Mode is selected from the Group Mode drop-down (if the User node does not contain such an attribute, this field should be empty so the Membership Attribute on Group node will be used instead). When any other mode is selected the field is automatically populated.
   Group Query	The LDAP query that is used to find Group objects. It is usual to match the nodes' Object Class, for example: (objectclass=group). This field is user editable when the Other Group Mode is selected from the Group Mode drop-down. When any other mode is selected the field is automatically populated.
   Membership Attribute on Group node	The LDAP attribute name to search for to determine whether an individual is a member of a group. The attribute is on the Group nodes, and provides a list of names of users. For example, the attribute might be called "member". This field is user editable when the Other Group Mode is selected from the Group Mode drop-down. When any other mode is selected the field is automatically populated.

2. To save the LDAP settings, click Apply.

Configuring LDAP for use with BMC Atrium SSO

Depending on how your LDAP servers are configured, user authentication via Atrium SSO may work, but then user authorization in BMC Atrium Discovery fails. This occurs because Atrium SSO sends BMC Atrium Discovery the first part of the user's DN as their userid.

For example, for a DN of the following format:

dn: CN=ADDM QA. TEST,CN=Users,DC=addmsqa,DC=bmc,DC=com

The part that must be matched by the search that BMC Atrium Discovery runs is:

ADDM QA. TEST

To do this, for the example above, set the Search Base to:

cn=users,dc=addmsqa,dc=bmc,dc=com

and the Search Template to:

(cn=%(username)s)

Changing from LDAPS to LDAP

When you reconfigure BMC Atrium Discovery to use LDAP when it was previously configured to use LDAPS, you must remove the CA Certificate, and change the URI in a single step otherwise you will encounter a Cannot use LDAPS without a CA Certificate warning. To do this:

1. Edit the URI to point to the LDAP server's ldap:// URI. Do not click Apply button yet.
2. Select Remove CA Certificate.
3. Click Apply.

Changing from LDAP to LDAPS

When you reconfigure BMC Atrium Discovery to use LDAPS when it was previously configured to use LDAP, you must add a CA certificate before you attempt to enter an ldaps:// URI.

LDAP group mapping

The LDAP group mapping enables you to assign membership of BMC Atrium Discovery groups to LDAP groups. If you do not use group mapping, users will be only be assigned to groups in BMC Atrium Discovery which are exactly the same as the the LDAP groups that they are members of, that is, in LDAP form dc=tideway,dc=com,ou=engineering...

To enable or disable LDAP group mapping

1. From the LDAP page, select the Group Mapping tab.
   
   The LDAP Group Mapping page lists the LDAP groups that are assigned to BMC Atrium Discovery security groups. For each LDAP group, the appliance security groups to which it is assigned are listed. Links for each action that you can perform are provided for each group.
2. Select Enabled or Disabled from the drop-down list to enable or disable LDAP group mapping.

To add or edit LDAP Group Mapping starting from a username

1. From the LDAP page, select the Group Mapping tab.
2. Click Lookup User.
3. In the LDAP User Lookup dialog enter the Username and click the OK button.
4. The system looks up the username in LDAP and displays the results.
   
   LDAP Groups: For each LDAP group of which the user is a member, displays existing group mappings and provides an add link or an edit link.
   Mapped Groups: Displays the final list of mapped groups for this user.
   Details: Displays whether the information was obtained from the local cache and the total number of groups to which this user belongs.
5. Click Add to create a new group mapping or Edit to modify an existing group mapping.
6. Select the appliance security groups to which you want to assign the LDAP group.
7. To save the mapping, click Apply.

To add an LDAP Group Mapping starting from an LDAP group name

1. From the LDAP page, select the Group Mapping tab.
2. Click Add.
3. On the Add LDAP Group Mapping page, enter a search term for the common name into the LDAP Group field and click the Search button. A list of matches is displayed. If more than ten entries match, the first ten are shown and a label is displayed at the bottom of the list showing how many additional matches there are.
4. Select the matching LDAP group from the list. The LDAP groups field is not case sensitive. All LDAP groups returned from the LDAP server are displayed in lower case.
5. Select the appliance security groups to which you want to assign the LDAP group.
6. To save the mapping, click Apply.

To edit an LDAP Group Mapping starting from an LDAP group name

1. From the LDAP page, select the Group Mapping tab.
2. For each LDAP group listed, an edit link and a delete link are provided.
3. Click Edit.
4. Select the appliance security groups to which you want to assign the LDAP group.
5. To save the mapping, click Apply.

To delete an LDAP Group Mapping

1. From the LDAP page, select the Group Mapping tab.
2. For each LDAP group listed, an edit link and a delete link are provided.
3. To remove an LDAP group mapping, click Delete.

Troubleshooting

If you receive a "Can't Contact LDAP Server error" in the Connection Status field, this might be caused by certificate problems rather than simple connectivity (wrong URI, port and so forth). Check that the certificate you are using is the one you received from your LDAP administrator.

If the login fails when attempting LDAP authentication, set the security log /usr/tideway/log/tw_svc_security.log level to debug.

Where the account used to bind to the directory fails to authenticate look for messages similar to the following:

-1285350512: 2010-08-13 10:00:46,843: security.authenticator.ldap: DEBUG: Attempt to auth bind as username "administrator"
-1285350512: 2010-08-13 10:00:47,117: security.authenticator.ldap: DEBUG: LDAP passwd for "CN=Administrator,CN=Users,DC=generic,DC=com" not valid

If you are using group mapping and are experiencing login failures, check that group mappings have been correctly defined for one or more LDAP groups to which the user belongs. See To add or edit LDAP Group Mapping starting from a username.