Web Express Logon Tutorial

Back Home Next

 

Step Step 6 of 9: Configure the Credential Mapper Servlet

In this step, you will configure 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 (called a network ID), (2) map the user's network ID to the host ID, and (3) return the host credentials to the client as an XML document.

Host On-Demand provides three CMS WAR files, one for each of the following network security applications:

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 (opens new browser).

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

The web.xml file is the servlet configuration file that you will edit in this step. The other two XML files (DCAS.xml and Vault.xml) are sample files that Host On-Demand provides to help you better understand DCAS and Vault parameters and their values. These two XML files can also serve as a valuable reference when you edit the web.xml file. We also recommend that you use these files as a reference when you edit the web.xml file. Finally, the was.policy file is for IBM WebSphere Application Server only. It contains the required permissions for the CMS when Java 2 security is enabled. For more information, refer to Troubleshooting Web Express Logon (opens new browser)

Take the following steps to begin configuring the CMS:

  1. Locate the WAR file on the Host On-Demand V8 CD.
  2. Edit the CMS-related parameters.
  3. Add optional CMS-related debugging parameters.
  4. Add the required Vault client parameters for the CMPIVaultPlugin.
  5. Add optional Vault client parameters (if desired).
  6. Save the WAR file.

1. Locate the WAR file on the Host On-Demand CD.

With the Host On-Demand V8 CD loaded in the CD drive of your machine, take the following steps to locate the WAR files on the CD.

  1. Click Start > Programs > IBM WebSphere > Application Server v5.0 > Application Assembly Tool.

  2. On the Welcome to the Application Assembly Tool window, click the Existing tab and browse to the apps\wel directory on the Host On-Demand CD.



  3. In the apps\wel directory, you will see three WAR files, one for each of the following network security applications:

    Network security application Corresponding WAR file
    IBM Tivoli Access Manager for e-business V4.1 amcms.war
    Netegrity Siteminder V5.5 smcms.war
    Microsoft Active Directory (Windows Domain) wincms.war

    Highlight the WAR that represents your network security application and press Select. Then select OK.



    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 (opens new browser).

Back to top


2. Edit the CMS-related parameters.

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

  1. In the left panel of the window, expand Web Components > CredMapper and click Initialization Parameters. The three default INIT parameters that you became familiar with in the previous step appear in the top window.



    (a) - (b) describe these default parameters in more detail:

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

    Code example:

    <init-param>
       <param-name>CMPICredentialMappers</param-name>
       <param-value>echo</param-value>
    </init-param>


    b.
    Network Security plug-in: The name of the parameter is CMPINetworkSecurity, and the parameter value is the full path name of the class that handles the CMS interface into the network security application, which is Tivoli Access Manager in this scenario.

    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 XML file (wincms.xml) since the Windows login ID is used as the network ID.


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

    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 PC'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 specified when deploying the CMS, and CredMapper is the name of the CMS itself.

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


    Code example:

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

  2. Highlight the CMPICredentialMappers parameter in the top panel of the window. In the Parameter value field below, change the name of its current value (echo) to the name of your HCM plug-in. In this scenario, the administrator specifies CMPIVaultPlugin as the parameter value because he is using a vault-style database as his HCM plug-in. Optionally provide a description and click Apply to replace the value in the top window.



    Code example:

    <init-param>
       <param-name>CMPICredentialMappers</param-name>
       <param-value>CMPIDCASPlugin</param-value>
    </init-param>

  3. Highlight the echo parameter in the top panel of the window. In the Parameter name field below, replace the current parameter name (echo) with the name of the parameter value that you specified for the HCM plug-in. In this scenario, the administrator changed the parameter name to CMPIVaultPlugin.

    Now, replace the parameter value with a compound value that contains the full class path name of the implementing class, the authentication type to be used by the HCM plug-in, and the host mask. Separate these values with commas. In this scenario, the administrator added com.ibm.eNetwork.security.sso.cms.CMPIVault for the full class path name, AuthType_3270Host for the authentication type, and * for the host mask. Optionally provide a description and click Apply to replace the value in the top window.

    The authentication type for FTP sessions should be either AuthType_FTPPassword or AuthType_All.




    Code example:

    <init-param>
       <param-name>CMPIDCASPlugin</param-name>
       <param-value>com.ibm.eNetwork.security.sso.cms.CMPIDCAS,AuthType_3270Host,*</param-value>
    </init-param>


    The following table provides additional information about full class path name, authentication type, and 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 parameter 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 HCM plug-in 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 and descriptions are listed in the following table:

    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 HCM plug-in. 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. The following table 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

Back to top


3. Add optional CMS-related debugging parameters.

To add new parameters, right-click Initialization Parameters in the left pane of the Application Assembly Tool window and select New. This displays the New Initialization Parameter window.

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

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

Code example:

<init-param>
   <param-name>CMPI_TRACE_LOG_FILE</param-name>
   <param-value>C:\Program Files\IBM\HostOnDemand\HOD\HODWEL.log</param-value>
</init-param>
CMPI_CMS_TRACE_LEVEL
This parameter specifies the trace level for the CMS. The trace messages are logged to the log file specified by CMPI_TRACE_LOG_FILE parameter. Depending on your Web application server, they may or may not be logged to the console. Trace level values include the following:
0 = None: No tracing. This is the default.
1 = Minimum: Trace APIs and parameters, return values, and errors.
2 = Normal: Trace Minimum plus internal APIs and parameters and informational messages.
3 = Maximum: Trace Normal plus Java exceptions.


Code example:


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

Back to top


4. Add the required Vault parameters for the CMPIVaultPlugin.

Adding the required Vault parameters allows the HCM to map the users' network IDs to their host IDs and receive the needed passwords from the vault-style database. The following Vault parameters are required in order for Web Express Logon to function properly. This section is divided into two subsections, A and B.

A. The following parameters contain all the relevant information needed to connect to your HCM, which in this case is a JDBC database table created with IBM DB2. You can either configure access to an existing database or to a newly created one.

The level of security for the database depends on the database vendor. See the documentation for details.


CMPI_VAULT_DB_ADDRESS
This is a URL string that provides the address of the database. An example of this string is jdbc:db2://dtagw.raleigh.ibm.com:6789/HODSSO.

Code example:


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

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

Code example:


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

CMPI_VAULT_DB_USERID
This is the ID of the user account to use when accessing the database. In this case, the user ID is admin.

Code example:


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

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

We strongly recommend that you encrypt this parameter using the password encryption tool provided with Host On-Demand. The tool encrypts the password and then decrypts it so the HCM plug-in can use it. To learn more about how to use this tool, refer to Using the Password Encryption Tool.


Example:

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

CMPI_VAULT_DB_TABLE
This identifies the table to use for the needed query. In this case, the table is called HACP.

Example:


<init-param>
   <param-name>CMPI_VAULT_DB_TABLE</param-name>
   <param-value>HACP
</param-value>
</init-param>
B. The following parameters correspond directly to the column headings that you added to your HCM database table in Step 3: Create the Host Credential Mapper database. Recall that you added the following five column headings, all in uppercase: NETWORKID, HOSTADDRESS, APPLICATIONID, HOSTID, and PASSWORD.

The APPLICATIONID column is not required for FTP sessions.


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 vault-style database to request the password.
CMPI_VAULT_DB_NETID_COL_NAME
This entry identifies the name of the column that contains the network ID value (NETWORKID).

Code example:


<init-param>
   <param-name>CMPI_VAULT_DB_NETID_COL_NAME</param-name>
   <param-value>NETWORKID</param-value>
</init-param>

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

Code example:


<init-param>
   <param-name>CMPI_VAULT_DB_HOSTADDR_COL_NAME</param-name>
   <param-value>HOSTADDRESS</param-value>
</init-param>

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

Code example:


<init-param>
   <param-name>CMPI_VAULT_DB_HOSTAPP_COL_NAME</param-name>
   <param-value>APPLICATIONID</param-value>
</init-param>

CMPI_VAULT_DB_HOSTID_COL_NAME
This entry identifies the name of the column that contains the host ID value (HOSTID).

Code example:


<init-param>
   <param-name>CMPI_VAULT_DB_HOSTID_COL_NAME</param-name>
   <param-value>HOSTID</param-value>
</init-param>
CMPI_VAULT_DB_HOSTPW_COL_NAME
This entry identifies the name of the column that contains the host password value (PASSWORD).

Code example:


<init-param>
   <param-name>CMPI_VAULT_DB_HOSTPW_COL_NAME</param-name>
   <param-value>PASSWORD</param-value>
</init-param>

Back to top


5. Add optional Vault parameters (if desired).

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

CMPI_VAULT_TRACE_LEVEL
This parameter specifies the trace level for the Vault plug-in. The trace messages are logged to the log file specified by CMPI_TRACE_LOG_FILE parameter. Depending on your Web application server, they may or may not be logged to the console. Trace level values include the following:
0 = None: No tracing. This is the default.
1 = Minimum: Trace APIs and parameters, return values, and errors.
2 = Normal: Trace Minimum plus internal APIs and parameters and informational messages.
3 = Maximum: Trace Normal plus Java exceptions.

Code example:


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

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

Code example:


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

Back to top


6. Save the WAR file.

On the Application Assembly Tool window, click File > Save to save your WAR file. If it saves successfully, this window will appear as a confirmation:

Back to top


Click Next to deploy the CMS.

BackHomeNext