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: Z and I Emulator for Web 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 of the incoming HTTP request object. The details 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: Z and I Emulator for Web provides three HCM plug-ins, two for DCAS and one for Vault. If you decide not to use either of these, you may create your own plug-in. For sample HCM plug-in code, refer to Sample HCM plug-in.

The primary function of the HCM plug-in is to take the user's network ID or user's certificate (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 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 HCM plug-in. In our DCAS/JDBC plug-in, we automate 3270 application logins by associating users' network IDs to their host IDs. Then, the host IDs and application IDs are used to obtain 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 a DCAS API that you can use to develop your own custom plug-ins. This API provides access to RACF-generated passtickets.

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

The DCAS API client contains the following members:

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

The DCAS API client contains the following methods:

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 (String hostAddress, int hostPort, String trustStoreName, String trustStorePassword, String trustStoreType)
  • hostAddress - DCAS server's IP address
  • hostPort - DCAS server's port number. If not specified, the default port number of 8990 will be used.
  • trustStoreName - The name of the truststore to be used by JSSE to connect to DCAS. It should include the full path name. Set to null if using default truststore .
  • trustStorePassword -The password of the above truststore. Set to null if using default truststore .
  • trustStoreType -- The type of the above truststore. Valid values are DCASClient.TRUSTSTORE_TYPE_PKCS12 (pkcs12), DCASClient.TRUSTSTORE_TYPE_JCEKS (jceks), and DCASClient.TRUSTSTORE_TYPE_JKS (jks). Set to null if using default truststore .
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 truststore name should include the full path name. The truststore must contain the DCAS client certificate and DCAS server certificate, unless the default truststore will be used. The truststore 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. Return 0 on success, non-zero otherwise.
public void setUseDefaultTrustStore(boolean def)
public void setNoFIPS(boolean nof)
Public int Init(String dcasAddr, int dcasPort, String keyringFileName, String keyringPassword)
  • dcasAddr - DCAS server's IP address
  • 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 p12 file name should include the full path name. It must contain the DCAS client certificate and the DCAS server certificate. If the default truststore is being used for these certificates, set p12FileName and p12Password to null. The p12 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. If a truststore of a type other than p12 is being used, use the Init(hostAddress, hostPort, trustStoreName, trustStorePassword, trustStoreType method instead.
Public void setWellKnownTrustedCAs(boolean wellKnownCAs)
public void setWellKnownTrustedCAsPassword(String password)
This method is used for setting the value specified by the above parameter.
Public void setServerAuthentication(boolean serverAuth)
Public void setTraceLevel(int level)
Public void setLogFile(string fileName)
Public CMResponse getPassticket(String 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 (0). The valid values for the status field are specified in Table 1. An SSL client authenticated connection is established with the DCAS server, and it is reused for all subsequent passticket requests.
Public CMResponse getPassticket(byte certificate[], String hostApplID, String hostAddr, long timeout)
  • certificate - User Certificate 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 (0). The valid values for the status field are specified in Table 1. 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.
Parent topic: Customizing Web Express Logon