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

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

Overview

BBj supports the use of various authentication mechanisms including

  • BBjServices (default)
  • LDAP / Active Directory
  • SAML (Security Assertion Markup Language)
  • Windows Native

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 third-party application can establish a connection. 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 set up for employees 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 www.openldap.org and Apache Directory Studio from directory.apache.org.



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

BBjServices supports enabling multiple authentication mechanisms. BASIS recommends this configuration because it provides a way to log in to the Enterprise Manager in the event that the LDAP or Active Directory server is inaccessible.

To add Active Directory authentication to the BBjServices authentication options:

  1. Sign in to the Enterprise Manager.
  2. Expand the Security node in the Enterprise Manager navigator.
  3. Double-click on the Setting node.
  4. Enable LDAP/Active Directory authentication by placing a check in the appropriate checkbox.

    5. Note:

    This is only used if permissions are stored on the directory rather than BBjServices. Use the search query builder dialog shown below to provide a search query to lookup available user permissions.

Once enabled, select the LDAP/Active Directory item and configure the appropriate settings:


LDAP/Active Directory Authentication Settings

Setting Description

SSL

Whether the server is using SSL.

Host

Hostname or IP address of the Active Directory server

Port

The port to connect to. The default for LDAP is 389. For Active Directory the default is 10389.

Timeout

Connection timeout in milliseconds.

User Match Patterns

For the user match pattern, this uses a string replacement format where the value %u will be replaced by the user name used to sign in. This match pattern is the value passed by BBjServices to the directory server in combination with the provided password using a bind request. This match pattern should be the distinguished name (DN) for the user object in the directory.

 

For LDAP, the pattern typically appears as something similar to:

uid=%u,cn=basis,cn=com

Active Directory Specifics

The most common user matching pattern when using Active Directory includes the domain and the username rather than a DN. It typically takes the form: DOMAIN\%u

 

For example, if your domain is BASIS, your user match pattern would typically be:

BASIS\%u

Note:

You may specify any number of potential user match patterns. BBj will attempt a bind operation using each match pattern until one is successful or the options have been exhausted.

Directory Access Bind DN

The bind DN used for basic directory access used when retrieving a list of available users. 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. 

Directory Access Bind Password

The bind password used in conjunction with the Directory Access Bind DN.

Add Permissions LDIF Lines

The LDIF lines used if you choose to have BBjServices store user permissions information on the directory. Typically, it is best to store permissions locally in BBjServices since those permissions are typically specific to the particular BBjServices installation.

If you choose to configure this option, you must provide a permissions search query as well. In addition, use the %u and %perms placeholders to specify where the username and permissions strings should be placed in the LDIF lines.

Modify Permissions LDIF Lines

This is the LDIF message used to modify permissions. See Add Permissions LDIF Lines for more information.

User Search Query

Use the search query builder dialog shown below to provide a search query to lookup available user accounts.

Permissions Search Query

Specify the Permissions Search Query.  BBj uses the Permissions Search Query to find the location of the BBj-specific user permissions within the directory. 

Note:

This is only used if permissions are stored on the directory rather than BBjServices. Use the search query builder dialog shown below to provide a search query to lookup available user permissions.

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

Use the search query editor dialog shown below to provide lookup queries for users and optionally permissions. The search filter format uses standard LDAP search syntax.


Option Description

Base DN

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

Filter

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.

Scope

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

 The maximum amount of time to retrieve results in seconds.

LDAP Search Filter Examples

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)))

Test Button

The Test button allows you to test your search query prior to committing the change. Upon clicking the Test button you will provide bind credentials as shown below:

The results of the query will appear in the large text area below the search configuration settings as shown above. The results are raw text returned showing the details of each matching object.

Configuring Permissions

Once you complete the configuration of the LDAP/Active Directory settings, before logging out, make sure to assign appropriate permissions to users. BASIS recommends using groups to make managing permissions easier. To configure permissions:

  1. Make sure to save the changes to the security settings page.
  2. Double-click on the Groups node in the Enterprise Manager navigator.
  3. Add a group for administrators.
  4. Select the new group.
  5. Set appropriate permissions for the group.
  6. Click the add button in the Group Members area.
  7. Select the users to add to this group.
  8. Make sure to save the changes.

You may also set individual user permissions using the Users node instead of Groups.

Active Directory Help

If you need help locating certain aspects of your Active Directory server’s configuration, these screenshots may prove helpful.

ASDI Edit

ASDI Edit is a simple tool that shows your Active Directory directory structure. To run ASDI Edit, use the Windows search feature to launch: asdiedit

Below is a screenshot of a default AD configuration. Note the path to the location of the user accounts in this example below would be CN=Users,DN=basis,DN=local. You could use this as the Base DN for a User Search Query discussed above:

sAMAccountName

sAMAccountName is an attribute on each user account object which is used by BBjServices as the user name to show in the list of users. As shown in the screenshot below, note the value of a user object’s sAMAccountName can be viewed by right-clicking on the user object and selecting Properties:

Object Class

Referencing the Object Class in the user search query is a common method for identifying user accounts. To view the various object classes present on an object, right-click on the object and select Properties:

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 BBj.properties 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:

    com.basis.auth.type=multiserver

  3. Save the changes.

  4. Restart BBjServices.

See Also

Lightweight Directory Access Protocol (LDAP)

Apache Directory and Directory Studio

OpenLDAP