Creating plug-ins for Web Express Logon

The Web Express Logon feature of HATS enables you to accept network security credentials and use them to generate and use host credentials, freeing your users from the requirement to navigate host logon screens. Web Express Logon accomplishes this by the use of two types of plug-ins:

HATS supplies several Network Security plug-ins and Credential Mapper plug-ins. If the plug-ins that are supplied with HATS do not meet your needs, you can create your own plug-ins and integrate them into Web Express Logon. For example, if you need to access a different type of database where your credentials are stored, you can write your own plug-in.

Creating custom plug-ins for Web Express Logon

Web Express Logon relies on plug-ins to provide the network user ID and host access credentials. Web Express Logon interacts with these plug-ins through Java™ interfaces, which are described in the following sections.

Web Express Logon is implemented at the enterprise archive (.ear) file level for HATS Web projects and at the Web archive (.war) file level for HATS portlet projects. Your plug-in needs to be placed into each enterprise archive file or Web archive file accordingly. Follow these steps to create your own plug-in:

  1. Create a Java project in Rational® SDP to hold your plug-in. Ensure that these HATS files are in the class path of the Java project, in this order:
    1. hatscommon.jar
    2. hodwel.jar
    These files are located in the common plug-ins (cache) directory of the HATS Toolkit (common plug-ins directory/plugins/com.ibm.hats.core_x.x.x.yearxxxxxxxx/lib) where x.x.x is the version level and yearxxxxxxxx is the build level of HATS and in the root directory of the HATS enterprise archive file.
  2. Code your plug-in using the APIs described in this chapter.
  3. Create a Java Archive (.jar) file from your Java project. For HATS Web projects, export the .jar file to the file system in each .ear file in which you want to use it. For HATS portlet projects, export the .jar file to the Web Content/WEB-INF/lib directory of the HATS portlet projects in which you want to use it.
  4. Add the Java Archive to the MANIFEST.MF located in Web-Content/META-INF.
  5. Configure your connections to use Web Express Logon, and configure Web Express Logon to use your custom plug-in. Refer to HATS User's and Administrator's Guide for information about planning and configuring Web Express Logon.

Web Express Logon plug-in interface

All plug-ins must implement the following Java interfaces:

com.ibm.eNetwork.security.sso.cms.CMInterface

The CMInterface interface contains the following methods:

public int Init(Properties p, String id)
This method is used to initialize the plug-in. Any configuration parameters that are needed to initialize the plug-in are passed in with the properties object parameter. The parameters are configured in HATS Toolkit and stored in the Web Express Logon configuration file, hatswelcfg.xml. The id parameter is the symbolic name of the plug-in that is generated by HATS. This value is used to qualify the instance of the plug-in in the event multiple instances of the plug-in are running. The Network Security plug-in always get initialized with the default value of "" (empty string), because only one instance of this plug-in ever gets created. This method should return one of the SSOConstants values listed in Table 5.
public void Destroy()
This method is called when HATS is shutting down.
public CMResponse CMSGetUserCredentials(CMRequest req)
HATS calls this method when it has selected the plug-in to respond to a request. If the plug-in is a network security type, it is expected that the plug-in will return the user's network user id. If the plug-in is a host user credential type, then this method will need to return the user's host credentials. The CMResponse and CMRequest objects used by this method are described below.

The following methods are needed for plug-in identification and selection.

public String getName();
This method returns a string that identifies the plug-in.
public String getDescription();
This method returns a string that contains information that describes the purpose and function of the plug-in.
public String getAuthor();
This method is needed to identify the originating company or person of the plug-in.
public String[] getParameters();
This method returns a string array containing the names of parameters that can be used to configure this plug-in. These tokens are the keys that are specified in the parameters section of the Web Express Logon editor in HATS Toolkit. The symbolic name of the plug-in generated by HATS (id) is prepended to each parameter name when the parameters are passed into the Init() method. If no parameters are needed for configuration, the method might return null.
public Properties getParameterInfo(String strParm);
Given a parameter token, this method returns a properties object with the list of properties for the given parameter. Possible properties are as follows:

com.ibm.eNetwork.security.sso.CMRequest

HATS requests credentials by passing request information in this object. The following are its members and methods.

Members:

Methods:

public CMRequest()
public CMRequest(String id, String applID, String hostAddr, int authType, HttpServletRequest httpRequest)
public String getID()
public void setID(String id)
public String getHostApplID()
public void setHostApplID(String applID)
public String getHostDestination()
public void setHostDestination(String hostAddr)
public int getAuthType()
Possible values for authtype are:
 public static final int SSO_AUTHTYPE_ALL = 0xFFFF;
 public static final int SSO_AUTHTYPE_3270HOST = 0x0001;
 public static final int SSO_AUTHTYPE_5250HOST = 0x0002;
 public static final int SSO_AUTHTYPE_VTHOST   = 0x0004;
These values are defined in the com.ibm.eNetwork.security.sso.SSOConstants class. You must import this class if you want to use the values.
public void setAuthType(int authType)
Possible values for authtype are:
 public static final int SSO_AUTHTYPE_ALL = 0xFFFF;
 public static final int SSO_AUTHTYPE_3270HOST = 0x0001;
 public static final int SSO_AUTHTYPE_5250HOST = 0x0002;
 public static final int SSO_AUTHTYPE_VTHOST   = 0x0004;
These values are defined in the com.ibm.eNetwork.security.sso.SSOConstants class. You must import this class if you want to use the values.
public HttpServletRequest getHttpRequestObject()
public void setHttpRequestObject(HttpServletRequest httpRequest)

com.ibm.eNetwork.security.sso.CMResponse

Your plug-in bundles its response into this object and returns it to HATS. The following are its members and methods.

Members:

Methods:

public CMResponse()
public CMResponse(Object id, Object password, int status)
public int getStatus()
public void setStatus(int status)

The Credential Mapper plug-in uses the status element to provide the status of the return value. If the plug-in query fails for any reason, this field reports that failure to Web Express Logon. Failure codes are defined in the com.ibm.eNetwork.security.sso.SSOConstants class. Table 5 contains the status code numeric values, constant strings, and definitions.

Table 5. Status code definitions
Status code Constant value Description
0 SSO_CMR_SUCCESS Success
1 SSO_CMR_UNKNOWN_STATUS_CODE Unknown status code
2 SSO_CMR_CREDENTIAL_MAPPER _NOT_FOUND Credential Mapper not found
3 SSO_CMR_INVALID_WEB_ID Web ID not valid
4 SSO_CMR_INVALID_APPL_ID Application ID not valid
5 SSO_CMR_INVALID_SERVER_ADDR Server address not valid
6 SSO_CMR_DATABASE_CONNECTION_ ERROR Database connection error
7 SSO_CMR_USER_ID_NOT_FOUND_ IN_DB User ID not found in database
8 SSO_CMR_EXCEPTION Exception
9 SSO_CMR_INVALID_USER_IDU Invalid user ID not valid
10 SSO_CMR_PASSTICKET_ERROR Passticket error
11 SSO_CMR_TIMEOUT Timeout
12 SSO_CMR_UNEXPECTED_DCAS_RC Unexpected DCAS return code
13 SSO_CMR_API_NOT_SUPPORTED API not supported
14 SSO_CMR_BAD_URL Bad URL
15 SSO_CMR_UNABLE_TO_PARSE_ RESPONSE Unable to parse response
16 SSO_CMR_LOCAL_USERID_NOT_ AVAILABLE Local user ID not available
17 SSO_CMR_DUPLICATE_XML_TAGS Duplicate XML tags
18 SSO_CMR_CLIENT_EXCEPTION An exception occurred while processing the credential request
19 SSO_CMR_NO_NETWORK_SECURITY_ PLUGIN Network Security plug-in is not defined to Web Express Logon
public Object getID()
public String getIDasString()
public void setID(Object id)
Your CMSGetUserCredentials() method can use this method to return the network user ID from a Network Security plug-in or the host user ID from a Credential Mapper plug-in.
public Object getPassword()
public String getPasswordasString()
public void setPassword(Object password)

Writing a Network Security plug-in

HATS provides a Network Security plug-in for Tivoli® Access Manager and one for use with WebSphere® Portal. If you decide not to use these plug-ins, you can create your own.

The function of the Network Security plug-in is to acquire the user's network ID, which can be gleaned from the HTTP header that is found on the incoming HTTP request object. The details of how to acquire the network ID are specific to your network security application. Refer to your network security application's documentation for more information.

Writing a Credential Mapper plug-in

HATS provides several Credential Mapper plug-ins. If you decide not to use any of these, you can create your own plug-in.

The function of the Credential Mapper plug-in is to take the user's network ID (and perhaps the application ID) and obtain the appropriate host credentials. In Web Express Logon's implementation, users' network IDs are mapped to their host IDs during this process by way of a Java Database Connectivity (JDBC) accessible database. However, you might want to do this by another means, such as LDAP. For this reason, you might want to write your own Credential Mapper plug-in.

In the DCAS/JDBC plug-in, HATS automates z/OS® logins by associating a user's network IDs with their host IDs, and taking the host ID with the application ID and obtaining a RACF-generated passticket from the Digital Certificate Access Server (DCAS), a component of z/OS. This passticket is then used to sign the user on to the host. In your environment, you might not want to use the JDBC association aspect of the provided plug-in. For this reason, HATS provides a DCAS API. This API provides access to RACF-generated passtickets.

Sample Web Express Logon plug-in

See Appendix B. Sample Web Express Logon plug-in which contains a sample Web Express Logon plug-in and illustrates an approach to coding either a Network Security plug-in or a Credential Mapper plug-in.

Encrypting and decrypting plug-in parameter strings

Web Express Logon includes an object called com.ibm.eNetwork.security.sso.PasswordCipher to encrypt and decrypt plug-in parameter strings. It contains the following two methods:

public static String encrypt (String plainText)
This method returns an encrypted string that is passed as a parameter.
public static String decrypt (String cipherText)
This method reverses the encryption process by returning a decrypted string. If the cipherText was not encrypted using the encrypt method, it returns the original input string

The DCAS API object

The Digital Certificate Access Server (DCAS) API object (DCASClient) encapsulates the passticket requests. The following are its members and methods.

Members:

If you have previously written your own plug-in using the DCASClient object prior to HATS V7.0, you do not need to change your code for it to continue to work. However, new APIs are available starting with HATS V7.0 and should be used when developing new plug-ins. The preferred APIs are flagged below with a  Preferred  symbol.

Methods:

Public DCASClient()
This constructor should be used if you want to use the default trace level and log file name when the object is created.
Public DCASClient(int traceLevel, String logFile)
This constructor should be used if you want to specify a trace level and log file name when the object is created.
public int Init (String hostAddress, int hostPort, String trustStoreName, String trustStorePassword, String trustStoreType)
 Preferred 
Public int Init(String dcasAddr, int dcasPort, String keystoreFileName, String keystorePassword)
This method should be called after creating the DCASClient object. The parameters are stored in the object, and they do not change for the life of the object. The keystoreFileName should include the full path name. The keystore database must contain a DCAS client certificate and the DCAS server certificate. If WellKnownTrustedCAs.p12 or the default truststore is being used for these certificates, set keystoreFileName and keystorePassword to null. The keystore password should be encrypted using the encrypt password tool. It will be decrypted before being stored in the object. The valid return codes are described in the SSOConstants object.

If a keystore of a type other than p12 is being used, use the Init(hostAddress, hostPort, trustStoreName, trustStorePassword, trustStoreType method instead.

The keystore Password should be encrypted with the PasswordCipher.encrypt() method. If it is provided by an encrypted parameter (that is, a parameter with cmiEncrypted="true", it is provided to the plug-in in encrypted form. If it is not provided by an encrypted parameter, you can use this code to encrypt it:
import com.ibm.eNetwork.HOD.common.PasswordCipher;
keystorePW = PasswordCipher.encrypt(keystorePW);
The valid return codes are listed in Table 5.
public void setUseDefaultTrustStore(boolean def)
public void setNoFIPS(boolean nof)
Public void setWellKnownTrustedCAs(boolean wellKnownCAs)
Public void setServerAuthentication(boolean serverAuth)
Public CMResponse getPassticket(String hostUserID, String hostApplID, String hostAddr, long timeout)
This method should be called after creating and initializing the DCASClient object to obtain a passticket from the DCAS server. The passticket and the user ID are returned in a CMResponse object. The caller should check the status field of the CMResponse object to see whether the call was successful or not. If the call was successful, the status field will be set to SSO_CMR_SUCCESS. The valid values for the status field are listed in Table 5. An SSL client-authenticated connection is established with the DCAS, and it is reused for all subsequent passticket requests.
Public void Destroy()
This method closes the DCAS connection.