Creating plugins 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 plugins:

HATS supplies several Network Security plugins and Credential Mapper plugins. If the plugins that are supplied with HATS do not meet your needs, you can create your own plugins 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 could write your own plugin.

Creating custom plugins for Web Express Logon

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

Web Express Logon is implemented at the enterprise archive (EAR) file level. Your plugin needs to be placed into each EAR file in which you want to use it, not in each HATS application's Web Archive (.war) file. Follow these steps to create your own plugin:

  1. Create a Java project in Rational Studio to hold your plugin. Ensure that these HATS files are in the classpath of the Java project, in this order:

    1. hatscommon.jar

    2. hodwel.jar
    These files are located in the lib directory of the HATS Studio toolkit (HATS_install_dir/eclipse/plugins/com.ibm.hats_6.0.0/lib) and in the root directory of each HATS enterprise archive (EAR) file.

  2. Code your plugin using the APIs described in this chapter.

  3. Create a Java Archive (.jar) file from your Java project. Export the .jar file to the file system in each EAR file in which you want to use it.

  4. Configure your connections to use Web Express Logon, and configure Web Express Logon to use your custom plugin. Refer to HATS User's and Administrator's Guide for information about planning and configuring Web Express Logon.

Web Express Logon plugin interface

All plugins 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 plugin. Any configuration parameters that are needed to initialize the plugin are passed in with the properties object parameter. The parameters are configured in HATS Studio and stored in the Web Express Logon configuration file, hatswelcfg.xml. The id parameter is the symbolic name of the plugin that is generated by HATS. This value is used to qualify the instance of the plugin in the event multiple instances of the plugin are running. This method should return one of the SSOConstants values listed in Table 3.

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 plugin to respond to a request. If the plugin is a network security type, it is expected that the plugin will return the user's network user id. If the plugin 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 plugin identification and selection.

public String getName();

This method returns a string that identifies the plugin.

public String getDescription();

This method returns a string that contains information that describes the purpose and function of the plugin.

public String getAuthor();

This method is needed to identify the originating company or person of the plugin.

public String[] getParameters();

This method returns a string array containing the names of parameters that can be used to configure this plugin. These tokens are the keys that are specified in the parameters section of the Web Express Logon editor in HATS Studio. The symbolic name of the plugin 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:

  • cmiDefaultValue. This property contains the default value for the specified parameter. This property is optional; if it is not specified, there is no default value for the parameter.

  • cmiEncrypted. This property determines whether the parameter must be encrypted. Valid values are the strings true and false. If this parameter is set to true, use the encryption and decryption methods that are provided by Web Express Logon. See Encrypting and decrypting plugin parameter strings for information about these methods.

  • cmiRequired. This property identifies whether or not a parameter is required for initialization of the plugin. Valid values are the strings true and false.

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_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_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 plugin 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 plugin uses the status element to provide the status of the return value. If the plugin 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 3 contains the status code numeric values, constant strings, and definitions.

Table 3. 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 plugin 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 plugin or the host user ID from a Credential Mapper plugin.

public Object getPassword()

public String getPasswordasString()

public void setPassword(Object password)

Writing a Network Security plugin

HATS provides a Network Security plugin for Tivoli Access Manager and one for use with WebSphere Portal. If you decide not to use these plugins, you can create your own.

The function of the Network Security plugin 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 plugin

HATS provides several Credential Mapper plugins. If you decide not to use any of these, you can create your own plugin.

The function of the Credential Mapper plugin 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 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 plugin.

In the DCAS/JDBC plugin, 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 plugin. For this reason, HATS provides a DCAS API. This API provides access to RACF-generated passtickets.

Example Web Express Logon plugin

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

Encrypting and decrypting plugin parameter strings

Web Express Logon includes an object called com.ibm.eNetwork.security.sso.PasswordCipher to encrypt and decrypt plugin 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 API object (DCASClient) encapsulates the passticket requests. The following are its members and methods.

Members:

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.

  • traceLevel - Trace level (0=None, 1=Minimum, 2=Normal, 3=Maximum)

  • logFile - Trace log file name. This parameter is not used in HATS. Traces are recorded in the HATS trace files. Web Express Logon traces are controlled with the runtime trace flag, trace.RUNTIME.

Public int Init(int dcasPort, String keyringFileName, String keyringPassword)

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 keyringFileName should include the full path name. The keyring database must contain a DCAS client certificate. It should also contain the DCAS server certificate if it is self signed or from an unknown Certificate Authority.

  • dcasPort - DCAS server's port number.

  • keyringFileName - The name of the SSL keyring database file. The name should include the full path name. While you are developing your plugin, you will not know the full path that will be used when you deploy your HATS application. Following is an example of code that you can use to convert a provided file name parameter into a fully qualified file name, relative to the EAR directory, at runtime: 
    import com.ibm.eNetwork.security.sso.cms.CredMapper;
import com.ibm.eNetwork.security.sso.cms.PluginResourceLocator;

    if ( (p12FileName != null) && 
                    (CredMapper.getPluginResourceLocator() != null))  
           p12FileName = 
                    CredMapper.getPluginResourceLocator().findResource(p12FileName);

  • keyringPassword - The password of the above keyring database.

The keyring 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 plugin 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;
keyringPW = PasswordCipher.encrypt(keyringPW);
The valid return codes are listed in Table 3.

Public void setWellKnownTrustedCAs(boolean wellKnownCAs)

Public void setServerAuthentication(boolean serverAuth)

Public CMResponse getPassticket(Sting 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 3. An SSL client-authenticated connection is established with the DCAS server, and it is reused for all subsequent passticket requests.

  • hostUserID - User ID for which the passticket is being requested.

  • hostApplID - Application ID for which the passticket is being requested.

  • hostAddr - The DCAS server's address.

  • timeout - The time available for the DCAS protocol to return a passticket, specified in milliseconds.

Public void Destroy()

This method closes the DCAS connection.