Lightweight Directory Access Protocol (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.
If you are using LDAP authentication there is no need to set up local user accounts for LDAP users on BMC Atrium Discovery.
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.
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.
To configure the LDAP settings:
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:
Select Enabled or Disabled to enable or disable LDAP support for this appliance.
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)
The address of the LDAP server to connect to. For example:
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.
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.
Note that 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.
The user name with which to connect to the LDAP server. For example, firstname.lastname@example.org.
The password that corresponds to the user name entered in the Bind Username field. Check the box to modify the password.
The length of time that the appliance will wait before the login is assumed to have failed.
The location in the directory from which the LDAP search begins. For example: dc=tideway,dc=com. This restricts the search to the tideway 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.
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.
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.
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.
Note that 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.
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
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.
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.
- To save the LDAP settings, click Apply.
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:
- Edit the URI to point to the LDAP server's
ldap://URI. Do not click Apply button yet.
- Select Remove CA Certificate.
- 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
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 LDAP groups that they are members of, that is, in LDAP form dc=tideway,dc=com,ou=engineering....
To configure the LDAP group mapping settings:
- 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.
- Select Enabled or Disabled from the drop-down list to enable or disable LDAP group mapping.
For each LDAP group listed, an edit link and a delete link are provided.
- To remove the LDAP group mapping, click Delete.
- To edit the security groups mapped to an LDAP group, click Edit.
Add enables you to add a new group mapping. To do this:
- Click Add.
- 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.
Select the matching LDAP group from the list. The LDAP groups field is not case sensitive. If you use any upper case characters, their case is ignored. All LDAP groups returned from the LDAP server are displayed in lower case.
- Select the appliance security groups to which you want to assign the LDAP group.
- To save the mapping, click Apply.
If you receive a Can't Contact LDAP Server error in the Connection Status field, this may 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:
If you are using group mapping and are experiencing login failures, check that the groups have been correctly defined. The security log shows the list of groups that the user is assigned to, if the list is empty, no groups have been mapped and no login is possible.