Web Express Logon custom plugins

 

+
Search Tips   |   Advanced Search

 

Overview

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:

• The Network Security plug-in retrieves the user's credentials from a network security application.

• The Credential Mapper plug-in uses the credentials returned by the Network Security plug-in to retrieve the host user ID and acquires the host access credentials.

HATS supplies several Network Security plug-ins and Credential Mapper plug-ins. If the plug-ins 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 could write your own plug-in.

 

Create 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 via Java interfaces, which are described below.

Web Express Logon is implemented at the Enterprise Archive (.ear) file level. Your plug-in will need 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 plug-in:

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

   • hatscommon.jar

   • hodwel.jar

   These files are located in the lib directory of the HATS Studio toolkit...

   wstools\eclipse\plugins\com.ibm.hats\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 plug-in.

 

Web Express Logon plug-in interface

All plug-ins must implement the following Java interface:

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 needed to initialize the plug-in will be 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 plug-in 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. 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 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 may be used to configure this plug-in. These tokens are the keys specified in the parameters section of the Web Express Logon editor in HATS Studio. 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 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. This property is optional; if it is not specified, there is no default value for the parameter.

• cmiEncrypted: This property determines if 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 provided by Web Express Logon. See Encrypting and decrypting plug-in parameter strings for information about these methods.

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

com.ibm.eNetwork.security.sso.CMRequest

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

Members :

• ID (Host ID or Network ID)

• Host Application ID

• Host Destination Address

• Authentication Type

• HTTP Servlet request object

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 them.

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 them.

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 :

• Status Code

• ID (Host ID or Network ID)

• User Credentials (Password or Passticket)

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 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	Invalid user ID
4	SSO_CMR_INVALID_APPL_ID	Invalid application ID
5	SSO_CMR_INVALID_SERVER_ADDR	Invalid server address
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_ID	Invalid user ID
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 may be gleaned from the HTTP header from the incoming HTTP request object. The details of how to acquire the network ID are specific to your network security application.

 

Writing a Credential Mapper plug-in

HATS provides several Credential Mapper plug-ins. If you decide not to use any of these, you may 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 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 Credential Mapper plug-in.

In the DCAS/JDBC plug-in, HATS automates z/OS logins by associating a users' 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 may not want to use the JDBC association aspect of our plug-in. For this reason, HATS provides a DCAS API. This API provides access to RACF-generated passtickets.

 

Example Web Express Logon plug-in

Appendix A. Sample Web Express Logon plug-in contains an example Web Express Logon plug-in, which 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.com.eNetwork.HOD.common.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 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. Here are its members and methods:

Members :

• Port Number

• Keyring File Name

• Keyring Password

• Use WellKnownTrustedCAs

• Server Authentication

• Trace Level

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. 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.

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.

• keyringFileName - The name of the SSL keyring database file. It should include the full path name. While you are developing your plug-in, you will not know the full path that will be used when you deploy your HATS application. Here is an example of code that you can use to convert a provided filename parameter into a fully qualified filename, 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.

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 be encrypted with the PasswordCipher.encrypt() method described above. If it is provided by an encrypted parameter (that is, a parameter with cmiEncrypted="true", it will be 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;
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)

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 listed in Table 3. 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.

 

Home