Approach 2: Customize the existing CMS provided with Host On-Demand

A. 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 intialize the plug-in. Any configuration parameters needed to intialize the plug-in will be passed in with the properties object parameter. The parameters are specified in the servlet's web.xml file (point user to discussion of web.xml configuration). The id parameter is the symbolic name of the plug-in specified in the CMS configuration portion of the web.xml file. This value may be used to qualify the instance of the plug-in in the event multiple instances of the plug-in are running.


public void Destroy()

This method is called when CMS is shutting down.

public CMResponse CMSGetUserCredentials(CMRequest req)

This method is called by the CMS 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.

public String getName();

This method returns a string that identifes 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 parameter tokens that may be used to configure this plug-in. These tokens are the keys specified in the initialization (INIT) parameters section of the web.xml file used to define the CMS servlet. If no tokens are needed for configuration, the method may 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. The current list of possible properties are as follows:

• cmiDefaultValue: This property contains the default value for the specified parameter.
• cmiEncrypted: This property determines if the parameter must be encrypted (true or false).
• cmiRequired: This property identifies whether or not a parameter is required for initialization of the plug-in

The CMRequest interface contains the following members:

• ID (Host ID or Network ID)
• Host Application ID
• Host Destination Address
• Authentication Type
• HTTP Servlet request object
  

The CMRequest interface contains the following 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()

public void setAuthType(int authType)

public HttpServletRequest getHttpRequestObject()

public void setHttpRequestObject(HttpServletRequest httpRequest)

public String toString()

C. com.ibm.eNetwork.security.sso.CMResponse: The CMResponse interface encapulates all relevant information needed by the CMS for the request made of a plug-in. The following are its members and methods:

The CMResponse interface contains the following members:

• Status Code
• ID (Host ID or Network ID)
• User Credentials (Password or Passticket)

The CMResponse interface contains the following methods:

public CMResponse()

public CMResponse(Object id, Object password, int status)

public int getStatus()

public void setStatus(int status)

public Object getID()

public String getIDasString()

public void setID(Object id)

public Object getPassword()

public String getPasswordasString()

public void setPassword(Object password)

public String toString()

Writing your own plug-ins
The Network Security and HCM plug-ins are Java classes that implement the CMInterface interface. The CMS makes calls to your plug-ins via the APIs described earlier.

Network Security plug-in: Host On-Demand provides two Network Security plug-ins, one for Tivoli Access Manager and one for Netegrity Siteminder. If you decide not to use either of these, you may create your own plug-in.

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

HCM plug-in: Host On-Demand provides two Host Credential plug-ins, one for DCAS and one for Vault. If you decide not to use either of these, you may create your own plug-in.

The primary function of the Host Credential 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 JDBC-accessible database. However, you may wish to do this by another means, such as LDAP. For this reason, you may want to write your own Host Credential plug-in. In our DCAS/JDBC plug-in, we automate z/OS logins by associating a users' network IDs to their host IDs, and taking the host ID with the application ID and obtaining a RACF-generated passticket. This passticket is then used to sign the user on to the host. In your environment, you may not want to use the JDBC association aspect of our plug-in. For this reason, we have provided our DCAS API. This API provides access to RACF-generated passtickets.

The DCAS API object (DCASClient) encapsulates the Passticket requests:

The DCAS API client has the folllowing members:

• Port Number
• Keyring File Name
• Keyring Password
• Use WellKnownTrustedCAs
• Server Authentication
• Trace Level
• Trace Log File Name

The DCAS API client has the folllowing 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)

• traceLevel - Trace level (0=None, 1=Minimum, 2=Normal and 3=Maximum)
• logFile - Trace log file name. It should include the full path name.

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(int dcasPort, String keyringFileName, String keyringPassword)

• dcasPort - DCAS server's port number. If not specified, the default port number of 8990 will be used.
• keyringFileName - The name of the SSL keyring database file. It should include the full path name.
• keyringPassword - The password of the above keyring database.

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 DCAS client certificate. It should also contain the DCAS server certificate if it is self signed or from an unknown Certificate Authority. The keyring Password should have been 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.

Public void setWellKnownTrustedCAs(boolean wellKnownCAs)

Public void setServerAuthentication(boolean serverAuth)

Public CMResponse getPassticket(Sting hostUserID, String hostApplID, String hostAddr, long timeout)

• 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. It is specified in milliseconds.

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 if 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 specified in the SSOConstants object. An SSL client authenticated connection is established with the DCAS server, and it is reused for all subsequent passticket requests.

Public void Destroy()

This method closes the DCAS connection.