Before using this information and the product it supports, read the information in Appendix G. Notices.
This edition applies to Version 10 of IBM(R) WebSphere Host On-Demand (program number 5724-I20) and to all subsequent releases and modifications until otherwise indicated in new editions.
This book is written for administrators who are interested in understanding, planning for, implementing, and troubleshooting Web Express Logon. It provides step-by-step instructions for configuring Host On-Demand for Web Express Logon. For details about configuring other applications such as your network security application, refer to the Web Express Logon for Host On-Demand white paper, located at ftp://ftp.software.ibm.com/software/network/hostondemand/library/whitepapers/wel2.pdf.
This book contains the following parts:
The following typographic conventions are used in Host On-Demand Web Express Logon Reference:
| Convention | Meaning |
|---|---|
| Monospace | Indicates text you must enter at a command prompt and values you must use literally, such as commands, functions, and resource definition attributes and their values. Monospace also indicates screen text and code examples. |
| Italics | Indicates variable values you must provide (for example, you supply the name of a file for file_name). Italics also indicates emphasis and the titles of books. |
| > | When used to describe a menu, shows a series of menu selections. For example, "Click File > New" means "From the File menu, click the New command." |
When used to describe a tree view, shows
a series of folder or object expansions. For example, "Expand HODConfig
Servlet > Sysplexes > Plex1 > J2EE Servers > BBOARS2" means:
|
|
|
This graphic is used to highlight notes to the reader. |
|
|
This graphic is used to highlight tips for the reader. |
|
|
This graphic refers to information that is specific to Certificate-based Web Express Logon. |
In the age of e-business on demand, finding ways to simplify the user experience while maintaining company security can be a real challenge. For example, many companies would like to decrease the number of IDs and passwords that their users have to manage, but they also realize that allowing users to access company resources without proper identification risks company security.
Several products exist in the marketplace that claim to solve the multiple logon issue and maintain security at the same time. However, these products generally apply to Web-based applications only and do not address logon processes for legacy hosts and host-based applications. In other words, in host-based applications that do not use HTML or XML, automating the logon process requires being able to intercept the telnet data stream. Because of its unique position to work with individual screens and the ability to substitute fields in the data stream, Host On-Demand is an ideal candidate to address multiple logon issues in companies where users access host systems via browser-based terminal emulation.
Web Express Logon 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:
Host On-Demand offers three types of Express Logon:
Web Express Logon has been available since Host On-Demand Version 8, Certificate Express Logon, formerly known as Express Logon Feature (ELF), has been available since Host On-Demand Version 5. Although the name has changed, Certificate Express Logon functions the same as ELF did in earlier versions and requires the same configuration. Reuse Active Credentials is a feature available in Host On-Demand Version 10.0.
Reuse Active Credentials provides automated authentication on all emulation platforms. It is not as comprehensive as Web Express Logon but does not require any special network configuration. If a new connection is made to a host and a user has already authenticated to that host somehow, those credentials are applied to the new connection. The credentials are maintained for as long as Host On-Demand is running in the JVM. The credentials are only stored in Java memory and once the JVM closes they will have to be re-entered when Host On-Demand is restarted.
Although all three types of Express Logon allow users to log on to a host system without having to enter a user ID and password, they have different requirements for session type, client certificates, and SSL configuration. Certificate Express Logon works exclusively with 3270 session types and requires client-side certificates and an SSL connection to a TN3270 server. Web Express Logon and Reuse Active Credentials offer a wide variety of styles that function with all Host On-Demand session types (not just 3270 emulation). Certificate Express Logon requires a macro to log on to the host application and then distribute that macro to the clients. Web Express Logon and Reuse Active Credentials may or may not require a macro, depending on your environment.
DCAS and z/OS environments that use client certificates for user authentication are no longer limited to Certificate Express Logon. Starting with Host On-Demand V9, Web Express Logon offers a type of logon automation that uses client-side certificates known as Certificate-based Web Express Logon. Although both Certificate Express Logon and Certificate-based Web Express Logon work exclusively with 3270 host sessions and require a DCAS server, the client certificates in the two models are used differently and the automation process requires different components. With Certificate Express Logon, client certificates are used to authenticate users to an Express Logon-enabled TN3270 server, and the Host On-Demand client and a TN3270 server are configured to automate the login process. With Certificate-based Web Express Logon, however, client certificates are used to authenticate users to a secure Web server, and a Host Credential Mapper plug-in and a macro are used to automate the login process.
Certificate-based Web Express Logon is a more flexible solution than Certificate Express Logon because it provides more implementation options. For more information about Certificate-based Web Express Logon, refer to Configuring macro-based automation in a z/OS and DCAS environment.
Host On-Demand V9 offers a new DCASELF plug-in that allows users of Certificate Express Logon to migrate to the more scalable certificate-based Web Express Logon architecture. This plug-in allows you to move SSL client authentication from the TN3270 server to a secure Web server. For specific details about how to migrate from Certificate Express Logon to certificate-based Web Express Logon, refer to the Web Express Logon white paper, located at
ftp://ftp.software.ibm.com/software/network/ hostondemand/library/whitepapers/wel2.pdf
.
The overall goal of Web Express Logon is to provide an automated way for users to log on to hosts and host-based applications without having to provide an additional ID and password. In order to accommodate the wide range of supported computing environments, Web Express Logon offers two styles of logon automation:
The style of logon automation that best suits your needs depends on your environment, including your host type, session type, and your current method for authenticating users. If the host does not allow the client to supply the needed credentials at the time the connection is established, for example, if the client must authenticate to the host after the host connection is established, macro-based automation is the appropriate style. In this model, the host must send a login screen to authenticate the client. The macro automates the login screen, populates the screen's credential fields with the appropriate user information, and then transmits this information to the host for authentication. However, if your host allows the client to supply the needed host credentials at the time the host connection is established, for example, using Kerberos authentication or FTP login, connection-based automation is the appropriate style.
The following sections provide more details about macro- and connection-based automation, including high-level overviews of some example environments supported by Web Express Logon. These examples are discussed in more detail throughout the remainder of this document.
As the name implies, macro-based automation requires a macro to automate the login process. The macro is responsible for obtaining the user's host credentials and passing that information to the host for authentication. The host credentials are based on one of the following user identity types:
User identity type is a configurable option in session properties.
|
|
If you plan for Host On-Demand to acquire the user's credentials from a different application than the ones supported by Web Express Logon, you will need to create your own plug-in. For more information, refer to Customizing Web Express Logon. |
Macro-based automation relies on the following four key components and the interactions that take place among them. Not all environments that use macro-based automation use all four components:
The login macro automates the end-to-end process of the client sending the HTTPS request to the CMS, the CMS responding with the needed credentials, and the macro inserting the user's credentials in the proper fields to allow authenticated logon. You must record the login macro while you are in an active session. It initiates at the time the user attempts to access the host session, either automatically or manually (depending on your configuration).
The CMS is supplied with Host On-Demand and must be deployed to a J2EE-compliant HTTP server. At a high level, the CMS is responsible for determining the client's identity and returning the host credentials to the client as an XML document.
|
|
The CMS is not required if using the Portal Credential Vault as your HCM database. This is because the Host On-Demand portlet is designed to allow the Web Express Logon macro to acquire the user's credentials directly from Portal Server. |
Host On-Demand provides two Network Security plug-ins, one for each of the two supported network security applications -- IBM Tivoli Access Manager and Netegrity Siteminder. 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 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. |
The HCM database is a back-end repository that maps users' network IDs to their host credentials. This repository can be one of the following:
The Digital Certificate Access Server (DCAS) and Vault plug-ins provided with Web Express Logon and Host On-Demand portlets are designed to work with these repositories. Another possibility for a repository is an LDAP directory. However, using LDAP as your HCM database requires you to write your own plug-in. For more information, refer to Customizing Web Express Logon.
The following examples show you how the key components discussed above interact together, beginning at the point the user attempts to open a Host On-Demand session and initiate the login macro. If the macro is not configured to auto-start, the user will need to start it manually.
The following three Web Express Logon-supported environments use macro-based automation:
In a z/OS and DCAS environment, Web Express Logon supports two different models--one in which users are identified via client certificates (called Certificate-based Web Express Logon) and one in which users are identified via a network security application. Since both of these models have their own requirements for user identification, the Web Express Logon configuration steps are different for each model. In a certificate-based environment, you must configure your HTTP server as well as the browser and Java 2 keystore on each Host On-Demand client. In a non-certificate-based environment, you must configure your network security application and create your HCM database. Both models require you to configure the Digital Certificate Access Server (DCAS).
Figure 1 and Figure 2 along with the accompanying steps illustrate how Certificate-based and non-Certificate-based Web Express Logon work in a z/OS and DCAS environment:
The login macro automatically inserts the user's credentials in the logon screen fields without user intervention. Now the user is fully authenticated and can proceed with the session.
For more information, refer to Configuring macro-based automation in a z/OS and DCAS environment.
In this model, users are authenticated in a vault-style environment. Figure 3 illustrates this environment:
In this model, users are authenticated via Portal Server, a component of IBM WebSphere Portal. Figure 4 illustrates this environment:
Macro-based automation has been successfully tested with the following applications:
|
|
The macro-based automation version of Web Express Logon can function with other applications that are not listed here. |
Unlike macro-based automation, connection-based automation does not require a macro because the client and the host are able to connect without having to provide the user with a login screen.
The following two Web Express Logon-supported environments use connection-based automation:
Currently, Web Express Logon supports i5/OS and OS/400 (V5R2 and later) telnet-negotiated environments that have Kerberos authentication enabled. It does not require the CMS, a login macro, a Network Security plug-in, nor the HCM database. Instead, it extends the existing single sign-on capability of the i5/OS and OS/400 operating systems.
In order for connection-based automation to function in this environment, you must have the following prerequisites in place:
You must configure your i5/OS or OS/400 environment to use single sign-on capability in order to implement connection-based logon automation. The i5/OS or OS/400 environment provides single sign-on capability through a combination of network authentication service and an IBM technology called Enterprise Identity Mapping (EIM). Host On-Demand uses this existing methodology for acquiring credentials to allow users to bypass the 5250 session login screen. Both network authentication service and EIM technology are available with the i5/OS and OS/400 (V5R2 and later) operating systems.
Figure 5 illustrates the overall process of connection-based automation in an i5/OS or OS/400 environment with Kerberos authentication enabled:
Web Express Logon provides an automated way for users to log on to FTP hosts by providing a central repository for storing and retrieving user's credentials. Although this process is similar to configuring Web Express Logon in a vault-style environment , this type of automation is different because the user's credentials are retrieved from the CMS at the time the connection is established. In other words, it does not require a macro. Currently, Host On-Demand allows you to store a user's ID and password statically in the FTP configuration; however, Web Express Logon extends this approach by automating the user credential retrieval process.
Figure 6 illustrates the overall process of connection-based automation in an FTP login environment:
Having a clear understanding of your environment and how you plan to implement Web Express Logon in your environment will save you valuable time in the implementation phase. Be sure that you take time to develop your strategy and gather the necessary resources and skills. A firm plan is key to a successful implementation.
We recommend that you begin planning by taking the following steps:
As described in the introduction, Host On-Demand offers two styles of logon automation:
The style of logon automation that best suits your environment depends on your host and session type. If your host allows the client to supply the needed host credentials at the time the connection is established (for example, during the telnet negotiation via a Kerberos passticket), connection-based automation is the appropriate style to use. However, if the client does not receive the needed credentials at time the connection is established, the host must send a login screen to authenticate the client. Since automating this login screen requires a macro, macro-based automation is the appropriate style. The macro populates the screen's credential fields with the appropriate user information and then transmits this information to the host for authentication.
Credential challenges are the times at which users are prompted to provide IDs and passwords. The first step is to evaluate your existing network infrastructure and identify which credential challenges exist for your users. Approach this step by simulating a typical day and identifying all the points at which users are prompted to provide credentials. For example, in a corporate environment, users may have to provide credentials when attempting to access any of the following resources:
At this point, you should know which style of logon automation is appropriate for your environment and what components are necessary to implement Web Express Logon. Before you can successfully plan your deployment strategy and estimate the scope of implementation, take a moment to take an inventory of your environment and answer the following questions according to your style of logon automation:
Now that you have evaluated your need for a Web Express Logon solution, chosen the style of logon automation that best works in your environment, and taken an inventory of your company's environment and resources, you can begin developing your deployment strategy. Consider issues such as how many/which users will be affected by this implementation, which skills are required for a successful implementation, and how many people you will need to participate in the setup process.
This step does not apply to Certificate-based Web Express Logon or i5/OS or OS/400 environments that support Kerberos authentication. An HCM database is required for all other environments discussed in this document.
|
|
This document does not provide details about how to
establish an HCM database. For these details, refer to the Web Express Logon
white paper, located at
ftp://ftp.software.ibm.com/software/ network/hostondemand/library/whitepapers/wel2.pdf. |
An HCM is a back-end repository that associates users' network IDs to their host IDs. The CMS queries this repository during the logon process. Web Express Logon supports the following two types of HCM databases:
Another possibility for a repository is an LDAP directory. However, using LDAP as your HCM database requires you to write your own plug-in. For more information, refer to Customizing Web Express Logon.
The way in which you implement macro-based automation depends on your environment. In this section, we focus on the following three environments:
|
|
This document does not provide details for configuring
other applications to work with Host On-Demand Web Express Logon. For more
information regarding configuring other applications, refer to the Web Express
Logon for Host On-Demand white paper, located at
ftp://ftp.software.ibm.com/software/ network/hostondemand/library/whitepapers/wel2.pdf. |
|
|
The DCAS is a TCP/IP server application that runs on OS/390 V2R10 and later (z/OS included). It interfaces with a Security Access Facility (SAF)-compliant server product to assist with express logon services such as Certificate-based Web Express Logon. In this example, this SAF-compliant server product is IBM Resource Access Control Facility (RACF). |
Web Express Logon supports two different models for z/OS and DCAS environments--one in which users are identified via a network security application and one in which users are identified via client certificates (called Certificate-based Web Express Logon). The configuration steps defined in this chapter cover both models with certain information that is specific to Certificate-based Web highlighted with the following icon:
|
|
Refers to information that is specific to Certificate-based Web Express Logon. |
The following steps show you how to edit and deploy the CMS provided with Host On-Demand, create an SSL key database so that Host On-Demand can communicate with the DCAS, and use the Deployment Wizard to create your HTML file, configure your 3270 host session, and record your login macro. In a certificate-based environment, you must also configure your HTTP server as well as the browser and Java 2 keystore on each Host On-Demand client. In a non-certificate-based environment, you must configure your network security application and create your HCM database. Both models require you to configure the Digital Certificate Access Server (DCAS).
|
|
For more information about configuring Host On-Demand clients for HTTPS and client authentication, refer to the Planning, Installing, and Configuring Host On-Demand guide located in the Host On-Demand Information Center at Start > Programs > IBM WebSphere Host On-Demand > Information Center or on the Web at http://publib.boulder.ibm.com/infocenter/hod9help. |
|
|
Steps 5-8 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. |
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 determining the client's identity and returning the host credentials to the client as an XML document.
The three WAR files are located in the cdimage\apps\wel subdirectory. Choose the one that matches your network security application:
|
|
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:
In this step, you will become familiar with the three default INIT parameters in the web.xml file.
Code example:
<init-param> <param-name>CMPICredentialMappers</param-name> <param-value>echo</param-value> </init-param>
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. |
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 V5, 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>
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.
<init-param> <param-name>CMPICredentialMappers</param-name> <param-value>CMPIDCASPlugin</param-value> </init-param>
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 DCAS HCM plug-in, and the host mask. Separate these values with commas. In this example, com.ibm.eNetwork.security.sso.cms.CMPIDCAS is the full class path name, AuthType_3270Host 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 plug-in 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 the Table 2:
|
|
Authentication used in Secure Shell (SSH) on VT emulation or sftp sessions are not supported by the HCM plug-in. |
| 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 3 lists valid wild-carded addresses:
| 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 |
<init-param> <param-name>CMPIDCASPlugin</param-name> <param-value>com.ibm.eNetwork.security.sso.cms.CMPIDCAS, AuthType_3270Host, *</param-value> </init-param>
Add the following two optional debugging parameters to help you troubleshoot:
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>
Code example:
<init-param> <param-name>CMPI_CMS_TRACE_LEVEL</param-name> <param-value>3</param-value> </init-param>
Add the required DCAS client parameters to allow the HCM database to map the user ID to the host ID and 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.
|
|
Starting with Host On-Demand V9.03, the CMPI_DCAS_KEYRING_FILE and CMPI_DCAS_KEYRING_PASSWORD are deprecated and should not be used. Instead, CMPI_DCAS_TRUSTSTORE, CMPI_DCAS_TRUSTSTORE_PASSWORD, and CMPI_DCAS_TRUSTSTORE_TYPE should be used. However, CMPI_DCAS_KEYRING_FILE and CMPI_DCAS_KEYRING_PASSWORD will continue to work in lieu of CMPI_DCAS_TRUSTSTORE and CMPI_DCAS_TRUSTSTORE_PASSWORD, and the type pkcs12 will be assumed when these deprecated parameters are used. |
|
|
To use the DCAS HCM plug-in, you must configure the DCAS. For information about configuring the DCAS, refer to documentation for z/OS V1R4.0 Communications Server at http://publibz.boulder.ibm.com/cgi-bin/bookmgr_OS390/Shelves/F1A1BK33, specifically the z/OS V1R4.0 Communications Server IP Configuration Reference (publication number SC31-8776-03) and the z/OS V1R4.0 Communications Server IP Configuration Guide (publication number SC31-8775-02). Also refer to the z/OS V1R4 APAR PQ74457 for information about how to configure the DCAS to function with Web Express Logon. |
|
|
For non-Certificate-based Web Express Logon, use DCAS.xml located in the WAR file as a reference for adding parameters when editing the web.xml file. For Certificate-based Web Express Logon, use DCASELF.xml as a reference. |
Add the following HCM database parameters to allow the client to connect to the DCAS securely:
Code example:
<init-param>
<param-name>CMPI_DCAS_KEYRING_FILE</param-name>
<param-value>C:\Program Files\IBM\HostOnDemand\HOD\HODDCAS.p12
</param-value>
</init-param>
|
|
This parameter should be encrypted using the password encryption tool. It is decrypted by the HCM 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_DCAS_KEYRING_PASSWORD</param-name> <param-value>45ie8WciVu</param-value> </init-param>
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.
|
|
The following parameters are not used for Certificate-based
Web Express Logon:
|
Code example:
<init-param> <param-name>CMPI_DCAS_DB_ADDRESS</param-name> <param-value>jdbc:db2://dtagw.raleigh.ibm.com:6789/HODSSO </param-value> </init-param>
Code example:
<init-param> <param-name>CMPI_DCAS_DB_NET_DRIVER</param-name> <param-value>COM.ibm.db2.jdbc.net.DB2Driver</param-value> </init-param>
Code example:
<init-param> <param-name>CMPI_DCAS_DB_USERID</param-name> <param-value>admin</param-value> </init-param>
|
|
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_DCAS_DB_PASSWORD</param-name> <param-value>tuBu9v8lHiJi1jt08UgHzA==</param-value> </init-param>
Code example:
<init-param> <param-name>CMPI_DCAS_DB_TABLE</param-name> <param-value>HACP</param-value> </init-param>
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.
|
|
The following parameters are not used for Certificate-based
Web Express Logon:
|
Code example:
<init-param> <param-name>CMPI_DCAS_DB_NETID_COL_NAME</param-name> <param-value>NETWORKID</param-value> </init-param>
Code example:
<init-param> <param-name>CMPI_DCAS_DB_HOSTADDR_COL_NAME</param-name> <param-value>HOSTADDRESS</param-value> </init-param>
Code example:
<init-param> <param-name>CMPI_DCAS_DB_HOSTAPP_COL_NAME</param-name> <param-value>APPLICATIONID</param-value> </init-param>
Code example:
<init-param> <param-name>CMPI_DCAS_DB_HOSTID_COL_NAME</param-name> <param-value>HOSTID</param-value> </init-param>
Code example:
<init-param> <param-name>CMPI_DCAS_USE_NETID_AS_HOSTID</param-name> <param-value>False</param-value> </init-param>
Unlike the previous set of DCAS parameters, the following parameters are optional. Which of these parameters you add to the web.ml file depends on your environment and your objectives as an administrator:
Code example:
<init-param> <param-name>CMPI_DCAS_TRACE_LEVEL</param-name> <param-value>3</param-value> </init-param>
Code example:
<init-param> <param-name>CMPI_DCAS_HOST_PORT</param-name> <param-value>8990</param-value> </init-param>
Code example:
<init-param> <param-name>CMPI_DCAS_USE_WELLKNOWN_KEYS</param-name> <param-value>true</param-value> </init-param>
|
|
This password should be encrypted using the encrypt password tool. For more information about the password encryption tool, refer to Appendix C. Password encryption tool. |
Code example:
<init-param> <param-name>CMPI_DCAS_WELLKNOWN_PASSWORD</param-name> <param-value>tuBu9v8lHiJi1jt08UgHzA==</param-value> </init-param>
Code example:
<init-param> <param-name>CMPI_DCAS_VERIFY_SERVER_NAME</param-name> <param-value>false</param-value> </init-param>
Code example:
<init-param> <param-name>CMPI_DCAS_REQUEST_TIMEOUT</param-name> <param-value>50000</param-value> </init-param>
|
|
The CMPI_DCAS_DB_PRESERVE_WHITESPACE and CMPI_DCAS_DB_CASE_SENSITIVE parameters are not used for Certificate-based Web Express Logon. |
Code example:
<init-param> <param-name>CMPI_DCAS_DB_PRESERVE_WHITESPACE</param-name> <param-value>false</param-value> </init-param>
Code example:
<init-param> <param-name>CMPI_DCAS_DB_CASE_SENSITIVE</param-name> <param-value>false</param-value> </init-param>
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.
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, for example, HODDCAS.p12. To create the file, use the Host On-Demand Certificate Management GUI on Windows and AIX platforms, or use a P12 keyring tool for other platforms. 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.
|
|
For more information about creating this key database file, refer to the Planning, Installing, and Configuring Host On-Demand guide, which is located in the Host On-Demand Information Center at Start > Programs > IBM WebSphere Host On-Demand > Information Center or on the Web at http://publib.boulder.ibm.com/infocenter/hod9help. |
To create a keyring database called HODDCAS.p12 file that will be specified in the CMPI_DCAS_KEYRING_FILE parameter in your web.xml file, take the following steps on a Windows machine:
|
|
You may choose a different name and location, if you prefer. |
|
|
This step only applies to Certificate-based Web Express Logon. If you are not using client certificates to authenticate users to a secure Web server, skip to the next step. |
For Java 2 clients, if the Web Server's certificate is self-signed or has not been issued by a trusted Certificate Authority (CA), you must add the Web server's certificate to the Java keyring in order to for clients to make secure HTTPS connections to the Web server. This is not required for Java 1 clients.
To add the certificate to the keyring for Java 2 clients, take the following steps:
C:\Program Files\IBM\Java14\jre\bin>keytool -import -alias "HOD HTTP Server" -file httphodnotnet.der -keystore ..\lib\security\cacerts -storepass changeit
Owner: CN=hodnotnet.raleigh.ibm.com, OU=Test, O=HACP, L=Chapel Hill, ST=NC, POST ALCODE=27514, C=US Issuer: CN=hodnotnet.raleigh.ibm.com, OU=Test, O=HACP, L=Chapel Hill, ST=NC, POS TALCODE=27514, C=US Serial number: 40a27eaf Valid from: Tue May 11 15:44:47 EDT 2004 until: Thu May 12 15:44:47 EDT 2005 Certificate fingerprints: MD5: 97:A9:31:88:4E:DC:77:08:C2:1D:1E:22:79:E8:4C:E8 SHA1: 16:26:88:91:67:4D:71:FD:2A:D4:9B:47:0C:96:07:C3:8D:3F:CC:37 Trust this certificate? [no]: yes Certificate was added to keystore
-Djavax.net.ssl.keyStore=<C:\path\cert_name.pfx> -Djavax.net.ssl.keyStorePassword= <certficate password> -Djavax.net.ssl.keyStoreType=pkcs12
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:
|
|
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. |
Take the following steps to configure your Host On-Demand session to use Web Express Logon.
|
|
You may also open session properties by right-clicking a session icon and selecting Properties. |
<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.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 11) and click Actions > Start.
For details about how to record the Web Express Logon macro, refer to Appendix A. Recording the Web Express Logon macro.
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:
Congratulations! You have taken all the necessary steps to implement Web Express Logon in a z/OS and DCAS 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.
In order to implement macro-based automation in a vault-style environment, you must configure your network security application and create your HCM database. For details about these steps, refer to the Web Express Logon for Host On-Demand white paper, located at
ftp://ftp.software.ibm.com/software/ network/hostondemand/library/whitepapers/wel2.pdf
.
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. |
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.
The three WAR files are located in the cdimage\apps\wel subdirectory. Choose the one that matches your network security application:
|
|
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:
In this step, you will become familiar with the three default INIT parameters in the web.xml file.
Code example:
<init-param> <param-name>CMPICredentialMappers</param-name> <param-value>echo</param-value> </init-param>
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. |
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 V5, 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>
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.
<init-param> <param-name>CMPICredentialMappers</param-name> <param-value>CMPIVaultPlugin</param-value> </init-param>
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. |
| 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:
| 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 |
<init-param> <param-name>CMPIVaultPlugin</param-name> <param-value>com.ibm.eNetwork.security.sso.cms.CMPIVault, AuthType_All, * </param-value> </init-param>
Add the following two optional debugging parameters to help you troubleshoot:
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>
Code example:
<init-param> <param-name>CMPI_CMS_TRACE_LEVEL</param-name> <param-value>3</param-value> </init-param>
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.
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>
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>
Code example:
<init-param> <param-name>CMPI_VAULT_DB_USERID</param-name> <param-value>admin</param-value> </init-param>
|
|
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>
Code example:
<init-param> <param-name>CMPI_VAULT_DB_TABLE</param-name> <param-value>HACP</param-value> </init-param>
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.
Code example:
<init-param> <param-name>CMPI_VAULT_DB_NETID_COL_NAME</param-name> <param-value>NETWORKID</param-value> </init-param>
Code example:
<init-param> <param-name>CMPI_VAULT_DB_HOSTADDR_COL_NAME</param-name> <param-value>HOSTADDRESS</param-value> </init-param>
Code example:
<init-param> <param-name>CMPI_VAULT_DB_HOSTADDR_COL_NAME</param-name> <param-value>HOSTADDRESS</param-value> </init-param>
Code example:
<init-param> <param-name>CMPI_VAULT_DB_HOSTAPP_COL_NAME</param-name> <param-value>APPLICATIONID</param-value> </init-param>
Code example:
<init-param> <param-name>CMPI_VAULT_DB_HOSTID_COL_NAME</param-name> <param-value>HOSTID</param-value> </init-param>
Code example:
<init-param> <param-name>CMPI_VAULT_DB_HOSTPW_COL_NAME</param-name> <param-value>PASSWORD</param-value> </init-param>
Unlike the previous set of Vault parameters, the following parameters are optional. Which of these parameters you add to the web.ml file depends on your environment and your objectives as an administrator:
Code example:
<init-param> <param-name>CMPI_VAULT_TRACE_LEVEL</param-name> <param-value>3</param-value> </init-param>
Code example:
<init-param> <param-name>CMPI_VAULT_DB_PRESERVE_WHITESPACE</param-name> <param-value>false</param-value> </init-param>
Code example:
<init-param> <param-name>CMPI_VAULT_DB_CASE_SENSITIVE</param-name> <param-value>false</param-value> </init-param>
Once you save the WAR file with your edits, you are ready to deploy