SageVue LDAP configuration
This article provides some basic information on LDAP (Lightweight Directory Access Protocol) and how it can be configured within SageVue, Biamp's browser-based monitoring and management platform. Utilizing LDAP will allow SageVue users to login with the common credentials they use everyday to access email and other similar services within their organization.
What is LDAP?
LDAP is an open standard protocol that provides a common language for client applications to communicate with directory servers. It can be used for storing, searching, and retrieving data, authenticating and authorizing users, and more. It's the authentication of users that we are primarily concerned with when discussing LDAP and SageVue.
It’s a fairly mature protocol, initially created as a lightweight version of x500, which was a series of standards developed by the telecommunications industry in the late 80s covering directory services. The current version of LDAP, v3, was introduced back in 1997 and is still in use today.
Common terminology
When working with LDAP it is helpful to become familiar with a few terms and abbreviations.
Directory Server - Central location on a network for storing and managing information. A variety of information can be stored, such as user profiles and information about network resources like printers and computers. Microsoft's Active Directory is one common example.
Directory Information Tree (DIT) - Data in a directory server is stored in a tree hierarchy, with the root being the top most level and all entries organized in containers branching off from there.
Distinguished Name (DN) - A distinguished name is used to identify an entry and its location within the directory information tree. This is similar to the path in a file system in that it includes both the name of the entry and its path back to the root. However, where we are used to reading a file path from left to right, DNs are read from right to left. A distinguished name is made up of multiple components called relative distinguished names.
Relative Distinguished Name (RDN) - This is a name=value pair, a combination of which can make up an entry's distinguished name. This could be thought of as a branch, the total of which make up the path from the entry (leaf) back to the root.
Base Distinguished Name - This identifies at which point in the tree hierarchy an LDAP client will begin its search. This is a required field to be entered within SageVue and will be highlighted in the SageVue configuration section.
Organizational Unit (OU) - Provides a way to classify and group objects within a directory tree. Oftentimes OUs will be created to mirror an organization's business structure, organizing entries based on things such as location or departmental groupings.
Domain Component (DC) - Represents the top of an LDAP tree where DNS is used to define the namespace. When looking at a distinguished name, a domain component is commonly found as the right most portion of the name (closest to the root) and is mirrored off the organization. For example, biamp.com may be shown as dc=biamp,dc=com.
Common Name (CN) - Identifies the name of an entry. It is typically the left most portion of a distinguished name. When entering the base distinguished name in SageVue this should only be included when searching for a specific group. When searching for specific user, the BDN should point to an organizational unit and the LDAP Users window used to navigate further and assign roles.
Bind Operation - Used to authenticate the LDAP client to the directory server. SageVue supports a simple bind operation for its authentication method. A simple bind utilizes the distinguished name and password of a user for authorization. This can also be set to Anonymous, where no username or password is required.
Directory Information Tree
The below diagram provides an example of what the directory information tree may look like. Using a company named Example with a domain of example.com, we start at the top, closest to the root. From here branches extend, organizing resources and users within the directory.
What's in a name?
Continuing with the above example, let's take a closer look at what makes up the distinguished name of a user. We have two user accounts John Doe and Jane Doe. John Doe works at the main office and Jane Doe is a remote employee working from home. Each of their distinguished names will contain their full path back to the root of the tree.
cn=john doe,ou=main office,ou=user accounts,dc=example,dc=com
cn=jane doe,ou=remote,ou=user accounts,dc=example,dc=com
LDAP groups
LDAP groups can associate users from different locations in the directory for efficiency in assigning things such as security policies and distribution lists, or in the case of SageVue, a SageVue access role.
An organization may already have an AV Support group or would want to create one specifically for its SageVue admins. In this case roles can be assigned to all users in the group at once. We'll take a closer look at this in the SageVue configuration section below.
SageVue configuration
During installation, a local admin account will be created for accessing SageVue's web UI. These credentials are specific to SageVue. However, it is possible to enable an LDAP client which allows roles to be assigned and users to login using their organization's common username and password. This section assumes that SageVue has already been downloaded, installed, and a local admin account created. For more information on SageVue installation, please see the deployment guide here.
LDAP Configuration can be found in the Settings menu within the web UI.
- Enable LDAP - LDAP must first be enabled by setting this control to On
- Hostname - This should be the hostname or IP address of the directory server
- Port - LDAP uses port 389 for unencrypted connections, or port 636 for encrypted communication via SSL/TLS
- Base Distinguished Name - This indicates where SageVue will begin its search for users. The LDAP search only moves away from the root, so ensure that this field is set to a portion of the tree between the desired user(s) and the root.
- Use SSL - This should be set to on if using port 636 for encrypted communications.
- Authentication Method - This defaults to Anonymous. If credentials are required, use the dropdown to choose Simple and enter the appropriate User Name and Password. Note that the User Name requires @domain to be included. Using the distinguished name of a user is also supported.
- Clear LDAP Cache - This force clears SageVue's LDAP cache. SageVue will maintain a cache of already discovered directory entries, with a validity period of 15 minutes. The clear cache option can be used if new entries are added to the directory and need to be displayed within SageVue immediately. Otherwise they would not be discovered until the cache expires.
Users list and assigning roles
Once LDAP has been enabled and configured, navigate to the Users section of the menu. Here you have a choice to select either Local Users (which would include the admin account created during installation) or LDAP Users. Select LDAP Users to view the search results that were returned against the base distinguished name.
Below is a an example showing the results returned against the above configuration, using the BDN of dc=example,dc=com. This returns the four organizational units located just below the BDN as shown in the directory information tree.
From here you can manually navigate through the directory by clicking the folder icon associated with a particular organizational unit. Referencing the DIT example above, clicking on the User Accounts folder will reveal the Main Office and Remote OUs located there. Clicking the folder icon for the Remote OU will show the Jane Doe user.
Individual LDAP role assignment
After navigating to a user, roles can be assigned by first checking the box next to the intended user, followed by the edit user icon 
. Since this information is read from the directory server, all fields for an LDAP user are read-only except the actual role assignment. Once the appropriate role is selected from the dropdown, select Save to apply.
Once the role is assigned that user should now be able to login to SageVue with their common enterprise credentials. More information on SageVue roles can be found in the help file here.
Advanced user search
In addition to navigating through the directory's folder structure from the LDAP users list, SageVue also includes an advanced user search that can be used to search for specific names in the directory. It is best to use the first and last name of any users you are searching for. SageVue will return the first 20 matching entries that it finds. A role may then be assigned to this specific user from the User Role drop down menu.
Group LDAP role assignment
SageVue roles may also be assigned to all members of a specific LDAP group. LDAP groups are managed from the Assign Role to LDAP Groups pop up as shown below.
First select the 
button to launch the LDAP groups pop up. You can set the list to ascending or descending alphabetical order by clicking either the Groups, or Role column headers.
Check the box next to the group or groups you would like to assign the role to, then choose the role from the User Role dropdown menu. Select Save to apply. Now all members of that LDAP group will be able to user their common enterprise credentials to access SageVue.
Troubleshooting
LDAP server connection
If SageVue is not getting a response from the address entered in the Hostname field, the Users section will provide a warning message that "The LDAP server is unavailable"
If seeing this message you can check the following:
- Can you ping the LDAP server address from the machine running SageVue
- If not, verify the correct address is entered
- Try running a 3rd party LDAP browser from the machine running SageVue. Can it connect to the directory server using the same address?
- This can help determine whether the issue is specific to SageVue or the machine SageVue is running on.
- Some examples are
- LDAPSoft LDAP Browser
- Ldp (which comes with Microsoft Active Directory)
Finding a group or user
If having trouble finding the user(s) you would like to assign roles to:
- Check the Base Distinguished Name. This may be pointed to the wrong section of the DIT.
- Again, a 3rd party LDAP browser can be used to validate the distinguished name of a user
- Set the BDN to be more granular, pointed directly to the organizational unit that contains the intended user.
- Use the Advanced Search Tool and enter both first and last name
- Point the base distinguished name directly to the desired LDAP Group
- If an LDAP group is not found in the Assign Role to LDAP Groups window you can set the BDN to point directly to the group. In this case the group pop-up window will just show just that single group.
- For example: cn=support,ou=groups,dc=example, dc=com.
- Ensure to set the BDN back out towards the root so that users of a group found in this way can authenticate with SageVue
Issues logging into SageVue
If LDAP users have been assigned a role, but are unable to login using their credentials:
- Login may require @domain to be included in the user name.
- while Jane.Doe would fail, Jane.Doe@example.com would work
- Set the BDN to be broader
- It's possible to manipulate the base distinguished name within SageVue to help navigate the directory when assigning roles to users or groups. However, this will need to be set back closer to the root of the directory so that SageVue may authenticate all users at login
Update LDAP settings failed
If you receive a message that LDAP settings have failed, please log out and log back in with a local (non-LDAP) SageVue account. SageVue will not permit LDAP changes to be made by a user logged in with LDAP credentials.