Configuring macro-based automation in a vault-style environment

In order to implement macro-based automation in a vault-style environment, you must configure your network security application and create your HCM database.

The following steps show you how to edit and deploy the CMS provided with Host On-Demand and use the Deployment Wizard to create your HTML file, configure your 3270 host session, and record your login macro.

Steps 3-6 are designed for administrators who are planning to use the Deployment Wizard to create the HTML file, configure the host session to use Web Express Logon, and record the Web Express Logon macro all in one sitting. However, you may decide to create your HTML file first and then configure your session and create your macro later.

Step 1: Configure the Credential Mapper Servlet (CMS).

We recommend using a J2EE-compliant Web application server such as IBM WebSphere Application Server to configure and deploy the Credential Mapper Servlet (CMS). The CMS is supplied with Host On-Demand and must be deployed to a J2EE-compliant Web application server. At a high level, the CMS is responsible for the following tasks: (1) determine the client's identity by means of the local system ID, network ID, or Portal ID, (2) map the user's ID to the host ID, and (3) return the host credentials to the client as an XML document.

A. Locate the WAR files on the Host On-Demand DVD

The three WAR files are located in the cdimage\apps\wel subdirectory. Choose the one that matches your network security application:

IBM Tivoli Access Manager: amcms.war
Netegrity Siteminder: smcms.war
Microsoft Active Directory (Windows Domain): wincms.war

If you have a different network security application, you will need to customize your own version of the CMS. For more information about how to do this, refer to Customizing Web Express Logon.

In addition to several other files, the WAR file contains the following files:

web.xml: the servlet configuration file that you will edit in a later step
Vault.xml: a sample file to help you better understand Vault parameters and their values
was.policy: for IBM WebSphere Application Server users only, this file contains the required permissions for the CMS when Java 2 security is enabled (refer to Troubleshooting Web Express Logon for more information)

B. Become familiar with the INIT parameters in the web.xml file.

In this step, you will become familiar with the three default INIT parameters in the web.xml file.

Host Credential Mapper (HCM) plug-in: The name of the parameter is CMPICredentialMappers, and the parameter value is a compound value that contains the list of all available HCM plug-ins, for example, CMPIDCASPlugin CMPIVaultPlugin, and CMPIDCASELFPlugin. Currently, the value is echo, but you will eventually replace this with the name of your HCM plug-in.
Code example:
```
<init-param>
   <param-name>CMPICredentialMappers</param-name>          
   <param-value>echo</param-value>  
</init-param>
```

Network Security plug-in: The name of the parameter is CMPINetworkSecurity, and the parameter value is the full path name of the class that handles the CMS interface into the network security application. This example is taken from the amcms.war file, which is based on the Tivoli Access Manager network security application:

Code example:

<init-param>
     <param-name>CMPINetworkSecurity</param-name>
     <param-value>com.ibm.eNetwork.security.sso.cms.CMNPIAccessManager</param-value>      
</init-param>

The Network Security plug-in does not apply to Microsoft Active Directory (Windows Domain), Portal Server, or Certificate-based Web Express Logon. For Microsoft Active Directory, the Windows login ID is used to identify the user. For Portal Server, the Portal ID is used to identify the user. For Certificate-based Web Express Logon, the client certificate is used to identify the user.

echo plug-in: The name of this INIT parameter (echo) is the same as the value for the HCM plug-in. In a future step, you will replace echo with the name of your HCM plug-in.

Host On-Demand provides this optional echo plug-in in case you want to confirm that you are able to deploy the CMS correctly before you begin editing the web.xml file. For example, after you deploy your CMS to a Web server, you can test it by entering the following syntax in a workstation's browser address bar: https://web_application_server_name/context_root/CredMapper, where web_application_server_name is the name of the Web application server, context_root is the name of the context root that you specify when deploying the CMS, and CredMapper is the name of the CMS itself.

Some Web application server products allow you to deploy the servlet first and then edit the XML file. Other products, such as WebSphere Application Server Version 5, work best when you deploy the servlet after you edit the XML code. Refer to your product's documentation for details.

Code example:

<init-param>
   <param-name>echo</param-name>
   <param-value>com.ibm.eNetwork.security.sso.cms.CMPINetEcho,AuthType_All,*
		</param-value>
</init-param>

C. Edit the CMS-related parameters.

In this step, you will edit two of the three INIT parameters in the web.xml file. INIT parameters adapt the servlet to your environment. You will not edit the CMPINetworkSecurity parameter name or value.

Locate the CMPICredentialMappers parameter and change the name of its current value (echo) to the name of your HCM plug-in. In this example, the HCM plug-in is CMPIVaultPlugin:
```
<init-param>
  <param-name>CMPICredentialMappers</param-name> 
  <param-value>CMPIVaultPlugin</param-value> 
</init-param>
```

Locate the echo parameter and change the name of its current value (echo) with the name of the parameter value that you specified for the HCM plug-in (CMPIVaultPlugin).

Now, replace the parameter value with a compound value that contains the full class path name of the implementing class, the authentication type to be used by the HCM plug-in, and the host mask. Separate these values with commas. In this example, com.ibm.eNetwork.security.sso.cms.CMPIVault is the full class path name, AuthType_All is the authentication type, and * is the host mask.

Full class path name

The CMS uses the value of the full class path name to create a class object of the specified type. That object is then used to handle CMS or HCM requests. The specified class file must be in the ...\WEB-INF\classes subdirectory in a loose file (not as a JAR file). From this location, the CMS will be able to access and use it whenever the need arises.

Authentication type

This value is used to identify the type of authentication that the requestor needs. Once you specify the desired authentication type, the CMS can better identify which credential mapper to select to handle the request. You can pair multiple authentication types together to give HCM plug-ins the freedom to support multiple authentication types. Use the vertical bar character to join multiple authentication types.

The five identified authentication types are listed in Table 4:

Authentication used in Secure Shell (SSH) on VT emulation or sftp sessions are not supported by the HCM plug-in.

Table 4. Authentication types and descriptions
Authentication type	Description
`AuthType_3270Host`	Identifies the credentials to be used with a 3270 emulation
`AuthType_5250Host`	Identifies the credentials to be used with 5250 emulation
`AuthType_VTHost`	Identifies the credentials to be used with VT emulation
`AuthType_FTPPassword`	Credentials used to access an FTP host
`AuthType_ConfigServer`	Credentials identified by the token used to identify the user to the Host On-Demand configuration server (if you are using the Configuration server-based model
`AuthType_All`	Identifies the credentials to be used for all authentication types

Host mask

The host mask is a secondary selection criteria used by the CMS to identify the most appropriate credential mapper. This value can contain one or more host addresses. Use the vertical bar character to join multiple addresses. Use the asterisks character to wildcard a host address. The wildcard character may start, end, or start and end a host address.

Table 5 lists valid wild-carded addresses:

Table 5. 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`

Code example:

<init-param>
  <param-name>CMPIVaultPlugin</param-name> 
  <param-value>com.ibm.eNetwork.security.sso.cms.CMPIVault, AuthType_All, *
		</param-value> 
  </init-param>

D. Add optional CMS-related debugging parameters.

Add the following two optional debugging parameters to help you troubleshoot:

CMPI_TRACE_LOG_FILE

This parameter specifies the name of the log file. The value should be the full path to the log file, for example C:\Program Files\IBM\HostOnDemand\HODWEL.log on a Windows platform.

Code example:

<init-param> 
   <param-name>CMPI_TRACE_LOG_FILE</param-name> 
   <param-value>C:\Program Files\IBM\HostOnDemand\HOD\HODWEL.log
		</param-value> 
</init-param>

CMPI_CMS_TRACE_LEVEL

This parameter specifies the trace level for the CMS. The trace messages are logged to the log file specified by CMPI_TRACE_LOG_FILE parameter. Depending on your Web application server, they may or may not be logged to the console. 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.

Code example:

<init-param> 
   <param-name>CMPI_CMS_TRACE_LEVEL
	 </param-name> 
   <param-value>3</param-value> 
</init-param>

E. Add the required Vault parameters for the CMPIVaultPlugin.

Add the required Vault parameters to allow the HCM database to map the user ID to the host ID.

Use the Vault.xml file located in the WAR file as a reference for adding parameters when editing the web.xml file.

The following parameters contain all the relevant information needed to connect to your HCM database, which in this example is a JDBC database table. You can either 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. Refer to the database application's documentation for details.

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

Code example:

<init-param> 
   <param-name>CMPI_VAULT_DB_ADDRESS</param-name>  
	 <param-value>jdbc:db2://dtagw.raleigh.ibm.com:6789/HODSSO</param-value> 
</init-param>

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.

Code example:

<init-param> 
   <param-name>CMPI_VAULT_DB_NET_DRIVER</param-name> 
   <param-value>COM.ibm.db2.jdbc.net.DB2Driver</param-value> 
</init-param>

CMPI_VAULT_DB_USERID

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

Code example:

<init-param> 
   <param-name>CMPI_VAULT_DB_USERID</param-name> 
   <param-value>admin</param-value> 
</init-param>

CMPI_VAULT_DB_PASSWORD

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

This parameter should be encrypted using the encrypt password tool. It is decrypted by the HCM plug-in before using it. For more information about the password encryption tool, refer to Appendix C. Password encryption tool.

Code example:

<init-param> 
   <param-name>CMPI_VAULT_DB_PASSWORD</param-name> 
   <param-value>tuBu9v8lHiJi1jt08UgHzA==</param-value> 
</init-param>

CMPI_VAULT_DB_TABLE

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

Code example:

<init-param> 
   <param-name>CMPI_VAULT_DB_TABLE</param-name> 
   <param-value>HACP</param-value> 
</init-param>

The following parameters should correspond directly to the column headings in your HCM database and should clearly indicate the contents of the columns. With some databases, such as IBM DB2, the column headings must be in all upper-case letters, for example, NETWORKID, HOSTADDRESS, APPLICATIONID, HOSTID, and PASSWORD.
Based on the information provided by the first three of these parameters (network ID, host address, and the host application ID), you can make a SQL query of the database to get the host ID. The result of the query is entered in the host ID (HOSTID) column. Assuming that the query is successful, a call is made to the DCAS to request the passticket.
CMPI_VAULT_DB_NETID_COL_NAME
This entry identifies the name of the column that contains the network ID value (NETWORKID).
Code example:
```
<init-param> 
   <param-name>CMPI_VAULT_DB_NETID_COL_NAME</param-name> 
   <param-value>NETWORKID</param-value> 
</init-param>
```
CMPI_VAULT_DB_HOSTADDR_COL_NAME
This entry identifies the name of the column that contains the host address value (HOSTADDRESS).
Code example:
```
<init-param> 
   <param-name>CMPI_VAULT_DB_HOSTADDR_COL_NAME</param-name> 
   <param-value>HOSTADDRESS</param-value> 
</init-param>
```
CMPI_VAULT_DB_HOSTADDR_COL_NAME
This entry identifies the name of the column that contains the host address value (HOSTADDRESS).
Code example:
```
<init-param> 
   <param-name>CMPI_VAULT_DB_HOSTADDR_COL_NAME</param-name> 
   <param-value>HOSTADDRESS</param-value> 
</init-param>
```
CMPI_VAULT_DB_HOSTAPP_COL_NAME
This entry identifies the name of the column that contains the host application value (APPLICATIONID).
Code example:
```
<init-param> 
   <param-name>CMPI_VAULT_DB_HOSTAPP_COL_NAME</param-name> 
   <param-value>APPLICATIONID</param-value> 
</init-param>
```
CMPI_VAULT_DB_HOSTID_COL_NAME
This entry identifies the name of the column that contains the user's host identification value (HOSTID).
Code example:
```
<init-param> 
   <param-name>CMPI_VAULT_DB_HOSTID_COL_NAME</param-name> 
   <param-value>HOSTID</param-value> 
</init-param>
```
CMPI_VAULT_DB_HOSTPW_COL_NAME
This entry identifies the name of the column that contains the host password value (PASSWORD).
Code example:
```
<init-param> 
   <param-name>CMPI_VAULT_DB_HOSTPW_COL_NAME</param-name> 
   <param-value>PASSWORD</param-value> 
</init-param>
```

F. Add the optional Vault parameters (if desired).

Unlike the previous set of Vault parameters, the following parameters are optional. Which of these parameters you add to the web.xml file depends on your environment and your objectives as an administrator:

CMPI_VAULT_TRACE_LEVEL

This parameter specifies the trace level for the Vault plug-in. The trace messages are logged to the log file specified by CMPI_TRACE_LOG_FILE parameter. Depending on your Web application server, they may or may not be logged to the console. 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.

Code example:

<init-param> 
   <param-name>CMPI_VAULT_TRACE_LEVEL</param-name> 
   <param-value>3</param-value> 
</init-param>

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.

Code example:

<init-param> 
   <param-name>CMPI_VAULT_DB_PRESERVE_WHITESPACE</param-name> 
   <param-value>false</param-value> 
</init-param>

CMPI_VAULT_DB_CASE_SENSITIVE

This parameter specifies whether or not the Vault plug-in 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.

Code example:

<init-param> 
   <param-name>CMPI_VAULT_DB_CASE_SENSITIVE</param-name> 
   <param-value>false</param-value> 
</init-param>

Step 2: Save the WAR file and deploy the CMS.

Once you save the WAR file with your edits, you are ready to deploy the servlet to the Web server. Refer to your Web server application's documentation for details of how to deploy the servlet.

Step 3: Begin creating your HTML file.

The Host On-Demand Deployment Wizard allows you to create an HTML file that is used to launch Host On-Demand sessions. Within the Deployment Wizard, you can add, delete, configure, and start sessions. It guides you configuration choices and provides comprehensive help for the features. When you have finished selecting features, it creates the HTML and supporting files for you.

To begin creating your HTML file on a Windows machine, take the following steps:

Open the Deployment Wizard:
- If you automatically installed the Deployment Wizard as part of the Windows Host On-Demand server, click Start > Programs > IBM Rational Host On-Demand > Administration > Deployment Wizard.
- If you installed the Deployment Wizard from the Host On-Demand DVD separately, click Start > Programs > IBM Rational Host On-Demand Deployment Wizard > Deployment Wizard.
On the Welcome to the Deployment Wizard window (Figure 14), select either to create a new HTML file or edit an existing file. Click Next.
Figure 14. Welcome to the Host On-Demand Deployment Wizard window

If you are creating a new HTML file, select one of the following three configuration models on the Configuration Model window (Figure 15) and click Next:

HTML-based model
Configuration server-based model
Combined model

If you are using the HTML-based or Combined models, you can create your HTML file as normal. However, if you are using the Configuration server-based model, you must configure the HTML file with additional steps. Refer to Appendix B. Web Express Logon using the Configuration server-based model for more information.

Figure 15. Configuration Model window

On the Host Sessions window, click New/Import to open the Add session window (Figure 16). This window allows you to either create a new session (default) or import an existing session. To create a new session, select a host type, enter a session name, and a destination address. Click OK to return to the Host Sessions window.
Figure 16. Add session window

Step 4: Configure the Host On-Demand session to use Web Express Logon.

Take the following steps to configure your Host On-Demand session to use Web Express Logon.

Using the Host Sessions window, highlight your session and select Properties under the Configure drop-down menu. On the left side of the window, select Express Logon under Connection.

You may also open session properties by right-clicking a session icon and selecting Properties.
On the Express Logon window (see Figure 17), select Web Express Logon as the Express Logon type.
Figure 17. 3270 Express Logon
Select the User Identity Type:
- Local System ID: the user's local operating system ID. Web Express Logon currently supports Microsoft Active Directory (Windows Domain).
- Network ID: the user's network security application ID. Web Express Logon currently supports IBM Tivoli Access Manager and Netegrity Siteminder.
- Portal ID: the user's Portal Server ID. Web Express Logon currently supports Portal Server, a component of IBM WebSphere Portal.
Type the full URL of the credential mapper server, for example, https://server_name/junction/cm/CredMapper, where
- server_name is the name of the authentication server
- junction is the name of the junction (optional)
- cm is the credential mapper servlet space
- CredMapper is the servlet name
Be sure that the servlet name matches the name in your XML file. For example, if you specify the servlet name in your host session as CredMapper, the code in your XML should look like the following:
```
<servlet>
      <servlet-name>CredMapper</servlet-name>
      <display-name>CredMapper</display-name>    
<servlet-class>com.ibm.eNetwork.security.sso.cms.CredMapper</servlet-class>
```
The servlet that resides at this URL processes the HTTPS request from the user, performs a lookup, and returns the user's credentials. The Host On-Demand client uses the obtained credentials to automate the login process.
Click OK.

Step 5: Record the Web Express Logon macro.

To record a macro, you must first start a host session. To start a session from within the Deployment Wizard, highlight your session on the Host Sessions window (Figure 18) and click Actions > Start.

Figure 18. Host Sessions window

For details about how to record the Web Express Logon macro, refer to Appendix A. Recording the Web Express Logon macro.

Step 6: Finish creating your HTML file.

Now that you have configured your Host On-Demand session to use Web Express Logon and have recorded your login macro, you are ready to finish creating your HTML file using the Deployment Wizard. To finish creating the file, take the following steps:

On the Host Sessions window, click Next to open the Additional Options window (Figure 19). Make any changes that you desire and click Next.
Figure 19. Additional Options window
On the File Name and Output Format window (Figure 20), enter the page title, the file name, choose the directory where you want to save your file, and check the Output HTML box. You should save your file to the Host On-Demand server in a directory known to your Web server; usually, this directory is your Host On-Demand server's publish directory. Click Create File(s) to finish creating your HTML file.
Figure 20. File Name and Output Format window

Congratulations! You have taken all the necessary steps to implement Web Express Logon in a vault-style environment. Your next step is to test the logon automation. If logon automation is not successful, that is, you are still being prompted with the host logon screen, refer to Troubleshooting Web Express Logon.