Using LDAP and Active Directory User Authentication in BBj 15.0 and Higher

To view this topic for the preceding Enterprise Manager, click here.


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 usernames and passwords found in the multiserver.pwdfile (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.

Using LDAP / Active Directory For Authentication

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 image below shows a simple directory using OpenLDAP on the backend, and Apache Directory Studio to manage the server. OpenLDAP can be obtained free from and Apache Directory Studio from

Prepare the LDAP / Active Directory Server

1.    Ensure the LDAP or Active Directory server is running and configured properly to allow connections from the BBjServices server.

2.    Using your favorite LDAP administration tool, create an entry to contain the BBj user permission entries.  BASIS suggests creating an entry of type organizationalUnit named “bbjpermissions”.  The location of the entry within the directory does not matter.

3.    Create a user permission entry under the bbjpermission entry created in the previous step for user “admin”.  Entries can be any type, however, BASIS recommends an entry of type person where cn=username and sn=username.  This allows BBj to use the default settings to add and modify user permissions.

4.    For the description attribute in the user entry, set it to “ALLOW_ALL”.  This will be the initial permissions for the admin user so that this user can log into the Enterprise Manager after switching BBj to use LDAP / Active Directory user authentication.


Configure BBjServices Security Settings

After preparing the LDAP / Active Directory server for use with BBj, configure BBjServices to use LDAP authentication. Because LDAP is very flexible in the way administrators can construct a directory hierarchy, there is no “one size fits all” configuration. The Enterprise Manager provides a number of configuration options to allow BBj to work with virtually any LDAP or Active Directory configuration. The image below shows a BBj configuration that would work with the directory structure shown in the previous image.

1.    Specify the hostname or IP address of the LDAP or Active Directory server.

2.    Specify the port number of the LDAP or Active Directory server.  The default for LDAP is 389.  For Active Directory the default is 10389.

3.    Add one or more User Match Patterns.  User Match Patterns are used by BBj when it attempts to bind to the LDAP connection (authenticate).  When binding to a LDAP server, it uses a bind DN and a password.  During the authentication process, BBj will attempt to bind using each of the specified match patterns until it finds one that is successful.  The match pattern should be a complete DN where the location of the user ID is indicated with a %u as a placeholder.  For example:  cn=%u,dc=basis,dc=com or uid=%u,ou=users,dc=mycompany,dc=com  NOTE for Active Directory:  Most Active Directory configurations use a bind DN for users that consists of the domain/username instead of a typical LDAP DN.  For example, if the domain is “basis”, the user match pattern would be “basis\%u”.

4.    Optionally specify a Directory Access Bind DN and password.  This value is used in conjunction with the Directory Access Bind Password to bind to the LDAP connection.  When this value is specified, all operations on the directory will be done as this user.  If this option is left blank, directory operations will be performed as the user logging into BBj.  NOTE for Active Directory:  The typical bind DN for the Administrator account would look something like this, “mydomain\Administrator”.

5.    Optionally modify the Add and Modify Permissions LDIF Lines.  If following BASIS’ recommendations described in “Prepare the LDAP / Active Directory Server”, the defaults should be acceptable.  However, if the entries for user permissions have special characteristics based on specific configuration requirements, it may be necessary to modify these values.  Setting permissions on users requires either an add or modify operation to occur.  Using standard LDIF format lines (see for more information), administrators can specify those exact requirements here.  Figure 2 shows the default configuration with placeholders.  %u indicates the username, %base indicates the base DN as configured in the Permissions Search (see below), and %perms indicates the permissions string.

6.    Specify the Users Search Query.  BBj uses the Users Search Query to locate the user accounts to show on the Security > Users panel in the Enterprise Manager.  See the section below, “LDAP Search Queries” for more information on creating a query.

7.    Specify the Permissions Search Query.  BBj uses the Permissions Search Query to find the location of the BBj-specific user permissions within the directory.   See the section below, “LDAP Search Queries” for more information on creating a query.

8.    Finally, change the “Active Authentication Type” field at the top of the panel to “LDAP / Active Directory Authentication”.

9.    Save the changes using File > Save or the Save button.

10.  Logout and log back in to begin using LDAP authentication.  There is no need to restart BBjServices.


LDAP Search Queries

LDAP provides a mechanism called searches to make it possible for applications to search for and retrieve specific information within a directory. BBj uses these searches to locate the list of available users as well as get and set BBj-specific user permissions. BBj uses standard LDAP search syntax for searches as shown in the image below. There are two different searches BBj requires when configuring LDAP: users and permissions. It is vital that these searches be accurate in order for BBj to properly authorize users.

Building a Search Query

Using the edit button on either the Users or Permissions Search Query fields in the Enterprise Manager opens the Search Query Dialog (see Figure 3) and provides the following options:

Base DN

The name of the base entry relative to where the search will be performed.


Criteria to use in selecting entries within the scope.  LDAP has a robust language for expressing filters which is beyond the scope of this documentation.  Some examples of search filters are shown below in “Sample LDAP Search Filters”.  Consult outside LDAP documentation sources for complete details on building search filters.


The elements below the Base DN to be searched:

  • Base Only - Only examines the base DN

  • Immediate Subordinates - Only examines those entries immediately under the base DN but does not recurse into any subdirectories.

  • All Subordinates and Base - Examines all subordinates and the base as well as recursing into all subdirectories.

  • All Subordinates Only - Examines all subordinates as well as recursing into all subdirectories.

Dereference Policy

Whether and how to follow alias entries (entries that refer to other entries).  Typically most configurations will use None.

Size Limit

Maximum number of entries to return from a search.  Typically this will be left blank to ensure returning all available users and permissions.

Time Limit

Optional timeout for returning search results.

Test Button / Results

It is highly recommended to test queries before attempting to use them as the authentication settings.  The results area shows the raw results from executing the specified query.

Sample LDAP Search Filters

Return all entries under the base DN with an objectClass of any type: (objectClass=*)

Return all entries under the base DN with an objectClass of person: (objectClass=person)

Return all entries under the base DN with an objectClass of person OR organizationalRole, but not those found with a DN having an ou=bbjpermissions: (&(|(objectClass=person)(objectClass=organizationalRole))(!(ou:dn:=bbjpermissions)))

Emergency Return to Standard BBj Authentication

If in the course of configuring BBjServices to use LDAP authentication, misconfiguration occurs, locking you out of the system, it is very easy to recover:

1.    Open the file located in the cfg directory in your BASIS installation directory, in your favorite text editor.

2.    Locate the line for com.basis.auth.type and change it to the following:


3.    Save the changes.

4.    Restart BBjServices.

See Also

Lightweight Directory Access Protocol (LDAP)

Apache Directory and Directory Studio




Copyright BASIS International Ltd. BBj®, Visual PRO/5®, PRO/5®, and BBx® are registered trademarks.