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 that are returned by the Network Security plug-in
to retrieve the host user ID and acquire the host access credentials.
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:
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:
hatscommon.jar
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.
Code your plug-in using the APIs described in this chapter.
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.
Add the Java Archive
to the MANIFEST.MF located in Web-Content/META-INF.
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:
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, you must use the encryption and decryption
methods that are 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 requests 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_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:
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 5 contains the status code numeric
values, constant strings, and definitions.
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:
Port Number
Keystore File Name
Keystore Password
Use WellKnownTrustedCAs
Server Authentication
Trace Level
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.
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 (String hostAddress, int hostPort,
String trustStoreName, String trustStorePassword, String trustStoreType)
Preferred
hostAddress - The DCAS server IP
address.
hostPort - The DCAS server port number.
If not specified, the default port number 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. The name is set to null if you are using the default
truststore or WellKnownTrustedCAs.p12.
trustStorePassword - The password
of the specified truststore. The password is set to null if you are
using the default truststore or WellKnownTrustedCAs.p12.
trustStoreType - The type of the
specified truststore. Valid values are:
DCASClient.TRUSTSTORE_TYPE_PKCS12 (pkcs12)
DCASClient.TRUSTSTORE_TYPE_JCEKS (jceks)
DCASClient.TRUSTSTORE_TYPE_JKS (jks)
The truststore type is set to null if you are using the default
truststore or WellKnownTrustedCAs.p12.
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 or WellKnownTrustedCAs.p12 will be used.
The truststore 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. Return
0 on success, nonzero otherwise. See SSOConstants for return codes.
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.
dcasAddr - The DCAS
server's IP address
dcasPort - The DCAS's port
number. If not specified, the default port number
of 8990 will be used.
keystoreFileName -
The name of the SSL keystore database file.
The name 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. 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:
keystorePassword -
The password of the above keystore database.
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:
Public void setWellKnownTrustedCAs(boolean
wellKnownCAs)
Public void setServerAuthentication(boolean
serverAuth)
Public CMResponse getPassticket(StringhostUserID, 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.
hostUserID - User ID for which the
passticket is being requested.
hostApplID - Application ID for which
the passticket is being requested.
hostAddr - The DCAS's address.
timeout - The time available for
the DCAS protocol to return a passticket, specified in milliseconds.