Security and Web Express Logon

HATS offers security for your applications. Using Secure Sockets Layer (SSL), HATS provides a secure connection between your application and the TN server it connects to.

Web Express Logon (WEL) gives you a mechanism to authenticate users (that execute HATS applications) and provides them with single signon capability.

Enabling SSL security

SSL Security between the end user and the HATS application requires an HTTPS connection to the HATS application. This requires that both HTTP server and WebSphere Application Server be configured to support HTTPS. The HTTP server certificate is stored in the browser certificate store for the browser-HTTP server connection. The SSL configuration of HATS is between the HATS application and the TN Server (which must be configured with an SSL port).

If you click the SSL enabled check box in the Security tab of the connection file, you request that data flowing over the connection to be encrypted to secure the connection.

HATS uses Host On-Demand to provide connection support from HATS applications to 3270 and 5250 applications using Telnet protocols. HATS uses the SSL support provided by Host On-Demand for securing these connections. Using a secure connection over SSL encrypts data flowing over the connection and thus protects it against observation by a third party.

For a connection to be secured, both the HATS application and the TN server it is connected to must support SSL. To secure the connection, the TN server must provide a certificate, which is used in encrypting the data.

After HATS receives the certificate from the server, it goes through an SSL handshaking function to determine whether to accept or reject the connection. It then searches its keyring file for a signer certificate that matches the TN Server certificate. The HATS keyring file contains a set of "WellKnown" certificates including Verisign, Thawte, and RSA. If the TN Server is using a valid WellKnown certificate, it will be accepted because it will match one of the WellKnown certificates that are provided with HATS. In this case, there is no need to import a certificate into HATS for the connection - the needed signer certificate is already in the HATS keyring file. If the TN server is using a non-WellKnown certificate (for example: a self-signed certificate), a valid signer certificate must be imported into HATS. This certificate can be obtained by opening the TN server keyring file with iKeyman and extracting the certificate as a binary .der file. The .der file can then be imported into HATS.

If a certificate is required by HATS, you can click Import in the Security tab of the connection file editor to import the required certificate from the TN server. When the certificate is imported, HATS builds a database called CustomizedCAs.class. The CustomizedCAs.class file is contained in the CustomizedCAs.jar. The database contains the certificate that you import. The certificate becomes a part of the HATS project, and it is packaged with the rest of the project files when you assemble the project.

When a HATS application that enables SSL security is deployed, the application War Classloader Policy setting in WebSphere Application Server must be set to "Application" (the default setting is "Module").

For more information on WebSphere Application Server security, go to http://www.ibm.com/software/webservers/appserv/was/library/. For information on IBM HTTP Server security, go to http://www.ibm.com/software/webservers/httpservers/library.html.

Multiple SSL CA certificates in a single EAR file

If you want to have multiple SSL connections in a single EAR file, and the connections require you to import different CA certificates, use the following procedure to ensure connectivity for all connections:

1. On the Security tab of the Connection editor, enable SSL and import the certificate for each connection that requires a certificate. This enables the HATS host terminal to use SSL and the imported certificates.

2. To ensure that each SSL connection works at runtime:

   • Open a command prompt from the com.ibm.hats directory. The directory is located at HATS Studio installation directory\wstools\eclipse\plugins\com.ibm.hats.

   • Run the gencert utility once for each certificate file (.der) needed for the EAR. For example,

      gencert certificate1.der  

     gencert certificate2.der

     gencert certificate3.der

     If the gencert utility prompts you for a password, just press the Enter key. Do NOT type a password.

     The gencert utility adds each certificate to a file named CustomizedCAs.jar in the com.ibm.hats directory.

3. Using the Navigator tab of HATS Studio, copy the newly created CustomizedCAs.jar file to the Web Content\WEB-INF\lib directory of each project that needs any of the certificates, replacing the CustomizedCAs.jar file created during step 1.

Using Web Express Logon (WEL)

Web Express Logon or WEL is the specific ability of an end-user to access host systems and host applications without the requirement of providing additional security credentials. It provides a means for a HATS application to accept user credential information previously authenticated by a network security layer, and use it to generate and use host credentials to be used by the HATS application instead of requiring a HATS end user to navigate logon screens.

WEL works in conjunction with your company's network security application to maintain company security while allowing users to log on to host systems without having to re-enter their user IDs and passwords. It has several benefits, including the following:

• Ease of use: Users can log on to their network security application and access host applications without having to re-enter their IDs and passwords.

• Reduced password-related support calls: Users are less likely to call the company support line because of forgotten or misplaced passwords.

• Increased productivity: Users can log on only once in an environment that has multiple methodologies for defining user IDs, passwords, and authentications.

A variant called Certificate Express Logon is also supported which allows authentication by way of X.509 certificates rather than by network security applications.

If you click the Use Web Express Logon check box on the Security tab of the Connection editor and then click the Configure Web Express Logon button, the Web Express Logon editor is opened. This editor has the following three tabs:

• Network Security Plugin

• Credential Mapper Plugins

• Source

Macro-based automation style of Web Express Logon allows you to use a network security application such as (IBM Tivoli Access Manager). You can also use a certificate-based authentication to configure WEL or you can create your own plug-in to work in your environment. For more information, refer to the HATS Programmer's Guide. Macro-based automation relies on the following four key components and the interactions that take place among them:

• Credential Mapper (CM)

• HATS macro (usually the connect macro)

• Network Security Plugin

• Credential Mapper Plugins (CMP)

The CM is supplied with HATS. At a high level, the CM has two primary roles: (1) request the client's credentials (called a network ID) and (2) respond with the host access credentials, which consist of the host ID and a password or passticket, depending on the type of CMP. In order to carry out the request and response process, the CM calls upon the Network Security plug-in to acquire the user's network ID from the network security application. Then the CM calls upon the CMP to acquire the user's host access credentials.

The login macro is recorded while you are in an active session (meaning you have your terminal open and your host session is connected). It initiates at the time the user attempts to access the host session, either automatically or manually (depending on your configuration). In broad terms, it automates the end-to-end process of the client sending the HTTPS request to the CM, the CM responding with the needed credentials, and the macro inserting the user's credentials in the proper fields to allow authenticated logon.

Note:

WEL must be configured by clicking the Use Web Express Logon check box on the Security tab of the Connection editor before the WEL macro can be created.

The CMP is a back-end repository that maps users' network IDs to their host IDs. This repository can be a JDBC database such as IBM DB2. The Digital Certificate Access Server (DCAS) and Vault plugins provided with Web Express Logon are designed to work with such a database. Another possibility for a repository is an LDAP directory. However, using LDAP as your CMP requires you to write your own plug-in. For more information, refer to the HATS Programmer's Guide.

Planning for implementation

There are certain things you need to consider while you are planning your setup and configuration to use WEL in your HATS project. The following is a list of what information you'll need to obtain:

• What is your host type?

• What network security layer your users will enter through?

• What host applications will your users access using WEL?

• What host authentication is needed for those applications?

• Where the host authentication credentials will be stored and how to access them?

• Whether built-in Credential Mapper plugins are sufficient to do the job, or whether a custom plugin needs to be written.

Implementation

Once you have obtained the information to begin setting up WEL, you will need to do the following:

• Configure your network security application, if you are using one.

• Configure connections in your HATS project for WEL.

• Configure WEL by:

  • Identifying the network security plugin to be used, and specifying any initialization parameters.

  • Identifying the Credential Mapper plugins to be used in the EAR project, the criteria for selecting each one, and the initialization parameters for each one. Order them optimally based on their selection criteria.

• Create and populate any back-end credential sources (such as DCAS).

• Configure any required keyring database files needed to connect to back-end credential sources like DCAS. A Certificate Management tool is provided, see Create SSL key database (DCAS only) for more information.

• Record macros that include prompts for user ID and password to trigger WEL processing.

• Trigger these macros at appropriate times in the HATS project (connection's logon macro being one example).

How to create a WEL logon macro

Perform the following steps to create a WEL logon macro:

1. From HATS Project View, select the project connection from the Connection folder

2. From the HATS toolbar, start a Terminal session.

3. Click on the Record Macro icon

4. Navigate to the screen that contains the user ID input field.

5. Select Add Prompt Action icon from the toolbar, and the Add Prompt Action wizard appears. Fill in the fields. For more information, see ***.

6. Select Use Web Express Logon in the Add Prompt Action dialog. Select the prompt type of User ID and enter the Application ID in the Application ID field.

7. Navigate to the Password input field.

8. Select Add Prompt Action icon, select Use Web Express Logon with Prompt type of Password and enter it in the Application ID.

9. When you have completed the login process, click the Stop Macro icon and the Save Macro.

After the macro has been recorded and saved, you need to configure Hats to invoke the macro. There are three methods which you can use:

• Define the WEL logon macro as the connect macro for the connection. Perform the following steps to configure WEL as the connect macro:

  1. Select the connection from the HATS Project View

  2. Open the Macros tab

  3. Select the WEL macro using the Connect macro drop-down list.

• Invoke the WEL logon macro with a Play Macro option on a screen customization. For more information, see Play macro.

• Create an Integration Object from the macro.

Network Security Plugin

The following Network Security plugins can be selected for WEL. You can only have one security plugin per .ear file. Select from the drop-down list beside Plugin type to display the following list:

• None (used when no network security package is being used, as in Certificate Express Logon)

• Custom (refer to the HATS Programmer's Guide)

• Access Manager Network Security

• WebSphere Portal Network Security Plugin
  Note:

  The WebSphere Portal Network Security Plugin will only appear in the if you are working with a HATS portlet project.

Credential Mapper Plugins

The following built-in Credential Mapper plugins are configured for WEL. Click the Add button then select Add built-in Credential Mapper plugin to choose from the following list:

• DCAS/RACF/JDBC Credential Mapper

• Certificate-based DCAS/RACF Credential Mapper

• JDBC Vault Credential Mapper

• WebSphere Portal Credential Vault Credential mapper
  Note:

  This item will only appear in the Add built-in Credential Mapper plugin dialog for a Portlet project.

• Test Credential Mapper

You also have the choice of adding a custom Credential Mapper by selecting Add custom Credential Mapper plugin and entering the name of the fully qualified plugin in the text box. For information on creating a custom plugin, refer to the HATS Programmer's Guide

Once you have selected your Credential Mapper plugin, the details of such as class, name, description and author, will be filled in the Details section. The Initialization section will display a set of parameters configured for the plugin you selected. By clicking the Add button, you can specify additional parameters for your plugin. You can also select Remove to remove selected parameters. Only parameters which are not required can be removed.

Initialization parameters

DCAS parameters for DCAS/RACF/JDBC Credential Mapper plugin

For solutions that use z/OS and DCAS, add the DCAS plugin parameters. Adding these parameters allows the CMP to map the user's network ID to his host ID and then get a passticket from the DCAS application running on the host. A passticket is a credential that is similar to a password, however a passticket expires after a certain amount of time and is used only one time. DCAS requires a Security Access Facility (SAF)-compliant server product, such as an IBM Resource Access Control Facility (RACF) security server, that supports passticket generation.

Required DCAS parameters: The following two Host Credential plugin parameters allow the client to connect to the DCAS server securely:

CMPI_DCAS_KEYRING_FILE

This parameter specifies a keyring database. A keyring must be specified to provide access to the DCAS client certificate as well as the DCAS server's certificate. The certificates establish a client authenticated secure connection with the DCAS server. This parameter is a file reference to the keyring to be used. The DCAS plugin is the DCAS client. The keyring file must be stored in the .ear.

CMPI_DCAS_KEYRING_PASSWORD

This parameter specifies the password for the keyring database.

The following parameters are designed to work with your JDBC database credential mapper. Using this type of network-accessible database provides you with a flexible and secure means of associating user's network IDs to their host IDs. By storing all the relevant access information, you can configure access to an existing database or point to a newly created database. The level of security for the database varies according to database vendor.

CMPI_DCAS_DB_ADDRESS

This is a URL string that provides the address of the database.

CMPI_DCAS_DB_NET_DRIVER

This string contains the name of the class that acts as the network database driver. An example of this string is COM.ibm.db2.jdbc.net.DB2Driver. The location of this class is assumed to be in the existing class path.

CMPI_DCAS_DB_USERID

This is the ID of the user account to use when accessing the database.

CMPI_DCAS_DB_CASE_SENSITIVE

This parameter specifies whether or not the DCAS plugin converts the application ID and network ID of the user to lowercase characters and then uses the lcase() method to make SQL queries to the HCM database. This parameter should be set to true when using SQL applications that do not support the lcase() method.

CMPI_DCAS_DB_PASSWORD

This is the password of the user account to use when accessing the database.

CMPI_DCAS_DB_TABLE

This entry identifies the table to use for the needed query.

The following four parameter values should match the column names in your credential mapper database and should clearly indicate the contents of the columns. With some databases, such as IBM DB2, the four column headings in the database must be in all upper case, for example, NETWORKID, HOSTADDRESS, APPLICATIONID, and HOSTID.

CMPI_DCAS_DB_NETID_COL_NAME

This entry identifies the name of the column that contains the network ID value (NETWORKID).

CMPI_DCAS_DB_HOSTADDR_COL_NAME

This entry identifies the name of the column that contains the host address value (HOSTADDRESS).

CMPI_DCAS_DB_HOSTAPP_COL_NAME

This entry identifies the name of the column that contains the host application value (APPLICATIONID).

Note:

Application ID is only used for 3270 host types.

CMPI_DCAS_DB_HOSTID_COL_NAME

This entry identifies the name of the column that contains the user's host identification value (HOSTID).

Based on the information provided by the parameters above, you can make an SQL query of the database to get the host ID. This query uses the network ID, the host address, and the host application as keys for the query. The result is identified in the Host Identification column. Assuming that the query is successful, a call is made to the DCAS server to request the passticket.

Optional DCAS parameters: The following DCAS parameters are optional:

CMPI_DCAS_TRACE_LEVEL

This parameter specifies the trace level for the DCAS plug-in. The trace messages are logged to the HATS trace file. Trace level values include the following:

• 0 = None: No tracing. This is the default.

• 1 = Minimum: Trace APIs and parameters, return values, and errors.

• 2 = Normal: Trace Minimum plus internal APIs and parameters and informational messages.

• 3 = Maximum: Trace Normal plus Java exceptions.

CMPI_DCAS_HOST_PORT

The DCAS host address is determined based on the destination host specified in the request. The default port address of 8990 is used, but you may override it using this parameter.

CMPI_DCAS_HOST_ADDRESS

The default DCAS host address is determined based on the destination host specified for the HATS connection.

CMPI_DCAS_USE_WELLKNOWN_KEYS

This parameter indicates whether the WellKnownTrustedCAs.class should be used to look up the DCAS server certificate or not. The default is true.

CMPI_DCAS_VERIFY_SERVER_NAME

This parameter indicates if the server host name in the certificate must be verified in addition to the certificate validation. The default is false.

CMPI_DCAS_REQUEST_TIMEOUT

This parameter specifies the passticket request timeout in milliseconds. It should be less than the macro time-out value. The default is 50000.

CMPI_DCAS_DB_PRESERVE_WHITESPACE

This parameter indicates whether to trim white space from the credential request parameters or not. If true, the white space is not trimmed. The default is false.

CMPI_DCAS_WELLKNOWN_PASSWORD

If you choose to replace the provided WellKnownTrustedCAs.p12 with your own, you will need to specify the password here. Place your WellKnownTrustedCAs.p12 file in the same directory where the provided version was located.

DCAS parameters for Certificate-based DCAS/RACF Credential Mapper plugin

Required DCAS parameters:The following two Host Credential plugin parameters allow the client to connect to the DCAS server securely:

CMPI_DCAS_KEYRING_FILE

This parameter specifies a keyring database. The type of keyring file required is the .pkcs12 format. A keyring must be specified to provide access to the DCAS client certificate as well as the DCAS server's certificate. The certificates establish a client authenticated secure connection with the DCAS server. This parameter is a file reference to the keyring to be used. The DCAS plugin is the DCAS client. The keyring file must be stored in the .ear.

CMPI_DCAS_KEYRING_PASSWORD

This parameter specifies the password for the keyring database.

Optional DCAS parameters: The following DCAS parameters are optional:

CMPI_DCAS_TRACE_LEVEL

This parameter specifies the trace level for the DCAS plugin. The trace messages are logged to the HATS trace file. Trace level values include the following:

• 0 = None: No tracing. This is the default.

• 1 = Minimum: Trace APIs and parameters, return values, and errors.

• 2 = Normal: Trace Minimum plus internal APIs and parameters and informational messages.

• 3 = Maximum: Trace Normal plus Java exceptions.

CMPI_DCAS_HOST_PORT

The default port address of 8990 is used, but you may override it using this parameter.

CMPI_DCAS_HOST_ADDRESS

The default DCAS host address is the destination host specified for the HATS connection.

CMPI_DCAS_REQUEST_TIMEOUT

This parameter specifies the passticket request timeout in milliseconds. It should be less than the macro time-out value. The default is 50000.

CMPI_DCAS_USE_WELLKNOWN_KEYS

This parameter indicates whether the WellKnownTrustedCAs.class should be used to look up the DCAS server certificate or not. The default is true.

CMPI_DCAS_WELLKNOWN_PASSWORD

If you choose to replace the provided WellKnownTrustedCAs.class with your own, you will need to specify the password here. Place your WellKnownTrustedCAs.class file in the same directory where the provided version was located.

CMPI_DCAS_VERIFY_SERVER_NAME

This parameter indicates if the server host name in the certificate must be verified in addition to the certificate validation. The default is false.

Vault parameters for JDBC Vault Credential Mapper plugin

Add Vault parameters for CMPIVaultPlugin. For environments that use JDBC-based Vault host security, add the Vault plugin parameters. This model is identical to the database mechanism used to associate network IDs and host IDs in the DCAS passticket environment. The only difference is that Vault-style authentication requires the CMPI_VAULT_DB_HOSTPW parameter

Required Vault parameters: The following Vault parameters are required:

CMPI_VAULT_DB_ADDRESS

This is a URL string that provides the address of the database. An example of this string is jdbc:db2://dtagw:6789/CMTEST.

CMPI_VAULT_DB_NET_DRIVER

This string contains the name of the class that acts as the network database driver. An example of this string is COM.ibm.db2.jdbc.net.DB2Driver. The location of this class is assumed to be in the existing class path.

CMPI_VAULT_DB_USERID

This is the ID of the user account to use when accessing the database.

CMPI_VAULT_DB_CASE_SENSITIVE

This parameter specifies whether or not the Vault plugin converts the application ID and network ID of the user to lowercase characters and then uses the lcase() method to make SQL queries to the HCM database. This parameter should be set to true when using SQL applications that do not support the lcase() method.

CMPI_VAULT_DB_PASSWORD

This is the password of the user account to use when accessing the database.

CMPI_VAULT_DB_TABLE

This entry identifies the table to use for the needed query.

The following five parameter values exactly match the column names in your credential mapper database.

CMPI_VAULT_DB_NETID_COL_NAME

This entry identifies the name of the column that contains the network ID value (NETWORKID).

CMPI_VAULT_DB_HOSTADDR_COL_NAME

This entry identifies the name of the column that contains the host address value (HOSTADDRESS).

CMPI_VAULT_DB_HOSTAPP_COL_NAME

This entry identifies the name of the column that contains the host application value (APPLICATIONID).

Note:

Application ID is only used for 3270 host types.

CMPI_VAULT_DB_HOSTID_COL_NAME

This entry identifies the name of the column that contains the user's host identification value (HOSTID).

CMPI_VAULT_DB_HOSTPW_COL_NAME

This entry identifies the name of the column that contains the user's host password (PASSWORD).

Based on the information provided by the parameters above, you can make an SQL query of the database to get the host ID. This query uses the network ID, the host address, and the host application as keys for the query. The result is identified in the Host Identification column. Assuming that the query is successful, the user ID and password are returned.

Optional Vault parameters: The following Vault parameters are optional:

CMPI_VAULT_TRACE_LEVEL

This parameter specifies the trace level for the Vault plug-in. The trace messages are logged to the HATS trace file. Trace level values include the following:

• 0 = None: No tracing. This is the default.

• 1 = Minimum: Trace APIs and parameters, return values, and errors.

• 2 = Normal: Trace Minimum plus internal APIs and parameters and informational messages.

• 3 = Maximum: Trace Normal plus Java exceptions.

CMPI_VAULT_DB_PRESERVE_WHITESPACE

This parameter indicates whether to trim white spaces from the credential request parameters or not. If true, the white spaces are not trimmed. The default is false.

Vault parameter for the Credential Vault Credential mapper

Note:

This initialization parameter will only appear if you are working with a HATS portlet project.

SLOT_ID

This is the vault slot ID that will retrieve a passive user-password credential from a vault slot.

SLOT_TYPE

This parameter indicates the type of credential slot you want to access. Valid values are:

• 0 = Private Slot

• 1 = Shared Slot

• 2 = Administrative Slot: This is the default value.

• 3 = System Slot

For descriptions of the different types of slots, please refer to the WebSphere Portal product information Web site: http://www.ibm.com/developerworks/websphere/zones/portal/proddoc.html.

Credential Mapper selection

The following describes which Credential Mapper requests will be handled by this plugin:

Authentication type:

Table 7. Authentication types and descriptions

Authentication type	Description
AuthType_3270	Identifies the credentials to be used with a 3270 emulation
AuthType_5250	Identifies the credentials to be used with 5250 emulation
AuthType_VTHost	Identifies the credentials to be used with VT emulation

Host mask:

Table 8. Host masks and values matched

Host mask	Value matched
*.raleigh.ibm.com	Matches all addresses that end with .raleigh.ibm.com
ralvm*	Matches all addresses that start with ralvm
*	Matches all
*xyz*	Matches any host address that contains xyz

Create SSL key database (DCAS only)

In order to communicate with a DCAS server, an SSL connection must be established using client authentication. This requires you to create a key database file. The required key database file type is pkcs12. To create the file, use the HATS Certificate Management GUI. This key database file must contain the DCAS client's personal certificate and the DCAS server's certificate (public key) information. Also, the DCAS client certificate must be added/imported to the DCAS server's keyring for SSL client authentication.

If you already have an older certificate that was created using the iKeyman utility, you may import it. Personal server certificates that were created with the old system cannot be easily exported from the old and imported into the new. There is however a way which you can do this:

1. Import the entire old format .kdb file into the new iKeyman

2. Export the desired certificates (such as, DCAS server certificate) to a .p12 format certificate.

3. Import the .p12 file into the new format .p12 keyring file.

Figure 35. HATS Certificate Management

To create a new keyring database called HatsWelKeys.p12 file that will be specified in the CMPI_DCAS_KEYRING_FILE parameter in your .xml file, take the following steps on a Windows machine.

1. Click Start > Programs > IBM WebSphere HATS 6.0 > Certificate Management

2. Click Key Database File and select New. For the Key database type, select PKCS12. For File Name, type HatsWelKeys.p12. For Location, type <hats_install_directory>\eclipse\plugins\com.ibm.hats_6.0.0\. (You will have to manually put this in your .ear file. You may choose a different name and location.)

3. Click OK.

4. Type the password and make a note of it.

5. Click OK.

6. Add the DCAS server's certificate to the key database. Be sure that the key database content is for the Signer Certificate. If it is not, select the pull-down menu and change it. Then select Add.

   1. Select Binary DER data for the Data type. If the server certificate is in ASCII format, select Base64-encoded ASCII data.

   2. Type the file name in the Certificate file name field.

   3. Type the path name in the Location field.

   4. Click OK.

   5. Enter a label for the certificate and click OK.

7. Add the DCAS client's certificate to the key database.

   1. Change the Key database content to Personal Certificates and click Import.

   2. Select PKCS12 for the Key file type.
      Note:

      You may have to browse to the select the keyring file (.p12/pkcs12) containing the certificate to import and enter the userid and password to open the file. It is best to make sure the keyring file contains only certificates that you want to import. You can also import certificates from a .kdb file. In this case, it will allow individual certificates to be selected.

   3. Type the client certificate's p12 file name in the File Name field and the path name in the Location field.

   4. Click OK and enter the client certificate PIN.

   5. Click OK.

8. Exit the Certificate Management GUI.

Configure the Certificate Management application to run with the icon minimized

When the Certificate Management application is invoked, a DOS window appears and is displayed the entire time the application is running. The window is finally closed once you exit from the application. The reason why the DOS window is displayed is because the default run property for the Certification Management application is "Normal Window".

To minimize the DOS window when the application is invoked, follow the following steps:

1. Go to Start > All Programs > IBM WebSphere HATS 6.0

2. Right click on Certificate Management and choose Properties

3. Configure the Run property to be "Minimized"

4. Click OK