Troubleshooting Web Express Logon

Web Express Logon depends on a number of independent processes working together to function properly. Some of these processes are client-based while others are host-based. If 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.

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.

If Web Express Logon is not functioning properly (that is, you are not logged in a host emulation session), complete the following checklist to try to determine the root cause:

Checklist

1. Did the Host On-Demand client display an error message?
   
   • If yes, skip to Web Express Logon client-side messages.
   • If no, verify the following on your session configuration panel:
     • Have you enabled Express Logon for the session that you are currently running? To do this, highlight your session and select Properties under the Configure drop-down menu in the Deployment Wizard. On the left side of the window, select Express Logon under Connection and click Yes to enable Express Logon.
     • Is this a 5250 session and you are using a Kerberos passticket for authentication? If so, you will need to make sure you select Yes for the Use Kerberos Passticket option on the Express logon window of session properties.
       
       
2. Are you using macro-based automation? If so, verify the following items:
   • When creating the macro, verify that you selected Web Express Logon (not Certificate Express Logon) on the Record macro window.
   • If you are expecting the macro to run when the session is started, verify that you have selected Auto-Start macro in your session configuration.
     
     
3. Did your automation macro run but not provide the appropriate credentials to log in the user? This means that you have properly accessed the Credential Mapper Web application, but something is not functioning properly within that environment. You should enable server-side logging and attempt another credential automation event. Then look in the log that is created and refer to Web Express Logon server-side messages.
   
   
4. Are you using IBM WebSphere Application Server and have Java 2 security enabled? If so, check to make sure that the following permissions are granted in the was.policy file, which is located in the META-INF directory.
   
   

   permission java.io.FilePermission "<<ALL FILES>>", "write";

   You can change <<ALL FILES>> to whichever directory you specifed in the CMPI_TRACE_LOG_FILE parameter in the web.xml file.
   
   

   permission java.lang.RuntimePermission "accessClassInPackage.sun.jdbc.odbc";

   This applies to the JDBC database Host Credential Mapper (HCM).



5. Are users being prompted for their network IDs twice? When using JVM V1.4 and later, users may be prompted for their network credentials two times. Although this is a known issue, currently no workaround exists. This double authentication issue does not occur when using JVM V1.3.x.

Web Express Logon client-side messages

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.

WELM001: Message key not found: status = value

This message should only be seen in the event of an error found in a custom plug-in. If you have customized the Web Express Logon credential mapper framework, you can create user defined error codes. If the Web Express Logon credential mapper returns such a code, this message will be displayed.

WELM002: No suitable Host credential plug-in found

This message is displayed when there is no appropriate credential plug-in found to handle the Host On-Demand client's credential request. Verify that your Web Express Logon credential mapper application is properly configured to handle the Host On-Demand client's session type.

WELM003: Invalid network user ID

The Web Express Logon credential mapper cannot acquire the user's network ID. This can be caused by improper settings in the network security plug-in section of the CMS configuration. If the local operating system identification is being used to identify the user, make sure this option is selected in the Express Logon section of the Session Configuration panel.

WELM004: Invalid Application ID

This message indicates the lack of a valid Application ID. You specify the Application ID when you create the Web Express Logon macro. When you create the macro, be sure that you enter the proper value for the Application ID.

WELM005: Invalid server address

This message indicates the lack of a valid server address. The server address is specified as the Destination Address on the Session Configuration panel. For some credential plug-ins, this is a required parameter.

WELM006: Could not connect to database

This problem can be generated by an improperly configured database link. Please verify that the database is properly configured in your CMS configuration. If the configuration information looks correct, you should independently verify the database's availability and running status. The database's configuration and management tools are a good place to perform this test.

WELM007: A matching user ID not found in database

The credential plug-in is not able to find a match for the user's host ID, given the search criteria. Verify that the user's host ID is specified in the database or other storage medium used by the credential plug-in. In addition, you may want to enable server-side logging and verify that the parameters being sent to the CMS are correct.

WELM008: The Credential Mapper Servlet reported an exception while processing a credential request. Please see the server log for details.

This generalized message is a result of an exception occurring on the CMS. Please follow the instructions for enabling server-side logging for more information about the cause of this problem.

WELM009: Invalid User ID

A credential plug-in does not have a valid user's host ID. For some plug-ins, the host ID is used to obtain a temporary passticket credential to access the host. If the value used is not appropriate, this message is generated. You may want to verify the user's host ID is specified in the database or other storage medium used by the credential plug-in. In addition, you may want to enable server-side logging and verify that the parameters being sent to the CMS are correct.

WELM010: Passticket could not be obtained

This message is displayed when a credential plug-in receives an error during the passticket creation process. Typically, the actual creation of the passticket occurs in a process outside of the credential plug-in. If that external process returns an error, this message displays. You should enable server-side logging and perform the credential request again. Using the information in the log along with the messages found in this section of the document should provide a better understanding of the problem.

WELM011: Credential/Passticket request timed out

This message is the result of a pending request timing out before it could be resolved. This could happen when the Host On-Demand client is making a request of the Credential Mapper Server, or it could be the credential plug-in making a request of an external entity. In either case, if the default time elapses before the request is fulfilled, this message is generated. To rectify the problem, verify that the addresses being used are correct. For the Host On-Demand client, the Credential Mapper server is specified as the Credential Mapper Server address in the Express Logon properties window of the Session Configuration panel. If the credential plug-in is generating this problem, verify that the credential plug-in is properly configured in your CMS configuration.

WELM012: Unexpected return code received from DCAS

This error is created when a credential plug-in receives an unexpected return value of an external application. You should enable server-side logging and perform the credential request again. Using the information in the log along with the messages found in this section of the document should provide a better understanding of the problem.

WELM013: API not supported. Contact the system administrator for server log.

This message informs the user that an unsupported request has been made of the credential plug-in selected by the credential mapping application. You should enable server-side logging and perform the credential request again. Using the information in the log along with the messages found in this section of the document should provide a better understanding of the problem.

WELM014: A malformed URL was specified for the Credential Mapper Server Address

The address used for the Credential Mapper server is not a valid URL address. The Credential Mapper server is specified as the Credential Mapper server address in the Express Logon properties of the Session Configuration panel.

WELM015: Unable to parse Credential Mapper response

The response generated by the Credential Mapper server application contains a response that is improperly formatted. This may happen when a custom Credential Mapper server application is used in place of the default Host On-Demand Credential Mapper server application. Refer to Customizing Web Express Logon for more information about the CMS response format.

WELM016: Local user ID not available

This message is generated when the operating system on which the Host On-Demand client is running does not support the Use Local Operating System ID option for network security identification. Refer to the Introduction for more information about which operating systems and versions are supported by this option.

WELM017: Credential Mapper response contained a duplicate userid, password, or status tag

This problem is caused when the response generated by the Credential Mapper server application contains duplicate response values. This may happen when a custom Credential Mapper server application is used in place of the default Host On-Demand Credential Mapper server application. Refer to Customizing Web Express Logon for more information about the CMS response format.

WELM018: An exception occurred while processing the credential request: some exception

This message is displayed when an exception occurs in the Host On-Demand client during the Web Express Logon process. If the exception is an IOException, the problem may be the Credential Mapper server address specified in the Express Logon properties panel in the session configuration. If the address seems correct, validate that the CMS server is available. Typing the Credential Mapper address specified in the session configuration into the address entry field of your browser allows you to test access to the CMS server easily. The results should be an XML document similar to the one described earlier in this document.

WELM050: Web Express Logon Credential Mapper Server Address not specified

Web Express Logon is used to automate the Host On-Demand configuration server login process, but the Credential Mapper server address is not specified. Verify that you have specified the proper value for the Credential Mapper server address in the Deployment Wizard.

WELM051: User name returned from Web Express Logon is not a known Host On-Demand user

Web Express Logon is used to automate the Host On-Demand configuration server login process and the user name provided by Web Express Logon is not a valid Host On-Demand user. Verify that the user is listed in the Host On-Demand configuration by accessing the Host On-Demand Administrative Console. In addition, view the server-side log to verify that the user name is being retrieved properly.

WELM052: Invalid password returned from Web Express Logon

Web Express Logon is used to automate the Host On-Demand configuration server login process, and the password provided by Web Express Logon is not a valid. Verify that the user is listed in the Host On-Demand configuration by accessing the Host On-Demand Administrative Console. In addition, view the server-side log to verify that the user name is being retrieved properly.

WELM053: This session is not enabled for Web Express Logon

A Web Express Logon macro is executed, and the session on which it is running has not been configured to use Web Express Logon. Web Express Logon can be configured via the Host On-Demand session configuration panel.

Web Express Logon server-side messages

The following are the primary server-side messages:

CMPIE001: Credential Mapper Plug-in initialization failed for: YourCredentialMapperName

This error occurs when the Credential Mapper plug-in corresponding to YourCredentialMapperName fails to initialize successfully. Possible causes of this error include the following:

• Your web.xml specifies an invalid or missing value for a parameter that is required by the specified plug-in.
• To determine which parameter(s) is causing the problem, turn on tracing for the plug-in and look in the log for error CMPIE008.
• You are using the DCAS or Vault plug-ins, and an error occurs when attempting to connect to the credentials database. Turn on tracing for the plug-in to obtain more diagnostic information (database driver missing, SQL exception, etc).
• You are using a custom plug-in, and your Init() method is returning a value other than 0 on success. Refer to the Customizing Web Express Logon for more information about writing your own credential mapper plug-in.
• You are using DCAS, and the SSL key database file or password is not specified in web.xml.

CMPIE003: No CM configuration can be found for the CM identified by the YourCredentialMapperName name.

This error occurs as a result of a missing element in your web.xml file. If you provide a value for the CMPICredentialMappers parameter that is not also a parameter itself elsewhere in the web.xml, you will get this error. For example, if you have the following definition in your web.xml,

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

you would also need something like this,

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

or you would get the error above.

CMPIE004: No Credential Mappers have been specified.

This error occurs when your web.xml does not define the CMPICredentialMappers parameter. Be sure to include the following in your web.xml:

<init-param>
<param-name>CMPICredentialMappers</param-name>
<param-value>YourCredentialMapperName(s)</param-value>
</init-param>

CMPIE005: No Credential Mapper found for Auth type: AuthTypeValue

When you define a Credential Mapper in your web.xml, you specify the type of Authentication to which the plug-in applies. For example, if you had an entry such as the following,

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

this would show that the vault Credential Mapper is only intended to be used with 3270 host sessions. If this were the only Credential Mapper defined in your web.xml and you tried to perform a logon to a 5250 session, you would receive this error with AuthTypeValue equal to AuthType_5250Host. Be sure that your web.xml has a Credential Mapper defined that is appropriate for your authentication type.

CMPIE007: No authentication type specified for CM object: YourCredentialMapperName

When you define a Credential Mapper in your web.xml, you must specify the full class path name, the authentication type, and the host mask. If you do not specify an authentication type, or if you specify an invalid authentication type (such as AuthType_Fred), you will get this error. For a list of valid authentication types, refer to the glossary.

CMPIE008: Invalid value for parameter: ParameterName

This error occurs when a parameter that is required by the plug-in has an invalid value or has not been specified. Provide an appropriate value in the web.xml for the parameter ParameterName.

CMPIE010: Exception and Host User ID not found for Network ID: NetIDValue.

An exception occurred before the host user ID corresponding to NetIDValue could be found. A possible cause of the exception is a mismatch between the column names in the data source and the column names specified in the web.xml. Another possibility is an error in the formatting of the table name ([tableName$] for Excel, simply tableName for DB2). Double check your web.xml for errors and refer to the exception trace in the server log for debugging information.

CMPIE011: Host User ID not found for Network ID: NetIDValue.

This error occurs when there is no entry found in the database for NetIDValue. Check your database and verify that there is an entry for NetIDValue. Make sure that the host address and application ID found in the server log for this query match the host address and application ID specified for this NetID in the database.

CMPIE012: SQLException: Value.

This error occurs when attempting to open or close a connection to the database. Make sure that the database is available and correctly specified in the web.xml file.

CMPIE013: Exception: Value.

An exception occurred in the plug-in code.

DCAS error messages

The following are the primary DCAS error messages:

DCASE001: Cannot import the CA certificates contained in Keyring Database.

An SSL runtime exception occurred while loading the CA certificates from the KeyringDatabase. The file may be corrupted. Please see the additional logged messages for details. You may have to set the CMPI_DCAS_TRACE_LEVEL parameter in web.xml to 3 to see the additional messages.

DCASE002: Cannot read the keyring file: KeyringFileName

The specified KeyringFileName cannot be loaded. Make sure that the file exists and the path name and file name are correctly specified in the web.xml file. See the exception trace for additional information.

DCASE003: The DCAS server address is either blank or null.

The Host On-Demand client's credential request contains an invalid server address. See the WELM005 message for details.

DCASE004: The Keyring file name is either blank or null.

The CMPI_DCAS_KEYRING_FILE parameter must be specified in the web,xml file. Check the web.xml file.

DCASE005: The Keyring password is either blank or null.

The CMPI_DCAS_KEYRING_PASSWORD parameter must be specified in the web.xml file. Check the web.xml file.

DCASE006: The host user id is either blank or null.

The host user ID retrieved from the vault database is either blank or null. Check the vault database for host user ID.

DCASE007: The host application id is either blank or null.

The Host On-Demand client's credential request contains an invalid application ID. See the WELM004 message for details.

DCASE008: Passticket could not be obtained for user ID: Userid

The DCAS client could not obtain a passticket for the specified User ID. Make sure that the host user ID is valid and it is defined to the host credential system such as RACF. Also, see the additional logged message for a specific failure.

DCASE009: DCAS timer expired - no response from server: Host

The DCAS connection timer expired before a passticket request could be completed. If this problem persists, you may want to increase the value of the CMPI_DCAS_REQUEST_TIMEOUT parameter in the web.xml file. This value should be less than the timeout value for the macro.

DCASE010: Unexpected DCAS return code: ReturnCode

This error suggests an internal coding error. Please make a note of the ReturnCode and report this problem.

DCASE013: DCAS Exception: Exception

Exception occurred while processing a passticket request. See the additional logged messages for details.

DCASE021: Cannot send passticket request to server Host

The DCAS server connection is not active. Check the DCAS server log and retry the operation.

DCASE022: An unexpected error occurred while processing a passticket request.

An unexpected exception occurred while processing a passticket request. See the exception details to determine the cause of the problem.

DCASE023: An error occurred while receiving data from the passticket server Host. The connection is closing.

Input/Output error occurred while receiving data from the passticket/DCAS server. Retry the operation. If the problem persists, check the DCAS server log for details.

DCASE050: Cannot create socket to the passticket server at IpAddr. See other messages for details.

An SSL exception occurred while creating a secure connection. See the additional logged messages for details. You may have to set the CMPI_DCAS_TRACE_LEVEL parameter in web.xml to 3 to see the additional messages. This message typically indicates an SSL handshake failure.

DCASE051: The DCAS server at Ipaddr is an unknown host.

The Destination Address specified in the Session Connection panel is an unknown host. Check the Ipaddr to make sure it is valid. See the WELM005 message.

DCASE052: Cannot create socket to the passticket server at IpAddr because of an I/O error.

An I/O exception occurred while creating a secure connection to IpAddr. See the additional logged messages for details. You may have to set the CMPI_DCAS_TRACE_LEVEL parameter in web.xml to 3 to see the additional messages. The server at IpAddr may be down.

DCASE060: The common name in the certificate received from Host is empty. SSL connection is terminated.

The SSL server authentication failed. The Host presented a certificate that does not contain the common name. Please update the server certificate's common name, or turn the server authentication off.

DCASE061: The common name in the certificate received from Host has no address. SSL connection is terminated.

The SSL server authentication failed. The host presented a certificate whose common name does not have an address. Update the server certificate's common name to the server's IP address, or turn the server authentication off.

DCASE062: The passticket server's name Host has no address. SSL connection is terminated.

The SSL server authentication failed. The host presented a certificate whose host name does not have an IP address. Make sure that an IP address is associated with the host name, or turn the server authentication off.

DCASE063: The common name in the certificate received from Host does not match the partner's common name. SSL connection is terminated.

The SSL server authentication failed. The socket or discovered address does not match the common name specified in the Host certificate. The server certificate could not be authenticated. Update the server certificate's common name to match its IP address, or turn the server authentication off.

DCASE064: No certificate chain received from Host. SSL connection is terminated.

The host did not present its certificate when a connection was established. The server certificate could not be authenticated. The host must be configured to send its certificate to do the server authentication.

Back to top