Developers often ask how they can use a single authentication source for multiple applications instead of managing and maintaining separate user directories for individual applications. This is where using Microsoft’s Active Directory or an application that utilizes a Lightweight Directory Access Protocol (LDAP) comes into play. Active Directory and LDAP enable a common location to manage user authentication instead of relying on each individual piece of software to maintain its own database of users.
BIRT iHub can utilize Active Directory or LDAP to externalize user authentication. Thanks to a utility created by my colleague Rob Murphy, BIRT iHub F-Type can now also connect to Active Directory or LDAP. In this post, I will walk you through obtaining the utility and using it to connect your iHub to an existing LDAP installation.
This tutorial assumes you have already installed BIRT iHub F-Type and have an existing LDAP installation already running.
The first step is to obtain the LDAP utility from the DevShare. (If you do not already have an account at developer.actuate.com, you will need to create one.) After you have downloaded the utility, copy it to a location accessible from the machine where BIRT iHub F-Type is installed. For this how-to, I copied the utility (ConfigureDirService.tgz in the list below) into the home directory of the user that runs iHub.
Now, extract the utility by using the tar command or something similar. This is the result:
After you have extracted the utility, take a look through README.txt for an overview of how to use the utility and for details on all of the utility’s valid options. The next step is to open the config.properties file with a text editor and add specific values for your environment. For a typical installation, you need to make changes to the Connection Settings and Mapping sections.
Of the various Connection Settings, you need to modify server, port, queryAccount, queryPassword, principalDNPrefix and principalDNSuffix. You may also need to modify other settings to align with your specific environment. For this example I use an installation of Apache Directory Studio for my LDAP, so I have also modified the value of isActiveDirectory to false since I will not connect to Active Directory.
The value of server needs to be changed to the hostname of the machine where your Active Directory or LDAP is installed, and the value of port needs to be changed to the port where the Active Directory or LDAP is listening.
The value for queryAccount needs to be to set to an account with permission to query the Active Directory or LDAP installation. For my example, I have used the admin account of the LDAP instance. The queryPassword for the queryAccount also needs to be set.
The final two settings you will need to modify are the principalDNPrefix and principalDNSuffix. Think of these as the values that will encapsulate the username when it is passed to your LDAP or Active Directory. My LDAP includes a user named Jesse whose Distinguished Name (DN) is uid=Jesse,ou=users,ou=system. Therefore, the DN prefix needs to be uid= and the suffix needs to be ,ou=users,ou=system to properly align with the LDAP.
Next, you will need to modify the Mapping section to include the values needed to map iHub to your Active Directory or LDAP. You will not need to provide a value for every field, and the fields you use may vary depending on your desired configuration. However, the majority of the fields need to be populated in order to properly map users and groups to your iHub. These are the LDAP mapping properties:
The value of userBaseDN should point to the structure where your users are housed. My userBaseDN is configured to ou=users,ou=system as the organizational unit (ou) users is located within the top level ou system in my LDAP structure.
The userLoginNameAttr needs to be set to the attribute used to specify the users. My users are specified as a uid, so I have configured this properly as uid for my mapping.
The userFullNameAttr should be mapped to the attribute that specifies a user’s full name. Within my environment, I have mapped this to the cn (common name) property.
The userDescriptionAttr should be mapped to the attribute used to specify a description of the user. This is not a required item, but it must be set if you wish to map the user description in iHub to a description set in your Active Directory or LDAP. In my environment, I do not use this setting.
The userObject needs to be set with the name of the object class that is used to define the users. Within my environment, I have defined the users using the inetOrgPerson class and thus I have specified inetorgperson for this value.
The emailAttr needs to be mapped to the attribute used to specify the email address for the user. Within my environment the email address is specified as a mail attribute so I have specified mail for this property.
The value of groupBaseDN, similar to userBaseDN, should be mapped to the structure where your user groups are housed. My groupBaseDN is configured to ou=roles,ou=system because the ou roles is located within the top level ou system in my LDAP structure (as seen below). The ou roles houses the various roles I want mapped to user groups within the iHub.
The value of groupDescAttr should be set to the attribute you have set to contain the groups description within your Active Directory or LDAP. I have configured my environment to use the cn property specified for each user group.
The value of groupObject needs to be set to the object class name used for the groups within your Active Directory or LDAP. Within my environment, I am using the object class groupOfUniqueNames for each of my user groups and thus have specified groupofuniquenames for this value.
The value of memberListAttr needs to be set to the attribute used to specify each member that is part of that group. Within my environment, each member is added to the group as a uniquemember attribute and thus I have specified this value as uniquemember.
The value of memberIDType needs to be set to match the ID type you are using to map each member. Within my environment, the members are specified using the full DN of the member and thus I have specified the value DN.
The value of homeFolderAttr needs to be specified to the attribute within your Active Directory or LDAP used to map the location of the users home folder within the iHub. Within my environment, I have used the attribute homePostalAddress to specify the users’ home folder path and thus have specified homePostalAddress for this attribute.
The value of homeFolderDefault needs to be specified with the path you want to be the root directory of where the users’ home folders are created. You need to set this value if there is not an attribute to specifically set the users’ home folder. Within my environment, I have configured this as /home to align with my existing home folder configuration as well as with the default location used in the iHub. For example, one of my users, alice, does not have a homePostalAddress specified; however, homePostalAddress is the value I have mapped for the users home folder. Since she does not have a home folder explicitly specified, a home folder will automatically be created for her at /home/alice.
Applying the Changes, Testing, and Undoing
Now that you have configured all of the needed values in your config.properties file, save the file and open a terminal window. Navigate to the directory where you extracted the LDAP utility and run the ConfigureDirService.sh script (ConfigureDirService.bat on Windows). The utility, which does not require any user input at this point, will report errors that occur and generate a message (shown below) to indicate when it has completed successfully. Please note that your iHub must be running for the utility to properly communicate with it and to make the required changes.
Once the LDAP utility has run successfully, log in to the Information Console using the Administrator account and navigate to the iHub Administrator interface. You should now see all of the Users and User Groups mapped to your Active Directory or LDAP within this interface. (The screenshot below shows the groups in the left column and the users in the main pane.)
After verifying that the users and user groups you created show up properly, log out of the Administrator account and attempt to log in using one of the user accounts in your Active Directory or LDAP. The folder structure below shows our new user in place.
You have now configured your BIRT iHub F-Type environment to use your existing Active Directory or LDAP to manage users and user groups.
If something goes wrong, or you need iHub to stop using your Active Directory or LDAP, you can run ConfigureDirService.sh (or ConfigureDirService.bat on Windows) script again with the -r true flag, as shown below.
Thank you for reading this post on configuring your BIRT iHub F-Type to use an external Active Directory or LDAP application to manage users and user groups. If you have any questions, post them in the comments below or in the Working with BIRT iHub forum.