Using LDAP and Active Directory User Authentication

In BBj 15.0 and higher, the LDAP been superseded by a new version. See LDAP and Active Directory User Authentication 15.0+.

Overview

Wikipedia defines the Lightweight Directory Access Protocol, or LDAP (pronounced /'εl dæp/) as

"an application protocol for querying and modifying directory services running over TCP/IP. A directory is a set of objects with attributes organized in a logical and hierarchical manner. A simple example is the telephone directory, which consists of a list of names (of either persons or organizations) organized alphabetically, with each name having an address and phone number associated with it."

Active Directory is a technology developed by Microsoft which provides a variety of network services, including user authentication and LDAP directory services. This documentation will assist the administrator in configuring BBj to use LDAP or Active Directory (which uses LDAP for its directory services) as a means of authenticating users of BBj. If unfamiliar with LDAP or Active Directory, please consult other documentation to gain a foundational understanding of these technologies before proceeding to configure BBj to use either one.

Why Use LDAP/Active Directory?

BBj ODBC and JDBC connections require user and password authentication before a connection can be established from a third party application. Further, BBj can optionally be configured to require user authentication before allowing access to the BBj interpreter and file system. By default, BBjServices manages this authentication by checking user names and passwords found in the multiserver.pwd file (part of the configuration files for BBj). While this method is secure and requires no additional configuration, it does require that the administrator manually add each user of BBj to the system. In a large enterprise, this could be a daunting task. Even worse, the company may already have an existing user management structure setup for employees which is managed by an LDAP or Active Directory server. Using the LDAP/Active Directory authentication option makes it possible to hook the BBj authentication mechanism into the existing system, eliminating the need to add users in a second location, or to try to remember to add them to the LDAP server for all other applications, and then add them to BBj as well.

How To Configure BBj

Before configuring BBj to use LDAP or Active Directory, first make sure an LDAP or Active Directory server is properly installed, configured, and running. The figure below shows settings that are applicable to the sample database installed with the Apache Directory Studio and Apache Directory Server. Both can be obtained free from https://directory.apache.org.

LDAP Server	Host name or IP address of the LDAP or Active Directory server.
LDAP Port	Port number on which the LDAP or Active Directory server is listening for connections.
LDAP Prepend Value	The prepend value will be prepended to the user name, and the append value will be appended to the end of the user name to build a complete, valid DN (Distinguished Name) which references a user object in the LDAP directory. For example, if the user account follows a pattern similar to uid=admin,ou=system where "admin" is the user name, the Prepend Value should be uid= while the Append Value would be ,ou=system
LDAP Append Value	See LDAP Prepend Value.
"Check Settings" button	Click this button after setting a server host, port, prepend value, and append value. It then gives the administrator the ability to enter a user name and password to validate. Use this to confirm that all of the settings are correct.
Users List Search Query	Select the search query that BBj will use to lookup the list of valid users for the system. NOTE: the administrator must create any queries that will be available; queries are specific to each particular LDAP server configuration.
Permissions Search Query	Select the search query that BBj will use to check user permissions for using The Enterprise Manager. NOTE: the administrator must create any queries that will be available; queries are specific to each particular LDAP server configuration.
"Edit LDAP Search Queries" button	Click this button to create or edit the search queries that will be available for selection in the "Users List Search Query" and "Permissions Search Query" drop down lists. See "Creating LDAP Search Queries" below for more information.

Creating LDAP Search Queries

LDAP search queries are used for two purposes in the BBj authentication system: specifying how to 1) find the list of available users and 2) lookup user permissions. While you can select only one query for each type, you can add any number of queries to the list of available queries.

Click the [Edit LDAP Search Queries] button to see the following dialog:

This dialog shows a list of all the available search queries. NOTE: there are no "default" queries; queries are specific to each LDAP/Active Directory server configuration and so they must be added by the administrator.

User List Queries

To create a query to look up the list of available users, the administrator should create a query that follows standard LDAP query syntax and returns a list of those objects that meet the criteria for a "user" object in the specific LDAP server configuration. For example, the following figure shows a query that returns a list of users from the sample directory installed with the Apache Directory Server:

Search Name	Name for the search query that will mean something in the specific context of the system.
Base DN	The base DN where the search will begin "looking."
Filter	Standard LDAP syntax filter string. In the example above, it specifies that it should return those objects who are of the "inetOrgPerson" type.
Scope	This settings specifies the depth that the search should look for matches.
De-reference Policy	The standard LDAP search de-reference policy to use for the query.
Size Limit	The maximum number of items that should be returned. Set to zero for unlimited.
Time Limit	The maximum number of seconds that the query can run before timing out. Set to zero for no limit.
"Test" button	Click this button to test the query. Basic results of the query will display in the text area below the button.

Permissions Search Queries

The BBj permissions are stored in the LDAP directory. In order for this to function properly, the administrator must create a single entry in their LDAP or Active Directory directory structure. This can be located anywhere that the administrator desires. The example below shows this entry in the Apache Directory Studio using the sample database:

The criteria for the permissions node is as follows:

The item must be named "bbjpermissions"
The item should have the following properties:

objectClass of "extensibleObject" (auxillary)
objectClass of "organizationalUnit" (structural)
objectClass of "top" (abstract)

The Permissions Query

The following figure shows an example of the query used to access the permissions item in the configuration from the above image. The query to locate the permissions query should look something like the following figure:

Other Important Information

The following list of items are a variety of points to keep in mind when using LDAP user authentication:

When LDAP authentication is configured, the LDAP server must be available or users cannot log into BBj. If a situation arises where the administrator needs to disable LDAP authentication and use the built in BBj authentication, and they cannot login to The Enterprise Manager, locate the "com.basis.auth.type" property in the BBj.properties file and change it to "bbj". You will need to restart BBjServices after making this change.

It is not possible to add/remove/edit users or change password from The Enterprise Manager when using alternate authentication methods such as LDAP or Windows authentication. This is designed behavior.