IBM Rational Host On-Demand: Single Sign-On using web services

Configuring Rational Host On-Demand logon macro with web services

This article describes the step-by-step procedure to write a web service client, and then configure it with an IBM® Rational® Host On-Demand macro to fetch logon credentials from a web service and provide them to the display session. The same idea can be extended to get any data from a web service to populate your terminal screens automatically.

Suneel Kumar (suneel.kumar@in.ibm.com), Systems Software Engineer, IBM

Suneel KumarSuneel Kumar is working on Host Integration at the IBM India Software Lab in Bangalore. He is currently a Developer and Level 3 support specialist for the IBM Rational Host On-Demand product. He holds a Bachelor's Degree in Computer Science and Engineering. He is a Sun-certified Java programmer and Sun-certified web component developer. His areas of expertise include Java, J2EE, and network programming. His interests are web Services, Service Oriented Architecture (SOA) and web 2.0 technologies.



Mahesh Babladkar (mbabladk@in.ibm.com), Senior Staff Software Engineer, IBM

Mahesh BabladkarMahesh Babladkar is working on Host Integration at the IBM India Software Lab in Bangalore. He is currently the Chief Programmer for the IBM Rational Host On-Demand product. He holds a Master's Degree in Distributed Computing Systems. He is a Sun-certified web component developer and business component developer. He is an expert Java and J2EE developer. His areas of interests are web based technologies, J2EE, Service Oriented Architecture (SOA) and software patterns.



19 October 2010

Also available in Chinese Russian

Introduction

IBM® Rational® Host On-Demand is a terminal emulator application that can be used to connect to host applications running on IBM® i (5250), IBM® System z® (3270), and other UNIX® terminals. It provides cost-effective and secure browser- and non-browser-based host access to users in intranet and extranet based environments. It can be installed on a web server, thus simplifying administrative management and deployment. Also, its applet is downloaded to the client browser or workstation, providing user connectivity to critical host applications and data. This web-to-host Rational host connectivity solution helps provide security-rich web-browser access to host applications to the web, without any programming required.

Overview

Rational Host On-Demand's existing support for Single Sign-On (SSO) is limited to Portal Server and Credential Mapper Servlet using macros. Even though macros have many built-in capabilities to provide an immediately available integration solution to achieve SSO using web services, until now Rational Host On-Demand macros have not been explored to this extent. This article is aimed at helping Rational Host On-Demand administrators and users understand the flexibility of Rational Host On-Demand macros, and learn to program Rational Host On-Demand macros with their custom code to achieve SSO using web services.

This article focuses on:

  • How to write an SSO macro, which in turn will invoke a web service client.
  • Sample web service client code, which gets the credentials from a web service running on an application server.
  • Sample web service code that generates a User ID and Password.

Furthermore, you can use the same idea to develop more complex macros using web services to fill in the terminal screens automatically with the data extracted from a database or some other source.

Deployment architecture

Figure 1 shows the structure of Rational Host On-Demand and the SSO web service.

Figure 1. Architectural flow
screen captures show steps in process

Following are the steps in the process.

  1. The Rational Host On-Demand client (end user) downloads the HTML file, along with the Java™ Archive files (JAR files, including the additional JAR files required to run the web services client code).
  2. You open the display session by double-clicking the session icon in the page, and then start the macro (SSOwebService.mac)
  3. The macro, as part of the action element, invokes a method on the SSO web service client object to get the user name
  4. The SSO web service client further connects to the SSO web service deployed on the web service engine (Apache Axis2) and gets the user name.
  5. The macro, as part of the next action element, invokes a second method on the SSO web service client object to get the password.
  6. The SSO web services client connects to the SSO web service deployed on the web service engine and gets the password.
  7. The macro finishes invoking the web service methods and continues with the next actions.
  8. While still on the logon screen,the macro runtime fills in the user name and password fields, followed by the enter key as part of its input actions.
  9. The data is sent to the host and you automatically log in without manually typing the credentials on the logon screen.

Sign-on macro

The following code listings show a sample sign-on macro. In Listing 1, the web service client class is included in the macro by using the import tag, and WSClient is the name assigned to it.

Listing 1. Import the web service client (WSClient) class
<HAScript name="SSOwebService" description="Single Sign-On using web Service" 
timeout="60000" pausetime="300" promptall="true" blockinput="false" 
author="Suneel - Mahesh " creationdate="Aug 21, 2010 1:38:43 PM" 
supressclearevents="false" usevars="true" ignorepauseforenhancedtn="true" 
delayifnotenhancedtn="0" ignorepausetimeforenhancedtn="true">

    <import>
        <type class="com.ibm.developerWorks.HOD.HODCredentialServiceClient"
         name="WSClient"/>
    </import>

In Listing 2, webService is a variable that has the web service URL, and SSO is the variable that points to the web service client object.

Listing 2. Create variables and instantiate the class
    <vars>
      <create name="$webService$" type="string" 
      value="'http://localhost:8080/axis2/services/HODCredentialGenerator'" />
      <create name="$SSO$" type="WSClient" value="$new WSClient($webService$)$" />
    </vars>

In Listing 3, SSO.getUserID() and SSO.getPassword() gets the user name and password, respectively, from the web service, and then writes the values to the screen.

Part 3: Define actions and get Credentials
    <screen name="Screen1" entryscreen="true" exitscreen="true" transient="false">
        <description >
            <oia status="NOTINHIBITED" optional="false" invertmatch="false" />
        </description>
        <actions>
            <input value="$SSO.getUserID()$" row="6" col="53" movecursor="true" 
            xlatehostkeys="true" encrypted="false" />
            <input value="'[tab]'" row="0" col="0" movecursor="true" 
            xlatehostkeys="true" encrypted="false" />
            <input value="$SSO.getPassword()$" row="7" col="53" movecursor="true" 
            xlatehostkeys="true" encrypted="false" />
            <input value="'[enter]'" row="0" col="0" movecursor="true" 
            xlatehostkeys="true" encrypted="false" />
        </actions>
        <nextscreens timeout="0" >
        </nextscreens>
    </screen>
    </HAScript>

Web service client

HODCredentialServiceClient.java is a web service client that connects to the web service deployed on Apache Axis2 web services engine (in this case).

This uses the client stub (generated by Axis2 plug-in for Eclipse). The Rational Host On-Demand macro instantiates and invokes the methods to get the user name and password. Upon instantiation, the web service client gets the current user name, as shown in Listing 4. This will be used as the key to get the credentials from the web service.

Listing 4. The web service client code
/* Sample Program for IBM developerWorks
 * 
 * Author(s): Suneel, Mahesh
 */

package com.ibm.developerWorks.HOD;
import java.rmi.RemoteException;
import org.apache.axis2.AxisFault;

public class HODCredentialServiceClient {	
	String key;
	//client stub generated by Axis2 plugin for Eclipse
	HODCredentialGeneratorStub stub;  

	//takes the web service url from the macro
	public HODCredentialServiceClient(String webService){ 
 
		//get the current system user from java. 
		//We'll use this value as the key to get the credentials
		key = System.getProperty("user.name");		
		try {
			stub = new HODCredentialGeneratorStub(webService);
		} catch (AxisFault e) {
			e.printStackTrace();
		}
	}

	//method to get the userid from the web service
	public String getUserID(){  
		HODCredentialGeneratorStub.GetUserID userIDKey = 
			new HODCredentialGeneratorStub.GetUserID();
		HODCredentialGeneratorStub.GetUserIDResponse userIDResponse = null;
		//set the key to request the user id from the web service
		userIDKey.setKey(key); 
		try {
			userIDResponse = stub.getUserID(userIDKey);
		} catch (RemoteException e) {
			e.printStackTrace();
			}
		return userIDResponse.get_return();
	}

	//method to get the password from the web service
	public String getPassword(){ 
		HODCredentialGeneratorStub.GetPassword passwordKey = 
			new HODCredentialGeneratorStub.GetPassword();
		HODCredentialGeneratorStub.GetPasswordResponse passwordResponse = null;
		//set the key to request the password from the webservice
		passwordKey.setKey(key); 
		try {
			passwordResponse = stub.getPassword(passwordKey);
		} catch (RemoteException e) {
			e.printStackTrace();
			}
		return passwordResponse.get_return();		
	}
}

Credential web service

This is the web service running on a web service engine that provides the required credentials to the client program. The logic to implement this can be anything ranging from getting the credentials by a random generator or a flat file to reading from a database.

Because the logic to generate the credentials is outside scope of this article, this article provides a skeleton program that has the methods to be implemented to use with the client

This example HODCredentialGenerator.java, shown in Listing 5, accepts a key as an input and provides the required user name or password based on that key value. You can deploy this as a web Service using the Axis2 plug-in for eclipse.

The example shown here is simplified to illustrate how Rational Host On-Demand macros can be extended. For a Single Sign-On implementation, additional security is recommended. For example, HTTPS could be used to create a secure channel between the web service client and the web service, or the web service could be modified to encrypt the password, with corresponding decryption logic in the web service client.

Listing 5. Web service code
/* Sample Program for IBM developerWorks
 * 
 * Author(s): Suneel, Mahesh
 */
 
package com.ibm.developerWorks.HOD;

public class HODCredentialGenerator {
	public String getUserID(String key){
        // logic to get the user name based on the key goes here
		return "uname";
			}
	public String getPassword(String key){
		//logic to get the password based on the key goes here
		return "password";
	}
}

Integration with Rational Host On-Demand Client

Create a JAR file

Create a JAR file (hodwsclient.jar) with the web service client and the supporting stub class files, and sign it with a valid certificate.

Create a Deployment wizard file with an HTML parameter

  1. Open the Rational Host On-Demand Deployment wizard and create a new HTML page with the required host definition.
  2. In Session Properties > Start Options, configure the logon macro to auto start with the session. The previous macro is recorded for the session with the first screen as the logon screen.
  3. In the Additional Options panel, select Advanced Options > HTML parameters and add an HTML parameter as follows (shown in Figure 2):
    • Parameter Name: AdditionalArchives
    • Parameter Value:a list of JAR files separated by a comma and without the .jar extension
  4. The list of JAR files should include the JAR that contains the web service client class and all the supporting JAR files required for that. Supporting JAR files might include the JAR files required for the stub class.
  5. In case of the stub generated by the axis2 plug-in, the list of JAR files include:
    • hodwsclient
    • axiom-api-1.2.7
    • axiom-impl-1.2.7
    • axis2-1.4.1
    • backport-util-concurrent-3.1
    • commons-codec-1.3
    • commons-httpclient-3.1
    • commons-logging-1.1.1
    • neethi-2.0.4
    • woden-api-1.0M8
    • wsdl4j-1.6.2
    • XmlSchema-1.4.2
    Figure 2. The Add HTML parameters panel in the Rational Host On-Demand Deployment wizard
    HTML Parameter Panel
  6. Continue with the creation of the HTML page.

Access the page

  1. Open the HTML file created in the previous steps in a Java-enabled web browser and access the Rational Host On-Demand session configured with the Sign-On macro.
  2. This will automatically populate the logon screen with the credentials provided by the web service, as shown in Figure 3.
    Figure 3. SSO logon screen
    Logon Screen

What you have learned

You now know how to write a web service client, and then configure it with a Rational Host On-Demand macro to fetch logon credentials from a web service and provide them to the display session on your terminal.

Furthermore, you can use the same idea to develop more complex macros using web services to fill in the terminal screens automatically with the data extracted from a database or some other source.


Downloads

DescriptionNameSize
Class files and jarBinaries.zip137KB
Java and macro source filesSource.zip137KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=551015
ArticleTitle=IBM Rational Host On-Demand: Single Sign-On using web services
publish-date=10192010