Jesse Freeman

Jesse is an evangelist for anything OpenText Analytics related.

How to Configure BIRT iHub F-Type to use Active Directory or LDAP

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. Connection Settings 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. Mapping Settings 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. -Jesse

Read More

Under the Hood – BIRT iHub F-Type: Understanding the Processes

While your customers don’t need to see the inner workings of your app, as a developer, you need to be the master of its parts and processes. It’s time to get under the hood. Hello BIRT community! My name is Jesse Freeman. Although I am not new to BIRT or Actuate, I am transitioning into a significantly more community-centric role. I have spent the last two years working as a Customer Support Engineer for Actuate, specializing in the server and designer products. I am excited to bring my product and support knowledge to the larger BIRT community. I come from a Java/JavaScript background and am a big fan of multi-platform, open source and open standard technologies. I am an advocate of Linux operating systems and have used or dabbled with the majority of the larger Linux distributions. In particular, I am a big fan of Arch Linux and CentOS. Over the next several weeks I will publish a series of blogs that will bring my support knowledge to the community. The series will include posts on understanding the BIRT iHub F-Type’s processes and configuration as well as troubleshooting. This series will provide technical insight for anybody who will be configuring and/or maintaining a BIRT iHub F-Type installation. BIRT iHub F-Type is a free BIRT server released by Actuate. It incorporates virtually all the functionality of commercially available BIRT iHub and is limited only by the capacity of output it can deliver on a daily basis, making it ideal for departmental and smaller scale applications. When BIRT iHub F-Type reaches its maximum output capacity, additional capacity is available as an in-app purchase. Understanding the Processes The first topic of my Under the Hood blog series is titled Understanding the Processes. When I first started in support, one of the first pieces of information I learned was the breakdown of all of the processes and their specific roles. This information was invaluable for the duration of my time providing support. Understanding the processes and their responsibilities provides insight into how the product works for configuration and integration purposes, and helps us understand where to look for more information if an issue arises. With that in mind, here is the list of the BIRT iHub F-Type processes and their responsibilities: ihubd – This is the daemon process responsible for the initial startup of BIRT iHub F-Type. The ihubd process starts the ihubc and ihubservletcontainer processes.  If issues occur during startup, this is one of the first processes to examine. ihubservletcontainer – As the name implies, this process is the front end servlet container for the BIRT iHub F-Type. This process is hosted out of an integrated Tomcat within BIRT iHub, which means anybody who is familiar with Tomcat should feel right at home when configuring or troubleshooting of the process. ihubc – This is the parent of all other processes started by BIRT iHub,  including the ihub, jsrvrihub and jfctsrvrihub processes.  The ihubc is the SOAP endpoint for BIRT iHub’s communication, the job dispatcher, and resource group manager, and also takes requests from front-end applications such as the integrated Information Console. ihub – The ihub process is responsible for communication with the metadata database as well as the Report Server Security Extension (RSSE) if one has been implemented. jsrvrihub – Within a single installation there may be multiple jsrvrihub processes running simultaneously. A typical out-of-the-box installation will have at least two. One of these two typical jsrvrihub processes is used for the viewing of dashboards and the other is used for execution and viewing of reports transiently. jfctsrvrihub – The jfcsrvrihub process is used for the execution of background jobs on BIRT iHub. This includes any report that is explicitly scheduled to run at a specific time (or immediately) and allows reports to be output to a directory within the ihub process rather than viewed immediately within the current browser session. Whether beginning an installation, working on an integration project, or troubleshooting an existing installation,  this information will assist you with knowing the process that needs to be examined. Thank you for reading.  Subscribe to this blog and you will be first to know when I publish my next Under the Hood – BIRT iHub F-Type series with a review of the Primary Configuration Files. Download BIRT iHub F-Type today so you can follow along. If you have any questions, post them in the comments below or in the BIRT iHub F-Type forum. -Jesse

Read More