Lightweight Directory Access Protocol (LDAP) is an Internet standard that provides access to information from different computer systems and applications. LDAP uses a set of protocols to access information directories and retrieve information. A directory is like a database, but contains information that is more descriptive and attribute-based. Information in a directory is generally read more often than it is written or modified. LDAP allows an application, running on a school's computer platform, to obtain information such as usernames and passwords.

Centralizing this type of information simplifies your job by providing a single point of administration. User information is provided in a single location, reducing the storage of duplicate information. This, in turn, reduces maintenance needs. LDAP authentication also enables users to have a single login and password to access a number of different applications.

More on creating custom authentication providers

Why use LDAPS (Secure LDAP)?

This method provides enhanced security over regular unencrypted LDAP, and may be required by some network administrators or by some LDAP server technologies, or when the LDAP server is at a remote site without private connection.

As a general recommendation, use LDAPS or be sure that the Learn application has a private non-routed connection to the LDAP server. In this case, the chance of someone intercepting the unencrypted LDAP traffic between the servers is very low, and encryption is not necessary.

LDAPS prerequisites

If the LDAP server is using SSL (LDAPS), you need a commercially signed certificate or authentication may fail. If the LDAP server uses self-signed certificates, import the certificate into the trusted keystore of the Blackboard Learn application server's JDK.

This enables the LDAP client-the Learn application-to establish the validity of the server certificate presented by the LDAP server when it initially attempts to establish the LDAPS connection. Otherwise, the SSL handshake fails, the LDAP bind does not happen, and authentication fails.

Example:

bb-config.properties has the bbconfig.java.home parameter set to /usr/local/jdk/jdk1.6.0_30, then the location of the JVM's truststore is /usr/local/jdk/jdk1.6.0_30/jre/lib/security/cacerts.

To import the CA-certificate into the truststore, use the Java keytool as follows:

$JAVA_HOME/jre/bin/keytool -import -v -trustcacerts -alias ldaps -file path-to-the-ca.crt -keystore $JAVA_HOME/jre/lib/security/cacerts

To learn more, see:

Java keytool documentation for Windows

Java keytool documentation for Unix

Tip: When prompted, use the default keystore password of changeit.

Configure an LDAP provider

  1. Provide your LDAP Server URL, for example, ldaps://directory.example.edu:636If the LDAP server is using SSL (LDAPS), you need a commercially signed certificate or authentication may fail. If the LDAP server uses self-signed certificates, import the certificate into the trusted keystore of the Blackboard Learn application server's JDK. We recommend encrypting using StartTLS.

  2. Provide the Base Search DN-the starting point in the LDAP directory structure for searching for a Learn user. A subtree search is performed from here, for example, dc=people,dc=example,dc=edu. You can create and configure two entirely separate LDAP providers with different Base Search DNs that point to the same physical LDAP server. You might do this if you want to reduce the load on the LDAP server by 'branding' to education.blackboard.com, then setting up the LDAP provider to search only dc=people,dc=education, dc=example,dc=edu instead of the whole tree.

    You can add multiple LDAP providers with the same Base Search DNs that point to different physical servers. If one LDAP server is unresponsive, the framework queries the next one. To learn more, see Provider Order.

  3. Provide the Search Attribute-the LDAP attribute containing the value that maps to the Learn Username or Batch Uid set in the Create Provider step. This property is domain specific. For Active Directory (AD), the property used is typically sAMAccountName, and for Novell, typically uid. For Active Directory, most clients integrating use sAMAccountName as the Search Attribute. This maps to the old style (pre-win2k) login name that has a maximum of 20 characters. Your AD Domain administrator is able to confirm if this is the correct attribute -OR- if you can or should use userPrincipalName.

    Some LDAP servers such as Active Directory require a privileged user to connect to the directory. The LDAP provider requires the Distinguished Name (DN) and password for the user. The two usual options for connecting using a privileged user include:

    • Create a new user within the directory. Assign this user the right of read access only. Use this user account as the privileged user.
    • Use an existing directory user as the privileged user.

    This account needs to access the LDAP server for each user that attempts to log in to Blackboard. As a best practice, select the User cannot change password and Password Never Expires options.

    This is what is referred to as a service account so the LDAP administrator may have a special location in the directory for these types of accounts.

    When first setting up the account, use a basic password, and only after you have confirmed the configuration is working, change the password to something stronger. Keep in mind that issues can occur with special characters such as # and @.

  4. Optionally, set the:
    1. Search Using Privileged User as Yes. The default is No. When searching for the FDN of the user to authenticate, the LDAP provider binds to the LDAP server as a privileged (specified) user.
    2. Provide the Privileged User DN. If the Search Using Privileged User is set to Yes, this must be set. For example: cn=BlackboardLDAP,ou=Special Users, dc= example,dc=edu or [email protected]
    3. Provide the Privileged User Password. If the Search Using Privileged User is set to Yes, this must be set. This represents the password of the user in Privileged User DN.
  5. Optionally, set the Advanced Settings.
    1. Connection Timeout needs a minimum of 15000 milliseconds. This represents the time in milliseconds to wait before canceling an LDAP request.
    2. Dereference Aliases as Always, Finding, or Searching. The default is Never. This property defines how aliases are dereferenced during search operations.
      • Never: Never dereference aliases.
      • Always: Always dereference aliases.
      • Finding: Dereference aliases only during name resolution-that is, while locating the target entry.
      • Searching: Dereference aliases once name resolution is completed-that is, after locating the target entry.
    3. Referrals as Follow or Throw. The default is Ignore. This property specifies how referrals should be handled by the provider.
      • Ignore: Ignore referrals if they appear in results.
      • Follow: Automatically follow any referrals.
      • Throw: Throw a Java ReferralException for each referral. This results in an error condition.
    4. Referral Limit as 5 is the default. This property specifies maximum number of referrals to follow. A setting of zero is an invalid value. You can set this property only if the Referrals property is set to Follow or Throw.

  6. Select Submit to save the configuration.

    Before making the new authentication provider Active, select Test Connection Settings from the menu to confirm that the configuration works as expected.