Using the OpenText Directory Services RSSE driver
Using an RSSE driver, the iHub server can delegate user and identity management to the OpenText Directory Services (OTDS). The users, user groups, and associated organization dynamics maintained in OTDS are available through standard LDAP endpoints or at an application level through a REST API URL endpoint.
While the iHub default LDAP connection feature can already work with OTDS, the feature is limited to authenticating a user using their username and password directly. A single sign-on (SSO) solution usually involves other authentication schemes which generally employ session-based tokens and need advanced logic to resolve properly. An RSSE driver can implement the correct logic to handle these schemes depending on the deployment environment and workflow of the web application.
This OTDS RSSE driver is a base implementation of the RSSE API working against OTDS through its REST API endpoints. The driver is deployed as a J2EE web application using the Apache Axis 2 web service APIs. The HTTP-based REST API calls are made using Apache HTTP Client 4 libraries. The OTDS RSSE example already implements a method authenticating the user by name and password. Methods for token-based options need to implement the necessary logic to collect and validate tokens within the deployment environment.
An RSSE driver working against OTDS requires the following components:
*OTDS Server
*iHub Server
*Apache Ant
*Eclipse IDE, for any additional implementation
Configuring the OTDS RSSE driver
Table 13‑2 describes the parameters the OTDS RSSE driver uses for configuration. The location of these parameters is <OTDS RSSE home directory>/src
After applying new values, rebuild the OTDS RSSE package using Apache Ant.
Table 13‑2 Properties in
Example value
The URL of the base REST API endpoint for OTDS.
A general user in the OTDS system that can perform queries to lookup other objects in the system, such as a list of users or user groups. This user must have sufficient privileges to successfully complete the operations that the RSSE driver performs, dependent on the individual implementation.
The query user’s password.
The base location for all user home folders. Each user that RSSE finds will have a subfolder under this base. In the current implementation, the name of the subfolder is the username, which results in a home folder path of /home
/, for example.
You can add additional parameters to be read by the RSSE driver, dependent on the individual implementation.
About the OTDS RSSE driver classes
Table 13‑3 describes the classes the example RSSE driver uses.
Table 13‑3 Cluster node service properties
The main class, deployed as the Axis2 web service. Implements the complete RSSE interface.
Contains all operational code related to RSSE.
Axis2 generates these classes to process the RSSE API.
Handle low level operations such as message deserialization.
A utility class for handling the HTTP REST calls. Automatically reads and processes the OTDS cookies required to maintain a session with the OTDS REST API server.
For adding or modifying HTTP operations.
Axis2 generates these classes to process the RSSE API (wsdl)
These classes should not be modified. They implement the API's wsdl specifications.
Deploying the OTDS RSSE driver
The OTDS RSSE driver uses the Apache Axis 2 libraries and is implemented as an Axis 2 web service, so you can deploy the driver on any web application server on which Axis 2 is already deployed. The following procedure describes deploying the driver to the iHub-embedded Tomcat.
How to deploy the OTDS RSSE driver
1 Configure the OTDS RSSE driver as needed by modifying the property values in, as shown in Table 13‑2.
2 Open a command prompt, and navigate to the OTDS RSSE home directory. Execute ant. Apache Ant compiles the OTDS RSSE driver, creating
<OTDS RSSE home directory>\bin\OTDSRSSE.aar.
3 Create a new folder for the Apache Axis 2 web application, AC_SERVER_HOME\web\webapps\axis2. Obtain the Apache Axis 2 web application, axis2.war, and unzip it to this folder. Apache Axis2 is available at the following location:
4 Copy OTDSRSSE.aar to the Axis 2 folder \axis2\WEB-INF\services.
5 Deploy Axis 2 and the OTDS RSSE driver by restarting the Web service in System Console. Restart the Web service by performing the following tasks:
1 Log in to System Console. Choose Clusters. Left-click the arrrowhead icon next to the cluster containing the iHub installation to which you downloaded Apache Axis 2, and choose Edit, as shown in Figure 13‑9.
Figure 13‑9 Editing a cluster node
2 On Cluster Configuration, left-click Web, and choose Stop Service, as shown in Figure 13‑10.
Figure 13‑10 Stopping the Web service
3 Left-click the gear icon to display the Manage Cluster menu. Choose Refresh to update the status of the Web service, as shown in Figure 13‑11.
Figure 13‑11 Refreshing the status of the Web service
Wait until Web turns red to go to the next step. When Web is red, the Web service is stopped.
4 Left-click Web, and choose Start Service, as shown in Figure 13‑12.
Figure 13‑12 Starting the Web service
6 Open a new browser window. Verify that deployment was successful by going to http://localhost:8700/axis2/services/listServices. The OTDSRSSE service should be listed here.
7 In System Console, choose User Management from the side menu. In Select User Management, choose RSSE SOAP Service. Specify values for the following properties, as shown in Figure 13‑13:
*Search Cache Only
Select if the frequency at which BIRT iHub refreshes user information from OTDS is low.
*Server Name
Server that hosts the OTDS RSSE application.
*Port number
Application server port. Accept the default value of 8700.
*Context Path
Context path for the OTDS RSSE application.
*Cache Timeout
Number of minutes that an object remains in memory before BIRT iHub refreshes the object from OTDS. Accept the default value of 1440.
Figure 13‑13 Setting RSSE SOAP service properties
8 Restart iHub for these settings to take effect. Users will now be able to login using their OTDS credentials.