Before using this information and the product it supports, read the information in Appendix G. Notices.
This edition applies to Version 14.0 of IBM® Rational 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.
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 made available starting with 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.
Starting from Version 9, Host On-Demand 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.
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 or OS/400 (V5R4 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 or OS/400 (V5R4 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. . |
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. . |
|
|
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 Rational Host On-Demand > Information Center or on the web at http://www-01.ibm.com/support/knowledgecenter/SSS9FA_14.0.0/com.ibm.hod.doc/WebSphereHOD.htm. |
|
|
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 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>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.xml 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 Rational Host On-Demand > Information Center or on the Web at http://www-01.ibm.com/support/knowledgecenter/SSS9FA_11.0.0/com.ibm.hod.doc/WebSphereHOD.htm. |
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.
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 changeitOwner: 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=pkcs12The 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>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.
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 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>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.xml 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 the servlet to the Web server. Refer to your Web server application's documentation for details of how to deploy the servlet.
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>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.
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 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.
In order to implement macro-based automation in a Portal Server environment, you must configure your Host On-Demand session to run as a portlet in the IBM WebSphere Portal Server space. You must also configure the Portal Server's Credential Vault Service with the appropriate host credential information, including the user's password, application ID, and host address. In this environment, the Portal Server's Credential Vault is similar to Host Credential Mapper (HCM) Vault database. For details about how to configure Portal Server's Credential Vault, refer to the Web Express Logon for Host On-Demand white paper, located at .
|
|
The Portal Credential Vault cannot be used as the HCM database for RACF passticket generation. |
The following steps show you how to use the Deployment Wizard to create your Host On-Demand portlet, configure your host session, and record your login macro.
|
|
Steps 1-5 are designed for administrators who are planning to use the Deployment Wizard to create the portlet, 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 portlet first and then configure your session and create your macro later. |
The Host On-Demand Deployment Wizard allows you to create a portlet to be launched within a Portal Server page. Host On-Demand portlets are saved as Web Archive (WAR) files.
To begin creating your portlet 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.
|
|
The User Identity Type field is not used when using the Portal Server Credential Vault Service. |
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 25) 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 portlet file using the Deployment Wizard. To finish creating the file, take the following steps:
|
|
Do not select Web Start client as your client type when creating a Host On-Demand portlet. |
|
|
Any information that you provide about the Portal Server Credential Vault is only used if you have left the Credential Mapper Server Address field in the Express Logon window of session properties blank. |
|
|
Host On-Demand provides a separate portlet for manipulating user IDs and passwords stored in administrative slots. The WAR file (PasswordEditor.war) is stored in the portal sub-directory of Host On-Demand published directory. Step 5: Using a custom portlet to manage user credentials describes the usage of the utility. Host On-Demand does not provide any tools for manipulating other types of valut slots (system and shared). |
Host On-Demand provides a customized portlet that can be placed on a user page and allows them to update their own credentials in administrative slots. This is particularly useful when a user is required to change their password because it has expired and they no longer remember the current password which is needed to create new credentials.
With this custom portlet, users can update their own credentials in the vault. After the password is reset the user can select the modify Slot radio button. Their credentials are retrieved from the credential vault and presented through the portlet edit mode. The host user ID and two password fields are populated with the current values. The user can now change the credentials by entering the new credentials into the respective fields and clicking Save.
Congratulations! You have taken all the necessary steps to implement Web Express Logon in a Portal Server 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.
The way in which you implement connection-based automation depends on your environment. In this section, we focus on the following two environments:
|
|
This document does not provide details for configuring other applications to work with Host On-Demand Web Express Logon. . |
Unlike macro-based automation, connection-based automation does not require the use of a Credential Mapper Servlet (CMS), a login macro, the Network Security plug-in, nor the Host Credential Mapper (HCM). Instead, it extends the existing single sign-on capability of iSeries environments that meet the following criteria:
You must configure your iSeries environment to use single sign-on capability in order to implement connection-based logon automation.
The iSeries environment provides single sign-on capability by working in conjunction with Kerberos-based network authentication 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 host session login screen.
Both EIM technology and Kerberos are available with i5/OS V5R4 or later operating systems. EIM is an IBM infrastructure technology that allows you to manage multiple user identities and user registries easily and inexpensively while maintaining secure authentication and authorization. This architecture describes the relationships between individuals or entities in an enterprise and the many identities that represent them within the enterprise. Kerberos, on the other hand, is a network authentication protocol that identifies and authenticates users who request to log on to a network. Together, EIM and Kerberos provide single sign-on capability.
Although this document does not instruct you how to configure your iSeries environment for single sign-on capability, the following resources are available to help you:
Once you have configured your iSeries environment to use single sign-on capability, you are ready to configure Host On-Demand to extend this single sign-on capability. To accomplish this, take the following two steps:
The Host On-Demand Deployment Wizard allows you to specify how sessions are defined and managed. You can choose from three different configuration models:
When using the Configuration server-based model and a network security application such as Tivoli Access Manager, you may be accessing your Host On-Demand pages via a URL such as https://server_name/junction_name/HOD/myhodpage.html, where server_name is the name of the machine running Tivoli Access Manager and junction_name is the junction that you create to point to your Host On-Demand server machine and your HTTP server's port number. If this is the case, Host On-Demand will try to contact the Host On-Demand Service Manager to get your user, group, and session information at the server_name rather than at the junction_name. To remedy this situation, edit the config.properties file found in the HOD directory of your Host On-Demand install directory (\Program Files\IBM\HostOnDemand\HOD\config.properties) by adding this line at the end of the file content:
ConfigServer=myhodserver.ibm.comwhere myhodserver is the machine you are pointing to with the junction_name.
Configure your 5250 session properties to use a Kerberos passticket by taking the following steps:
|
|
If Use Kerberos Passticket is selected, the User Identity Type and Credential Mapper Server fields become disabled. This is because they are not required for connection-based automation. |
Once you have taken the above steps and configured your iSeries host for Kerberos authentication, you will have taken all the necessary steps to implement Web Express Logon in an i5/OS or OS/400 and Kerberos 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.
|
|
Web Express Logon is also designed to work in FTP environments that use Portal Server. To configure this environment, follow steps 1 and 2 in this chapter and then steps 1, 2 and 4 in the Configuring macro-based automation in a Portal Server environment chapter. Because FTP logon is based on connection-based automation, you will not need to create a Web Express Logon macro; however, you must configure the Portal Server Credential Vault as you would with macro-based automation in a Portal Server environment. . |
In order to implement connection-based automation in an FTP login environment, you must configure your network security application and create your HCM database. .
In this document, we show you how to edit and deploy the CMS provided with Host On-Demand and use the Deployment Wizard to create your HTML file and configure your host session.
|
|
Steps 3-5 are designed for administrators who are planning to use the Deployment Wizard to create the HTML file and configure the FTP session to use Web Express Logon all in one sitting. However, you may decide to create your HTML file first and then configure your session 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 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>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 HCMs 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 6:
|
|
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 7 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 two of these parameters (network ID and host address), 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 vault-style database to request the password.
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 the servlet to the Web server. Refer to your Web server application's documentation for details of how to deploy the servlet.
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>|
|
Notice the Logon option in the left pane of the FTP Host Sessions window. On this window, be sure to leave the User ID and Password fields blank. If you enter a User ID and Password, Host On-Demand will ignore the settings on the Express Logon window. |
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 an FTP login 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.
If you decide to customize Web Express Logon, you may take either of the following two approaches -- (1) customize the existing CMS or (2) replace the entire CMS with your own custom version. Although the first approach requires some J2EE knowledge, it is easier to implement than the second approach and does not require experience creating servlets.
The CMS is the core of the credential-mapping framework. It 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. It accomplishes these tasks through credential mapper Java classes called plug-ins. Web Express Logon provides two Network Security plug-ins (one for Tivoli Access Manager and one for Siteminder) to perform the request part of the process and three Host Credential plug-ins (two for DCAS and one for Vault) to perform the response part.
The Network Security plug-in retrieves the user's credentials from the network security application after the user has made an HTTPS request to the CMS. It identifies the user by way of the network user ID and then passes it on to the appropriate Host Credential plug-in. The Host Credential plug-in then determines the host user ID and acquires the host access credentials.
If you take the first approach, you can create a Network Security plug-ins and/or a HCM plug-in. For example, if your network security application is not one of three applications supported by Web Express Logon, you can create a Network Security plug-in to meet the requirements of your application. Also, if you want to use an LDAP directory as your HCM database instead of a JDBC database such as IBM DB2, for example, you can create your own HCM plug-in.
This document does not describe how to create a servlet, but the following are resources available to help you:
If you decide to replace the entire CMS provided with Host On-Demand, you will need to use an HTTP parameter for requests and XML-formatted data for responses. Parameters are supplied to the CMS servlet via an HTTP request, and the response information is encapsulated into an XML-formatted object and returned to the caller.
When Host On-Demand makes a request of the CMS, it applies the appropriate HTTP parameters to this request. This helps determine the needs of the request. Since it must be an HTTP request, the CMS request interface is built around a standard HTTP-style query. Following the HTTPS protocol and server address is the query character, a question mark, and then a list of keys and values. These keys and values are separated by the ampersand symbol. Within each key and value pair, the key and value are separated by the symbol for equality. A sample query may look like the following example:
https://www.ibm.com/authserver/servlet/cms?operation=1
&destination=www.ibm.com/somehost&appid=tpf
&authtype=AuthType_3270HostTable 5 is a list of available keys:
| Key | Possible value |
|
'1' -- Credential Mapping Request |
|
This is the destination for which the credentials are being requested. |
|
This is the host application ID for which the credentials are being requested. |
|
This is the type of authentication credentials being requested (available authentication types are defined in Table 2). |
|
This optional value will supply the user's identification, based on the local operating system or the Portal user ID. For now, the local ID solution is supported only on the Windows operating system. |
The CMS returns its response to the client in XML format in an effort to make the response information structured and extensible. This XML format provides a good base for allowing structured access to the return data today and flexibility for expansion and improvement in the future. The following XML schema defines the format of the XML document:
<schema targetNamespace=""
xmlns="http://www.w3.org/2001/XMLSchema">
<element name="hod-sso-credential" type="hod-sso-credentialType" />
<complexType name="hod-sso-credentialType">
<sequence>
<element name="userid" type="string" />
<element name="password" type="string" />
<element name="status" type="string" />
</sequence>
<attribute name="version" type="string" />
</complexType>
</schema>Based on the above schema, the following code is a sample of the XML return document that is streamed over the HTTPS connection:
<?xml version="1.0"?>
<hod-sso-credential version="1.0" >
<userid>&^$#^&</userid>
<password>&^$#^&</password>
<status>0</status>
</hod-sso-credential>In the above code, the user ID and password elements return garbage characters because they are encrypted. Host On-Demand includes an object called com.ibm.eNetwork.security.sso.PasswordCipher to accomplish this. It contains the following two methods:
The status element provides the status of the return value. If the credential mapper query fails for any reason, this field reports that failure to the client. Failure codes are defined in the SSOConstants class, which serves as a static repository of related SSO static information. The following table contains the status code definitions:
| Status code | Description |
| 0 | Success |
| 1 | Unknown status code |
| 2 | Suitable HCM plug-in not found |
| 3 | Invalid network user ID |
| 4 | Invalid application ID |
| 5 | Invalid server address |
| 6 | Database connection error |
| 7 | User ID not found in database |
| 8 | Exception |
| 9 | Invalid user ID |
| 10 | Passticket error |
| 11 | Timeout |
| 12 | Unexpected DCAS return code |
| 13 | API not supported |
| 14 | Bad URL |
| 15 | Unable to parse response |
| 16 | Local user ID not available |
| 17 | Duplicate XML tags |
| 18 | An exception occurred while processing the credential request |
| 19 | Network Security plug-in is not defined to the CMS |
| 20 | Portal ID not available |
| 21 | A matching user ID not found in Portal Vault |
You can create custom Network Security and HCM plug-ins to customize the existing CMS. The CMS relies on these plug-ins to provide the user's network ID and host credentials. The CMS interacts with these plug-ins via the following three Java interfaces:
The CMInterface interface contains the following methods:
The following methods are needed for plug-in identification and selection.
The CMRequest object is used by CMS to encapsulate all necessary parameters for a plug-in request. The CMRequest interface contains the following members and methods:
Members:
Methods
The CMResponse object encapulates all relevant information needed by the CMS for the request made of a plug-in. The CMResponse interface contains the following members and methods:
Members:
Methods:
The Network Security and HCM plug-ins are Java classes that implement the CMInterface interface. The CMS makes calls to your plug-ins via the APIs described earlier.
Network Security plug-in: Host On-Demand provides two Network Security plug-ins, one for Tivoli Access Manager and one for Netegrity Siteminder. If you decide not to use either of these, you may create your own plug-in.
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 details of how to acquire the network ID is specific to your network security application. Refer to your network security documentation for more information.
HCM plug-in: Host On-Demand provides three HCM plug-ins, two for DCAS and one for Vault. If you decide not to use either of these, you may create your own plug-in. For sample HCM plug-in code, refer to Appendix D. Sample HCM plug-in.
The primary function of the HCM plug-in is to take the user's network ID or user's certificate (and perhaps the application ID) and obtain the appropriate host credentials. In Web Express Logon's implementation, users' network IDs are mapped to their host IDs by way of a JDBC-accessible database. However, you may wish to do this by another means, such as LDAP. For this reason, you may want to write your own HCM plug-in. In our DCAS/JDBC plug-in, we automate 3270 application logins by associating users' network IDs to their host IDs. Then, the host IDs and application IDs are used to obtain a RACF-generated passticket. This passticket is then used to sign the user on to the host. In your environment, you may not want to use the JDBC association aspect of our plug-in. For this reason, we have provided a DCAS API that you can use to develop your own custom plug-ins. This API provides access to RACF-generated passtickets.
The DCAS API object (DCASClient) encapsulates the Passticket requests:
The DCAS API client contains the following members:
Members:
The DCAS API client contains the following methods:
Methods:
Web Express Logon depends on a number of independent processes working together to function properly. Some of these processes run on the Host On-Demand client while others run on other host systems. When one or more of these processes break down, you must be able to determine which process is causing the problem in order to resolve it appropriately. This portion of the document is devoted to that purpose.
If you have problems with Web Express Logon, analyze the type of results you receive and any accompanying informational messages. Some of these informational messages are included as part of the Host On-Demand client by way of an interactive panel, and/or they may be part of a server-based log.
Assuming that Web Express Logon is not functioning properly (that is, you are not logged in a host emulation session), ask yourself the following questions:
When an unexpected problem occurs during the Web Express Logon process, the Host On-Demand client provides information about the problem to the user by displaying a panel with an informational message. Each of these messages contain an error code that you can use as a unique identifier for the problem that is occurring. The following is a list of all Web Express Logon messages for the Host On-Demand client.
The following are the primary server-side messages:
<init-param>
<param-name>CMPICredentialMappers</param-name>
<param-value>vault</param-value>
</init-param><init-param>
<param-name>vault</param-name>
<param-value>com.ibm.eNetwork.security.sso.cms.CMPIVault,
AuthType_3270Host,*</param-value>
</init-param><init-param>
<param-name>CMPICredentialMappers</param-name>
<param-value>YourCredentialMapperName(s)</param-value>
</init-param><init-param>
<param-name>vault</param-name>
<param-value>com.ibm.eNetwork.security.sso.cms.CMPIVault,
AuthType_3270Host,*</param-value>
</init-param>The following are the primary DCAS error messages:
Take the following steps to record the logon automation macro:
The alternate start screen is a screen from which the user might want to play the macro to log on to the application. If the application has more than one possible start screen, you should identify it during the recording process so that the macro can be played from that screen. For example, the logon process might begin from the USSMSG10 screen or the application logon screen. You may start the logon macro from either the start screen or the alternate start screen. You can designate only one screen as an alternate start screen. There is no alternate start screen after the screen that contains the user ID.
|
|
Click Current only if you will not be using this screen for multiple applications and the location of the user ID field never changes. |
|
|
Click Current only if you will not be using this screen for multiple applications and the location of the password field never changes. |
When creating an HTML file using the Configuration server-based model in the Deployment Wizard, the next window after the Configuration Model window is the Logon Type window. On this window, you are presented with the following three options:
|
|
Note that you must have your user profiles already set up on your Host
On-Demand configuration server. If you do not have your user profiles set
up and you attempt to launch the HTML file, you will get the following error
message:
|
<init-param>
<param-name>CMPICredentialMappers</param-name>
<param-value>CMPIDCASPlugin, CMPIVaultPlugin,
CMPIConfigServer_ </param-value>
</init-param><init-param>
<param-name>CMPIConfigServer_</param-name>
<param-value>com.ibm.eNetwork.security.sso.cms.CMPIVault,
AuthType_ConfigServer, *</param-value>
</init-param>When using the Configuration server-based model and a network security application such as Tivoli Access Manager, you may be accessing your Host On-Demand pages via a URL such as https://server_name/junction_name/HOD/myhodpage.html, where server_name is the name of the machine running Tivoli Access Manager and junction_name is the junction that you create to point to your Host On-Demand server machine and your HTTP server's port number. If this is the case, Host On-Demand will try to contact the Host On-Demand Service Manager to get your user, group, and session information at the server_name rather than at the junction_name. To remedy this situation, edit the config.properties file found in the HOD directory of your Host On-Demand install directory (\Program Files\IBM\HostOnDemand\HOD\config.properties) by adding this line at the end of the file content:
ConfigServer=myhodserver.ibm.com
where myhodserver is the machine you are pointing to with the junction_name.
Host On-Demand provides a password encryption tool so you can encrypt your passwords for added security. The tool is a command-line tool that allows you to generate a file that stores the encrypted password, which you must then copy to the appropriate place in the web.xml file. The Host Credential plug-in decrypts the password before using it.
If you create a custom Host Credential plug-in, the plug-in should use the com.ibm.eNetwork.security.PasswordCipher object to decrypt the password. The CLASS file for this object is included in WAR file. Refer to XML data response object for a description of the encrypt and decrypt methods.
Using a DOS prompt, change the current directory to the Host On-Demand's bin directory and type the following command:
encrypt <password> [filename]where password is the password to be encrypted and filename is the name of the file that you want to store the encrypted password. The default filename is password.txt.
Issue the following command:
cd your_install_dir
Java -classpath .;your_install_dir\lib\sm.zip \
com.ibm.eNetwork.security.sso.cms.tools.Encrypt <password> [filename]where your_install_directory is your Host On-Demand installation directory, password is the password to be encrypted, and filename is the name of the file that you want to store the encrypted password. The default filename is password.txt.
You can create your own Host Credential Mapper (HCM) plug-in if those provided with Web Express Logon do not suit your needs. To use your own custom plug-in, you must write the plug-in code and update the web.xml file so the servlet can function with your plug-in.
The following two sections provide more details about writing your own plug-in and updating the web.xml file.
Here, we provide pseudocode from a sample HCM plug-in called CMPISample. The purpose of this sample is to demonstrate the implementation of CMInterface and some of the functions your plug-in will need to provide. CMPISample is designed to read the host credentials from a database that you specify.
|
|
We recommend that you use the provided CMPIVault class for this function whenever possible. You should only create a custom plug-in like CMPISample if one of the plug-ins provided with Host On-Demand does not suit your needs. |
package com.mycompany;
import java.util.Properties;
import java.util.Enumeration;
import com.ibm.eNetwork.security.sso.*;
import com.ibm.eNetwork.security.sso.cms.CMInterface;
public class CMPISample implements CMInterface {
private static final String className
= "com.mycompany.CMPISample";
//The following strings match the parameters contained in the
web.xml file (see Sample.xml)
private static final String DB_ADDRESS = "CMPI_SAMPLE_DB_ADDRESS";
private static final String DB_TABLE = "CMPI_SAMPLE_DB_TABLE";
private static final String TRACE_LEVEL = "CMPI_SAMPLE_TRACE_LEVEL";
private static final int DEFAULT_TRACE_LEVEL = Ras.TRACE_NONE;
//TODO: Add all other parameters needed, such as the database
driver, column names, ID and PW, etc
private String dbAddress; //url string that provides the
address of the database
private String dbTable; //database table to use for the query
private int traceLevel; //trace level
private String logFile; //trace log file
//TODO: Add fields for all other parameters
private Properties pInit = null;
private String cmID = null;
//TODO: Add any other needed fields, such as the database connection
private boolean initOK = true;
/*************************************************************************
* Called to initialize the Sample Plug-in
*
* @param pInit All of the CredMapper servlet parameters.
* These parameters are specified in the web.xml file.
* @param id The plug-in being initialized.
* @return An int value which indicates the status of the initialization.
*************************************************************************/
public int Init(Properties pInit, String id)
{
final String methodName = "Init";
initOK = true;
this.pInit = pInit;
this.cmID = id;
// For debug purposes, add a RAS implementor which logs to stdout and file.
String traceStr = getProperty(TRACE_LEVEL, false); // Optional
if (traceStr != null) traceLevel = Integer.parseInt(traceStr);
else traceLevel = DEFAULT_TRACE_LEVEL;
String logFile = getProperty(SSOConstants.TRACE_LOG_FILE, false); // Optional
if (logFile == null) logFile = SSOConstants.DEFAULT_TRACE_LOG_FILE;
SampleRas sampleRas = new SampleRas(logFile); //SampleRas classs not provided.
This class implements RasInterface
//and writes to logFile and stdout
if ((traceLevel > Ras.TRACE_NONE) &&
(Ras.hasNoImplementations())) {
Ras.addRasImplementation(sampleRas);
}
if (traceLevel >= Ras.TRACE_MINIMUM) {
//Trace all parameters and their values
String parameters = "";
//TODO: Loop through pInit and build parameters string
Ras.traceEntry(className, methodName, new String [] {
"pInit = {\n\t" + parameters + "\n\t}",
"id = " + id
} );
}
/*************************************************************************
* Get Sample parameters from the properties object
* Try to retrieve the value of all parameters and return an error
* if one or more than one parameter is bad.
*************************************************************************/
dbAddress = getProperty(DB_ADDRESS, true); //Required
dbTable = getProperty(DB_TABLE, true); //Required
//TODO: Read the rest of the properties here
if (!initOK) return SSOConstants.SSO_INVALID_PARAMETER;
//TODO: Check to see if the network database driver exists here,
and establish a connection with the database
if (traceLevel >= Ras.TRACE_MINIMUM)
Ras.traceExit(className, methodName);
return SSOConstants.SSO_SUCCESS;
}
/*************************************************************************
* Close the Database connection
*************************************************************************/
public void Destroy() {
final String methodName = "Destroy";
if (traceLevel >= Ras.TRACE_MINIMUM)
Ras.traceEntry(className, methodName);
//TODO: Close the database connection
if (traceLevel >= Ras.TRACE_MINIMUM) //@ry3
Ras.traceExit(className, methodName);
}
public CMResponse CMSGetUserCredentials(CMRequest cmreq)
{
final String methodName = "CMSGetUserCredentials";
if (traceLevel >= Ras.TRACE_MINIMUM)
Ras.traceEntry(className, methodName, new String [] {
"Network ID = " + cmreq.getID(),
"Application ID = " + cmreq.getHostApplID(),
"Destination Addr = " + cmreq.getHostDestination()
} );
String netID = cmreq.getID();
String hostApp = cmreq.getHostApplID();
String hostDest = cmreq.getHostDestination();
CMResponse resp = new CMResponse();
String retid = null;
String retpw = null;
//TODO: Build query statement with netID, hostApp, hostDest, and
the values provided in web.xml (table name, column names, etc)
//TODO: Execute the statement and set retid and retpw with the results
if (retid == null) {
if (traceLevel >= Ras.TRACE_MINIMUM)
Ras.logMessage(Ras.MSG_ERROR, className, methodName,
"DB_USER_ID_ERROR", netID);
resp.setStatus(SSOConstants.SSO_CMR_USER_ID_NOT_FOUND_IN_DB);
}
else {
resp.setID(retid);
resp.setPassword(retpw);
resp.setStatus(SSOConstants.SSO_CMR_SUCCESS);
}
if (traceLevel >= Ras.TRACE_MINIMUM) //ry3
Ras.traceExit(className, methodName);
return resp;
}
/*************************************************************************
* Retrieve the property value
*************************************************************************/
private String getProperty(String propName, boolean required) //@d01c
{
String value = null;
//TODO: Retrieve the specified property from pInit
return value;
}
public String getName() {return "Sample Credential Mapper";}
public String getDescription() {return "Retrieves host credentials
from a database";}
public String getAuthor() {return "My Company";}
String strParms[] = { DB_ADDRESS, DB_TABLE, TRACE_LEVEL }; //TODO:
Fill in the rest of the parameters here
public String[] getParameters() {return strParms;}
public Properties getParameterInfo(String strParm)
{
Properties p = new Properties();
if (DB_ADDRESS.equals(strParm))
{
p.put(CMInterface.cmiRequired, "true");
}
else if (DB_TABLE.equals(strParm))
{
p.put(CMInterface.cmiRequired, "true");
}
else if (TRACE_LEVEL.equals(strParm))
{
p.put(CMInterface.cmiRequired, "false");
p.put(CMInterface.cmiDefaultValue, Integer.toString(Ras.TRACE_NONE));
}
//TODO: Add ifs for the rest of the parameters
return p;
}
} //end class CMPIVaultIn order for CMS to work with your custom plug-in, you will need to update the web.xml file with the appropriate parameters. Use the following pseudocode as an example:
<init-param>
<param-name>CMPICredentialMappers</param-name>
<param-value>CMPISamplePlugin</param-value>
</init-param>
<!-- //// Optional Trace parameters //// -->
<init-param>
<param-name>CMPI_TRACE_LOG_FILE</param-name>
<param-value>C:\Program Files\IBM\HostOnDemand\HOD\HODWEL.log</param-value>
<description>Credential Mapper Log file name.</description>
</init-param>
<init-param>
<param-name>CMPI_CMS_TRACE_LEVEL</param-name>
<param-value>2</param-value>
<description>CMS Trace level. 0=none, 1=min, 2=normal, 3=max.</description>
</init-param>
<init-param>
<param-name>CMPI_SAMPLE_TRACE_LEVEL</param-name>
<param-value>2</param-value>
<description>HCM Sample Trace level. 0=none, 1=min, 2=normal, 3=max.</description>
</init-param>
<!-- //// End of Optional Trace parameters //// -->
<!-- // Configuration parameters needed for HCM Sample Plug-in /// -->
<!-- //// Required Parameters //// -->
<!-- The parameter name must match the value specified in -->
<!-- CMPICredentialMappers parameter. -->
<init-param>
<param-name>CMPISamplePlugin</param-name>
<param-value>com.mycompany.CMPISample,
AuthType_3270Host,
*
</param-value>
</init-param>
<!-- //// The Network ID to Host User ID Database Parameters //// -->
<init-param>
<param-name>CMPI_SAMPLE_DB_ADDRESS</param-name>
<param-value>jdbc:odbc:my_db_url</param-value>
<description>URL string that provides the
address of the database.</description>
</init-param>
<init-param>
<param-name>CMPI_SAMPLE_DB_TABLE</param-name>
<param-value>NetIDToHostID</param-value>
<description>The table to be used for querying the database.</description>
</init-param>
<!-- //// TODO: All other parameters added to CMPISample must
also be configured here. See vault.xml for examples. //// -->
<!-- //// End of Network ID to Host User ID Database Parameters //// -->
<!-- //// End of Required Parameters //// -->
<!-- // End of Configuration parameters needed for HCM Sample Plug-in /// -->
The following terms are used throughout this document:
When editing Credential Mapper Servlet (CMS)-related parameters in the web.xml file for macro-based automation, the parameter value must contain the full class path name of the implementing class, the authentication type to be addressed by the credential mapper, and the host mask.
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 Host Credential Mappers (HCM) the freedom to support multiple authentication types.
A certificate stored in the client's Web browser used to identify the user.
Connection-based automation works in FTP login environments as well as i5/OS or OS/400 environments that support Kerberos network authentication. With this type of automation, the user is authenticated through a telnet negotiation and the host never sends a login screen to authenticate the client. Therefore, connection-based automation does not require the use of a login macro, the Credential Mapper Servlet (CMS), a Network Security plug-in, nor the Host Credential Mapper (HCM).
Credential challenges are the time at which users are prompted to provide IDs and passwords.
For the macro-based automation style of Web Express Logon, the CMS is the core of the credential-mapping framework. It is supplied with Host On-Demand and must be deployed to a Web server or some type of Web application framework. At a high level, it 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 HCM.
DCAS is a TCP/IP server that runs on z/OS and OS/390 platforms. TN3270 servers connect to DCAS using Secure Socket Layer (SSL). The purpose of DCAS is to receive an application ID and a digital certificate from a TN3270 server and then ask RACF to return a valid user ID that has been associated with the certificate and to generate a passticket for the input user ID and application ID.
EIM is an IBM eServer technology that helps you easily manage multiple user registries and user identities in an enterprise. EIM is an architecture for describing the relationships between individuals or entities (like file servers and print servers) in the enterprise and the many identities that represent them within an enterprise. In addition, EIM provides a set of APIs that allow applications to ask questions about these relationships.
When editing CMS-related parameters in the web.xml file for macro-based automation, the parameter value must contain the full class path name of the implementing class, the authentication type to be addressed by the credential mapper, and the host mask.
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 network security or HCM queries. You must place the specified class file 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.
The HCM 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 DCAS and Vault plug-ins provided with Web Express Logon are designed to work with a such a database. Another possibility for a repository is an LDAP directory. However, using LDAP as your HCM requires you to write your own plug-in..
A host ID is the credential used to uniquely identify the user to the host being accessed. In macro-based automation, the host ID is what the Host Credential Mapper returns to the Credential Mapper servlet in order to achieve single sign-on.
When editing CMS-related parameters in the web.xml file for macro-based automation, the parameter value must contain the full class path name of the implementing class, the authentication type to be addressed by the credential mapper, and the 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.
Kerberos is a network authentication protocol that identifies and authenticates users who request to log on to a network. It provides a means of verifying the identities of principals (users) on physically insecure networks. It provides mutual authentication, data integrity, and privacy under the realistic assumption that network traffic is vulnerable to capture, examination, and substitution.
Macro-based automation is for environments of varying host types that are not using Kerberos authentication. As the name implies, it requires you to create a macro to perform logon automation.
In order to use the macro-based automation style of Web Express Logon, you must have a network security application in place. Host On-Demand provides out-of-the-box support for three common network security applications without requiring additional coding: IBM Tivoli Access Manager, Netegrity Siteminder, and Microsoft Active Directory (Windows Domain). If you have a different network security application, you will need to create your own plug-in to work in your environment.
A network ID is the credential that uniquely identifies the user to the network security application. In macro-based automation, the CMS calls upon the Network Security plug-in to acquire the user's network ID from the network security application.
In macro-based automation, the Network Security plug-in acquires the user's network ID from the network security application.
A Portal Server repository where user credentials are stored.
RACF is an IBM security product that protects resources by granting access to only authorized users of protected resources. RACF retains information about the users, resources, and access authorities in profiles on the RACF database and refers to the profiles when deciding which users should be permitted access to protected system resources.
Use the following sources to help you implement Web Express Logon in your environment:
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or region or send inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan, Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, JapanThe following paragraph does not apply to the United Kingdom or any other country or region where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:
Site Counsel
IBM Corporation
2455 South Road
Poughkeepsie, NY 12601-5400
U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.
If you are viewing this information softcopy, the photographs and color illustrations may not appear.
The following terms are trademarks of International Business Machines Corporation in the United States, other countries, or both: IBM
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle Corporation in the United States and other countries.
Microsoft, Windows, and the Windows logo are registered trademarks of Microsoft Corporation.
Other company, product, and service names may be trademarks or service marks of others.