wiki:EchoSystem
Last modified 12 years ago Last modified on 07/11/12 15:04:44

​IAM / ​Projects / Shibboleth / Service Candidates / Echo360

EchoSystem Server LDAP Security Module Configuration

Summary

This how-to article describes the procedure for configuring an LDAP security module in the EchoSystem Server (ESS) for use with content or system authentication. Although security modules can be applied to different purposes, which this article will cover, their basic configuration is the same in most cases.

NB:

An LDAP server administrator should be present for the initial configuration of an LDAP security module in the ESS. Because LDAP is an application protocol and not a data management specification, the layout of one institution’s LDAP directory will substantially differ from that of another even though this information may be expressed in similar ways. This article cannot hope to cover all possible permutations of an LDAP deployment, so your server administrator should be on-hand to help answer questions about how to populate the configuration fields discussed in this document.

Creating a Security Module

There are actually two types of security modules. The first and most commonly used is the LDAP security module. The second module type was introduced in ESS 2.6 and is called “Seamless Only,” which provides a way for a suitably configured Blackboard Learn system to authenticate to the ESS for content access. This article only covers the LDAP security module type. Proceed through the following steps to configure an LDAP security module:

  1. Log in as an administrator and navigate to the Configuration -> Security page of the ESS.
  2. Click the green Add button.
  3. In the Name field, give the new module a recognizable identifier. Optionally, also give a description of its function.
  4. Select the “LDAP Security” module type.
  5. A security target must be selected when the module is created for the first time. This option determines what the security module protects. If set to Content, presentations instantiating the module will require users to log in against the LDAP criteria specified in the module before the presentation will be delivered. If set to Application, the system will use the LDAP directory to authenticate users accessing the ESS administration Web-UI.
  6. Populate the tree definition fields. These fields determine how the ESS should bind (connect) to the LDAP directory and what criteria will be considered for matching when a user provides credentials. Up to three trees can be searched, each of which may reside on the same or separate LDAP servers. The trees are joined with a logical “OR,” meaning that a set of credentials need only match one of the trees in order to be granted access.
    • LDAP URL: The complete URL by which the LDAP server is accessed, including schema and port, of the form ldap://fqdn:port.
    • Anonymous Login: Indicates whether the LDAP directory may be freely queried without first providing credentials.
    • Manager DN: When anonymous login is disabled, this indicates the distinguished name of a user who has permission to query all parts of the LDAP tree defined by parameters on this page.
    • Manager Password: The password for the account of the manager DN.
    • Base Group DN: Provide the distinguished name of a container holding any groups by which access will be limited. This field is mandatory and usually very broad -- often it is simply the root DC components of the directory DN, since groups can be scattered all throughout the tree.
    • Search Group Subtree: If enabled, the ESS will search containers descending from the Base Group DN recursively. Most users will enable this option.
    • Group Attribute Name/Value pair: If these optional fields are populated, a user that is found to match the offered credentials must also be contained within a group defined by the value field in the pair, where the attribute name is usually OU or CN. Most users will leave these fields blank.
    • Base User DN: Provide the distinguished name of a container beneath which any users to be granted access can be found.
    • Search User Subtree: If enabled, the ESS will search containers descending from the Base User DN recursively. Most users will enable this option.
    • Group Membership Attribute: Provide the global attribute that is used to define horizontal group relationships within the directory. In Microsoft Active Directory systems, this is the memberOfattribute.
    • User Name Attribute: Provide the global attribute that is used to define the login name associated with a particular user’s distinguished name. In Microsoft Active Directory systems, this is the sAMAccountName attribute. In OpenLDAP systems, this is the uid attribute.
    • Extra User Attribute Name/Value pair: Optionally, provide an attribute name/value pair that must test true in a user record that matches the offered credentials. This can be used to limit access to users possessing an arbitrary attribute of the administrator’s choosing. This pair of fields is the most versatile and is best used to select a specific subset of users from the larger set defined by the Base User DN.
  7. When finished configuring the tree definition fields, click the blue Save button at the bottom of the page to commit your changes.

The fields in the Test Security Configuration section above the tree definition fields can be used to simulate login attempts. If a username and password are entered in these fields, the ESS will perform a test authentication against the LDAP directory using the tree values currently visible on the page. In other words, one does not need to save the page’s contents before attempting a test with these fields.

Practical Usage

Even given the field definitions above, it can sometimes be hard to determine what their actual values should be in order to secure access to the right set of accounts. The constraints are usually simple: one might have a large pool of user accounts, but only want users belonging to a certain group to have access. When thought of this way, configuration needn't be very complex.

To start with, it is important to realize that when dealing with LDAP directories, there are two different ways that "groups," or collections of users can be identified. One way is to use containers, but this is limiting since users are unique objects -- and a user can only exist in one container at a time. The best we can do with containers is specify which container holds the pool of users we want to select from. These are simple, "vertical" relationships.

The other way is to use attributes. In Active Directory, for example, a user might have many "memberOf" attributes, each one having a value that matches the distinguished name of some group anywhere else in the tree. This is the most common way group membership is assigned. One user can therefore participate in many different groups, any of which could be useful for filtering against. These are one-to-many "horizontal" relationships and can even involve complex inheritance structures such as where one group is a member of another, larger, group of groups.

Most often, somewhere in the LDAP directory (or Active Directory) schema, there is a container within which most or all login accounts of a certain type are stored. These might represent the user names of all students, students of a specific class, or all faculty users, for example. Sometimes, these are the groups one might want to grant access -- anyone with a valid user account, perhaps. In this case, the container full of users is actually what we would call the Base User DN, and this distinguished name would be used to select that container in the ESS configuration.

In other cases, these broad categories aren't nearly refined enough to limit access to the right subset of accounts -- such as students in a certain course or program. You still need the same Base User DN as in the previous example to tell the ESS where all the candidate accounts are, but then you'd need an additional parameter to filter out the ones that shouldn't be allowed in. This is when you would use attributes. The easiest way in many common situations is to put the group membership attribute in the Extra User Attribute Name field (it might even match the group membership attribute exactly), and the DN of a group in theRequired Extra User Attribute Value field. Any user account that meets that membership requirement will be granted access; all others (even if they're in the same Base User DN) will be denied.

Of course, you can use up to three tree search definitions with AND or OR operators to combine filters so that multiple ranges of users -- or even a subset of users located only where multiple groups overlap -- are given access.

Deploying the Security Module

After a security module has been created, the ESS needs to be told where the module is to be considered “in force.” Content and application security modules are deployed differently because they affect different parts of the system.

To deploy a content security module, use the following steps:

  1. As an administrator, navigate to the Schedule -> Courses page of the ESS.
  2. Click on the name of a course containing a section that you wish to secure.
  3. Point to the section you wish to secure and click the edit button that appears.
  4. In the Security Settings section, select from the Security Module combo box the module that you wish to apply to the section.
  5. After selecting a security module, more fields will appear with names similar to those seen on the module configuration page. These are optional section-level overrides that allow you to be more specific with your LDAP queries based on the section an Echo belongs to. Their parameters are the same as at the module level.
  6. Save the section.

To deploy an application security module, use the following steps:

  1. As an administrator, navigate to the Configuration -> System Settings page of the ESS.
  2. In the Application Security section, select from the Security Module combo box the module that you wish to govern access to the ESS administration Web-UI.
  3. In the event that the ESS cannot reach the LDAP server for any reason to perform a query, the ESS is capable of falling back to credentials stored within its own database on the Configuration -> Userspage. To enable this fallback feature (which is always enabled for administrators), check the Enable Fallback to Internal ESS Database box. If fallback is disabled and the LDAP directory is unavailable, individuals with the presenter or scheduler role will not be able to log in.
  4. Save your changes.