Oracle® Fusion Middleware

Configuring and Diagnosing Logon Manager Application Templates

11g Release 2 (11.1.2.2)

E37701-02

June 2014

Oracle Fusion Middleware Configuring and Diagnosing Logon Manager Application Templates, 11g Release 2 (11.1.2.2)

E37701-02

Copyright © 1998, 2014, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate failsafe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Contents

Preface

- Audience

- Documentation Accessibility

- Related Documents

- Conventions

1 Configuring and Diagnosing
Windows Application Templates

- 1.1 Overview of a Sign-On Event

- 1.2 Understanding Window Detection

- 1.3 Understanding Form Response

- 1.3.1 Supported Form Types

- 1.3.2 Supported Form Response Methods

- 1.3.2.1 Control IDs

- 1.3.2.2 "SendKeys"

- 1.3.2.3 Control IDs with "SendKeys"

- 1.4 Determining the Optimal Configuration for a Form

- 1.4.1 Determining the Optimal Configuration for a Logon Form

- 1.4.1.1 Non-unique target window?

- 1.4.1.2 Target window title blank or dynamic?

- 1.4.1.3 Target window class dynamic?

- 1.4.1.4 Target fields and controls appear in the Form Wizard?

- 1.4.1.5 Non-unique or dynamic Control IDs in the form?

- 1.4.2 Determining the Optimal Configuration for a Password Change Form

- 1.4.2.1 Logon and password change forms on the same screen?

- 1.4.2.2 Password change form on a tab different than logon form?

- 1.4.2.3 Action required to initiate password change?

- 1.4.2.4 Non-unique target window?

- 1.4.2.5 Target window title blank or dynamic?

- 1.4.2.6 Target window class dynamic?

- 1.4.2.7 Target fields and controls appear in the Form Wizard?

- 1.4.2.8 Non-unique or dynamic Control IDs in the form?

- 1.4.2.9 Application requires confirmation of new password?

- 1.4.2.10 Application displays a password change success and/or failure dialogs?

- 1.5 Configuring a Form

- 1.5.1 Configuring a Form Using Control IDs

- 1.5.2 Configuring a Form Using "SendKeys"

- 1.5.3 Using Matching to Improve Response Accuracy

- 1.5.3.1 Matching for a Blank or Dynamic Value

- 1.5.3.2 Matching Against a Window Title

- 1.5.3.3 Matching Against a Window Class

- 1.5.3.4 Matching Against an Executable Name

- 1.5.3.5 Matching Against a Field, Control, or Text String

- 1.5.4 Configuring an Application as a Service Logon

- 1.5.5 Disabling Automatic "SendKeys" Fallback

- 1.6 Testing the Configuration of a Form

- 1.6.1 Testing the Configuration of a Logon Form

- 1.6.1.1 Agent detects window?

- 1.6.1.2 Agent injects credentials?

- 1.6.1.3 Logon loop occurring on logout?

- 1.6.1.4 Agent responding properly after application is restarted?

- 1.6.2 Testing the Configuration of a Password Change Form

- 1.6.2.1 Agent detects the window?

- 1.6.2.2 Agent injects and submits credentials?

- 1.6.2.3 New password satisfies application's password policy?

- 1.6.2.4 Agent responds to password change form as if it were a logon?

- 1.7 Publishing a Template to the Repository

- 1.8 Troubleshooting Window Detection

- 1.8.1 Agent detects the window?

- 1.8.2 Agent responds to target window but also to other windows?

- 1.8.3 Agent detects window when using the "Logon Using Logon Manager" tray icon option?

- 1.8.4 Application running as a service or a user other than the current?

- 1.8.5 Window title changes after detection?

- 1.9 Troubleshooting Form Response When Using Control IDs

- 1.9.1 Agent populates fields but does not submit the logon?

- 1.9.2 Application rejects injected credentials?

- 1.9.3 Fields populated erratically?

- 1.10 Troubleshooting Form Response When Using "SendKeys"

- 1.10.1 Pre-filled fields cause erroneous logon?

- 1.10.2 Cursor always starts in the same field and retains focus?

- 1.10.3 Multiple values injected into a single field?

- 1.10.4 Switching to "SendKeys" with journal hooks restores reliable injection?

- 1.10.5 Characters missing from injected values?

- 1.10.6 Using mouse click actions to focus on fields results in successful logon?

- 1.11 Troubleshooting Matching

- 1.11.1 Target field or control recognized by Control Match Wizard?

- 1.11.2 Non-unique or dynamic Control IDs in the form?

- 1.12 Troubleshooting a Logon Loop

- 1.12.1 Post-logout form different from standard logon form?

- 1.12.2 Configuring the "Logon Loop Grace Period" option resolves logon loop?

- 1.13 Troubleshooting Java Application Issues

- 1.13.1 Installed JRE is a supported brand and version?

- 1.13.2 Using Oracle JInitiator or another JRE not made by Oracle or IBM?

- 1.13.3 JHO loaded?

- 1.13.4 Verifying and Repairing the Permissions Required by the JHO

- 1.13.4.1 Verifying That the Required Permissions Are Being Granted

- 1.13.4.2 Restoring the Missing JHO Permissions

- 1.13.5 Configuring the Behavior of the Java Helper Object (JHO)

- 1.13.5.1 Manually Restricting the JHO to Specific JREs

- 1.13.5.2 Manually Customizing the Event Response Behavior of the Java Helper Object (JHO)

2 Configuring and Diagnosing
Web Application Templates

- 2.1 Overview of a Sign-On Event

- 2.2 Understanding Web Form Detection

- 2.2.1 Supported Form Types

- 2.2.2 Understanding URL Detection

- 2.2.2.1 Understanding URL Matching Precision

- 2.2.2.2 Obtaining the URL of a Page, Element, or Pop-Up

- 2.2.3 Understanding Field Detection

- 2.2.3.1 Understanding HTML Elements

- 2.2.3.2 Understanding the Frame Element

- 2.2.3.3 Understanding the Form Element

- 2.2.3.4 Understanding the Input Elements Supported by Logon Manager

- 2.2.4 Recommended Page Inspection Tools

- 2.2.4.1 DOM Inspector for Mozilla Firefox

- 2.2.4.2 Firebug for Mozilla Firefox

- 2.2.5 Understanding Detection Matching

- 2.2.5.1 Detection Matching vs. Offset Matching

- 2.2.5.2 Matching Against Text on the Page

- 2.2.5.3 Matching Against HTML Code in the Page's Source

- 2.2.5.4 Matching Against Names and Values of Element Attributes

- 2.2.5.5 Constructing Complex Rule Chains Using Logic Operators

- 2.2.6 Using Wildcards to Configure Detection Criteria

- 2.2.7 Using Regular Expressions to Configure Detection Criteria

- 2.3 Understanding Form Response

- 2.3.1 Control IDs

- 2.3.2 "SendKeys"

- 2.3.3 Control IDs with "SendKeys"

- 2.4 Determining the Optimal Configuration for a Form

- 2.4.1 Determining the Optimal Configuration for a Logon Form

- 2.4.1.1 Target fields and controls appear in the Web Form Wizard?

- 2.4.1.2 Non-unique or dynamic field names?

- 2.4.1.3 Dynamic page or element URL?

- 2.4.1.4 Logon form is a Flash applet?

- 2.4.1.5 "Submit" control is an image?

- 2.4.1.6 Other fields on the page besides target fields?

- 2.4.1.7 Application displays a logon success and/or failure message?

- 2.4.2 Determining the Optimal Configuration for a Password Change Form

- 2.4.2.1 Logon and password change forms on the same screen?

- 2.4.2.2 Action required to initiate password change?

- 2.4.2.3 Target fields and controls appear in the Web Form Wizard?

- 2.4.2.4 Application requires confirmation of new password?

- 2.4.2.5 Need to inject the same data into more than one field?

- 2.4.2.6 Application displays a password change success and/or failure message?

- 2.4.2.7 Non-unique or dynamic field names?

- 2.4.2.8 Dynamic page or element URL?

- 2.4.2.9 "Submit" control is an image?

- 2.4.2.10 Other fields on the page besides target fields?

- 2.5 Configuring a Form

- 2.5.1 Basic Configuration

- 2.5.2 Manually Configuring a Field or Control

- 2.5.2.1 Configuring a Field or Control Using the "Control IDs" Method

- 2.5.2.2 Configuring a Field or Control Using the "SendKeys" Method

- 2.5.3 Configuring URL Detection Criteria

- 2.5.4 Configuring Additional Field Detection Criteria

- 2.6 Testing the Configuration of a Form

- 2.6.1 Testing the Configuration of a Logon Form

- 2.6.1.1 Agent detects form?

- 2.6.1.2 Agent injects credentials?

- 2.6.1.3 Logon loop occurring on logout?

- 2.7 Testing the Configuration of a Password Change Form

- 2.7.1 Agent detects the form?

- 2.7.2 Agent injects and submits credentials?

- 2.7.3 New password satisfies application's password policy?

- 2.7.4 Agent responds to password change form as if it were a logon?

- 2.8 Publishing a Template to the Repository

- 2.9 Troubleshooting Web Form Detection

- 2.9.1 "Logon Using Logon Manager" tray icon option results in successful detection?

- 2.9.2 Page completed loading?

- 2.9.3 Is the appropriate helper object running?

- 2.9.4 Removing all detection and offset matching rules results in successful detection?

- 2.9.5 Truncating URL definition to host.domain form results in successful detection?

- 2.10 Troubleshooting Form Response when Using Control IDs

- 2.10.1 Agent detects the form?

- 2.10.2 Agent injects credentials but does not submit them?

- 2.10.3 Fields populated erratically?

- 2.11 Troubleshooting Form Response When Using "SendKeys"

- 2.11.1 Pre-filled fields cause erroneous logon?

- 2.11.2 Cursor always starts in the same field and retains focus?

- 2.11.3 Multiple values injected into a single field?

- 2.11.4 Switching to "SendKeys" with journal hooks restores reliable injection?

- 2.11.5 Characters missing from injected values?

- 2.11.6 Using mouse click actions to focus on fields results in successful logon?

- 2.12 Troubleshooting Detection Matching

- 2.12.1 Removing all matching rules restores form detection?

- 2.13 Troubleshooting a Logon Loop

- 2.13.1 Post-logout form URL from standard logon form URL?

- 2.13.2 Post-logout form different from standard logon form?

- 2.13.3 Configuring the "Logon Loop Grace Period" option resolves logon loop?

- 2.14 Troubleshooting Java Application Issues

- 2.14.1 Installed JRE is a supported brand and version?

- 2.14.2 Using Oracle JInitiator or another JRE not made by Oracle or IBM?

- 2.14.3 JHO loaded?

- 2.14.4 Verifying and Repairing the Permissions Required by the JHO

- 2.14.4.1 Verifying That the Required Permissions Are Being Granted

- 2.14.4.2 Restoring the Missing JHO Permissions

- 2.14.5 Configuring the Behavior of the Java Helper Object (JHO)

- 2.14.5.1 Manually Restricting the JHO to Specific JREs

- 2.14.5.2 Manually Customizing the Event Response Behavior of the Java Helper Object (JHO)

3 Configuring and Diagnosing
Mainframe Application Templates

- 3.1 Overview of a Sign-On Event

- 3.2 Understanding Form Detection and Response

- 3.2.1 Fixed Screen Forms vs. Scrolling Screen Forms

- 3.2.2 Supported Form Types

- 3.2.3 Supported Credential Injection Methods

- 3.3 Determining the Optimal Configuration for a Form

- 3.3.1 Determining the Optimal Configuration for a Logon Form

- 3.3.1.1 Emulator supported by Logon Manager out of the box?

- 3.3.1.2 Is the emulator HLLAPI-compliant?

- 3.3.1.3 Is the emulator's HLLAPI implementation up to date?

- 3.3.1.4 Non-unique target form?

- 3.3.1.5 Logon form comprised of multiple screens?

- 3.3.1.6 Logon and password change (PWC) forms on the same screen?

- 3.3.2 Determining the Optimal Configuration for a Password Change Form

- 3.3.2.1 Logon and password change (PWC) forms on the same screen?

- 3.3.2.2 PWC form comprised of multiple screens?

- 3.3.2.3 One or more non-unique screens?

- 3.3.2.4 Application requests confirmation of new password?

- 3.3.2.5 Application displays a password change success or failure message?

- 3.4 Configuring a Form

- 3.4.1 Basic Configuration of a Fixed-Screen Form

- 3.4.2 Basic Configuration of a Scrolling-Screen Form

- 3.4.3 Advanced Form Configuration

- 3.4.3.1 Defining Window Title Matching Rules

- 3.4.3.2 Defining Additional Text Matching Rules

- 3.4.3.3 Defining Additional Fields

- 3.4.3.4 Adding Keystrokes, Pauses, or Text to the Logon Sequence

- 3.4.3.5 Configuring a Form for Dynamic Column Positioning (Scrolling-Screen Only)

- 3.4.3.6 Reducing Injection Speed

- 3.4.3.7 Adjusting the Emulator Polling Interval

- 3.4.3.8 Adjusting the Credential Request Delay Interval

- 3.5 Testing the Configuration of a Form

- 3.5.1 Testing the Configuration of a Logon Form

- 3.5.1.1 Agent detects the form?

- 3.5.1.2 Agent injects credentials?

- 3.5.1.3 Logon loop occurring on logout?

- 3.5.1.4 Logon failure or expired password exceptions accounted for in the template?

- 3.5.2 Testing the Configuration of a Password Change Form

- 3.5.2.1 Agent detects the form?

- 3.5.2.2 Agent injects and submits credentials?

- 3.5.2.3 New password satisfies application's password policy?

- 3.5.2.4 Agent responds to password change form as if it were a logon?

- 3.6 Publishing a Template to the Repository

- 3.7 Viewing and Modifying Emulator Configuration

- 3.7.1 Emulator Configuration Parameter Reference

- 3.8 Troubleshooting Form Detection

- 3.8.1 Agent detects the form when invoking the "Logon Using Logon Manager" tray icon option?

- 3.8.2 Valid entry for the emulator exists in mfrmlist.ini?

- 3.8.3 Has "Host/Mainframe Support" global Agent setting been disabled?

- 3.8.4 Match text, field text, and corresponding coordinates correct?

- 3.8.5 Emulator's HLLAPI implementation up to date and enabled?

- 3.8.6 Appropriate mainframe support component installed?

- 3.9 Troubleshooting Form Response

- 3.9.1 Agent detects the form?

- 3.9.2 Agent injects credentials but does not submit them?

- 3.9.3 Enter keystroke explicitly added to the logon sequence?

- 3.9.4 Fields populated erratically?

- 3.10 Troubleshooting a Logon Loop

- 3.10.1 Post-logout form different from standard logon form?

- 3.10.2 Configuring the "Logon Loop Grace Period" option resolves logon loop?

- 3.11 Troubleshooting Detection and Response with the SSO MHO Status Tool

- 3.11.1 Understanding the MHO Status Tool Interface

- 3.11.2 Using the MHO Status Tool to Diagnose Session Detection and Response

Preface

This guide describes the best practices and recommended procedures for configuring and diagnosing Windows, Web, and mainframe application templates. Topics covered include configuring logon and password change forms, as well as diagnosing and resolving most common application response issues.

Audience

This guide is intended for experienced administrators responsible for the planning, implementation and deployment of applications. Administrators are expected to have solid knowledge of directory environments, permission structures, domain administration, and databases.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

Related Documents

For more information, see the following documents in the Oracle Enterprise Single Sign-On Suite Release 11.1.2.2 documentation set:

- Oracle Enterprise Single Sign-On Suite Release Notes

- Oracle Enterprise Single Sign-On Suite Installation Guide

- Oracle Enterprise Single Sign-On Suite Administrator's Guide

- Oracle Enterprise Single Sign-On Suite Secure Deployment Guide

- Oracle Enterprise Single Sign-On Suite User's Guide

- Deploying Logon Manager with a Directory-Based Repository

Conventions

The following text conventions are used in this document:

Convention

Meaning

boldface

Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary.

italic

Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.

monospace

Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

1 Configuring and Diagnosing
Windows Application Templates

This chapter explains the concepts necessary to understand how and why you should configure Windows application templates to solve specific sign-on scenarios, as well as the recommended best-practice procedures for configuring and testing Windows application forms, and diagnosis and resolution steps for the most common issues that may cause the Agent to erratically detect and/or respond to application forms. It covers the following topics:

- Overview of a Sign-On Event

- Understanding Window Detection

- Understanding Form Response

- Determining the Optimal Configuration for a Form

- Configuring a Form

- Publishing a Template to the Repository

- Troubleshooting Window Detection

- Troubleshooting Form Response When Using Control IDs

- Troubleshooting Form Response When Using "SendKeys"

- Troubleshooting Matching

- Troubleshooting a Logon Loop

- Troubleshooting Java Application Issues

Tip:

If the troubleshooting steps in this chapter do not resolve your issue, you can troubleshoot further by tracing and logging the activity of Logon Manager and submitting the logged information to Oracle Support for analysis. For this purpose, Oracle provides the Trace Controller utility, from Oracle Support. For information on how to use the utility, see the "Using the Trace Controller Utility" topic in the Enterprise Single Sign-On Suite Administrator's Guide.

1.1 Overview of a Sign-On Event

Logon Manager can be configured to detect and respond to a wide range of sign-on events, such as logon, password change, and variations of thereof; support is provided for a diverse range of forms, fields, controls, and event flows.

In order to recognize application windows, the Agent constantly monitors the currently logged in user's Windows message queue and responds as follows:

1. Agent detects the window. For each new window it detects, the Agent does the following:

1. Searches through all of the available Windows application templates to find a match for the values of the identification criteria defined in the template. (These include the window title, window class, and executable name.)

2. Selects the first template whose configuration matches the criteria presented by the window.

3. Begins the response process.

2. Agent responds to the form within the detected window. The Agent follows the configuration stored in the template to determine how to interact with the fields and controls in the form. Typically, the Agent does the following:

1. (Optional) Performs the actions, such as setting field focus, which might be required by the application to invoke or activate the logon or password change form.

2. Retrieves the associated credentials from the user's store (if they exist) and populates the appropriate fields. (If the credentials don't exist, the Agent prompts the user to store them.)

3. Performs the actions necessary to submit the credentials to the application for processing, such as pressing the Logon button.

4. (Optional) Detects any follow-up forms or dialogs, such as new password confirmation, and performs the required action.

1.2 Understanding Window Detection

Whenever the Agent detects the instantiation of a new window (through the Windows message queue), the Agent examines the values of the following characteristics of the window and compares them to the values stored in each available application template in order to uniquely identify the window and the form it contains:

- Window title

- Window class

- Executable name (also referred to as a module name or an AppPath key)

Note:

An application template is a set of configuration options that instruct the Logon Manager Agent how to detect and respond to application windows and the forms they contain.

If a window other than the target window shares the values of these identifying criteria with the target window, the Agent may erroneously respond to such a window in addition to the target window. In such cases, you must use matching to more precisely constrain the allowable values of these criteria so that the resulting configuration uniquely identifies the target window and form to the Agent. For more information on matching, see Using Matching to Improve Response Accuracy.

If a match is found, the Agent responds to the form as defined in the first matched template, i.e., logs the user on or initiates password change.

1.3 Understanding Form Response

Once the Agent recognizes an application window, it checks for the presence of fields and controls that comprise a "form," such as a logon form, or a password change form. A logon form, for example, typically contains at least a user name field, a password field, and a button that submits the credentials to the application. An example logon form is shown below.

1.3.1 Supported Form Types

As of the release date of this document, Logon Manager supports the following types of forms in Windows applications:

- Logon

- Logon success (a message confirming successful logon)

- Logon failure (a message indicating the injected credentials have been rejected)

- Password change

- Password confirmation (a dialog requesting confirmation of the new password)

- Password change success (a dialog confirming successful password change)

- Password change failure (a dialog indicating the new password was rejected)

The same application window may contain different forms depending on the invoked function (i.e., logon or password change); thus, a single template can contain definitions for the multiple forms that the window can display. For most applications, you need to only define the forms to which you want Logon Manager to respond.

Note:

Defining a form comprises providing unique identification criteria, specifying the action to take when the form is detected, and the specific way in which the action (e.g., injecting credentials) should be performed.

Logon Manager can automatically populate the appropriate fields in a form with credentials retrieved from the user's credential store, as well as operate the form's controls to submit the credentials to the application for processing. Configuration options that instruct the Agent how to interact with the form's fields and controls are stored in the template.

1.3.2 Supported Form Response Methods

Depending on the design of the target application, Logon Manager can use one of the following methods to interact with the fields and controls in the target form.

1.3.2.1 Control IDs

This is the default and preferred form interaction method for most Windows applications. This method uses the Windows API to identify and interact with the fields and controls within the form. In a Windows API-compliant application, each field and control exposes a unique Control ID to the operating system. The Agent detects these Control IDs and binds to them specific sign-on functions that signify the purpose of the object represented by the Control ID, such as the password field or the "submit" button.

Note:

If some or all of the Control IDs exposed by the application are non-unique or dynamic, the Agent can substitute ordinals - sequential ID numbers assigned to each item in the window from top to bottom, left to right - to uniquely identify the detected fields and controls.

If a field or control does not expose its Control ID, or if there are additional actions required to complete the sign-on event, such as selecting a check box or manually setting focus on a specific field, you may also have to use the "SendKeys" method, in tandem with Control IDs, to interact with the target form.

1.3.2.2 "SendKeys"

This method allows the Agent to interact with the target application by emulating user input, such as keystrokes and mouse clicks. Use this method if the Agent is unable to programmatically detect or interact with the target fields and controls. For example, if an application does not expose Control IDs for any of its fields and controls, you will need to send individual keystrokes to populate the fields, mouse clicks or Tab keystrokes to toggle between fields, and a final mouse click to engage the Logon button.

Note:

If you configure a form definition to use the "Control IDs" method and Logon Manager fails to inject credentials programmatically due to application incompatibility, by default Logon Manager will automatically fall back to the "SendKeys" method and retry injection, which could result in credentials being injected into the wrong window or application. You can disable this fallback behavior by following the steps in Disabling Automatic "SendKeys" Fallback.

1.3.2.3 Control IDs with "SendKeys"

This method is a "best-of-both-worlds" combination of the two above methods and is the preferred way of solving sign-on scenarios that require actions that cannot be performed programmatically. Control IDs are used to interact with the form wherever possible, while keystrokes and mouse clicks are sent to accomplish tasks such as setting field focus, selecting a check box, and other actions that the Agent cannot perform programmatically within the target application.

Note:

To achieve this "mixed" mode, configure the form to initially use the "SendKeys" response method, then configure the desired "SendKeys" actions; while configuring the actions, enable the Inject directly into control option for actions that you wish to retain the "Control IDs" programmatic response method.

For example, if fields must be populated in a specific order due to cascading validation (i.e., the password field becomes active only once the user name field has been populated), you would use Control IDs to inject credentials into the fields, but send a Tab keystroke via "SendKeys" between each field injection to advance field focus.

1.4 Determining the Optimal Configuration for a Form

When Configuring a Form, use the information in this section to determine its optimal configuration based on the requirements and features of the target application.

1.4.1 Determining the Optimal Configuration for a Logon Form

1.4.1.1 Non-unique target window?

If the Agent cannot uniquely distinguish the target window from others, (i.e., another window whose window title, class, and/or module name are identical to those of the target window), the Agent might erroneously respond to such a window in addition to the target window. For more information on the causes of this issue and steps for resolving it, see Troubleshooting Window Detection.

1.4.1.2 Target window title blank or dynamic?

Blank window titles require no special configuration; dynamic text in the window title can be matched using either regular expressions or environment variables. For more information, see Using Matching to Improve Response Accuracy.

1.4.1.3 Target window class dynamic?

If the window class of the target window is partially or fully dynamic, you must use matching to allow the Agent to uniquely identify the target window by its title. For more information, see Using Matching to Improve Response Accuracy.

1.4.1.4 Target fields and controls appear in the Form Wizard?

In most situations, the Form Wizard successfully detects and displays the credential fields and controls present in the target window. If no fields or controls are visible in the Form Wizard, or if the items listed do not correspond to any of the fields or controls in the target window, you may need to use "SendKeys" to interact with that field or control. For more information, see Supported Form Response Methods.

1.4.1.5 Non-unique or dynamic Control IDs in the form?

Once you have identified the credential fields and controls that you wish to enable for sign-on, check that their Control IDs are unique. If you discover duplicates, Logon Manager's response to the application might be unreliable; in such cases, use ordinals to interact with the fields and controls in question. For more information, see Supported Form Response Methods.

1.4.2 Determining the Optimal Configuration for a Password Change Form

1.4.2.1 Logon and password change forms on the same screen?

Some applications might present password change forms that also contain logon-related fields or controls, such as a user name field or a Change Password button. For example, the logon screen shown below contains a Change button.

This Change button, in turn, invokes the password change screen.

If the Auto Submit feature is enabled and the Agent responds to such application, the user is logged in automatically without being given the option to change the password.

In order to allow the user to select the desired course of action, define the logon and password change forms in the template. The Agent will prompt the user for the desired course of action (logon or password change) when it responds to an application with consolidated logon and password change forms.

Note:

You also have the option to configure a grace period for the "action chooser" feature, during which the Agent will automatically assume that logon is the preferred action and log the user on without prompting to choose the desired action. This option, named Action Chooser Grace Period, is available in the Miscellaneous tab in the application template.

1.4.2.2 Password change form on a tab different than logon form?

Define the logon and password change forms in the template. The Agent will automatically switch to the password change tab when password change is initiated, and treat the password change form tab as a separate window.

Note: Only applications that implement tabs in full compliance with the WinAPI specification are supported.

1.4.2.3 Action required to initiate password change?

If the form requires an action to initiate password change, such as selecting a checkbox, and the Agent is unable to perform that action programmatically, you may need to use "SendKeys" to complete the action by sending keystrokes and/or mouse clicks to the application. For more information, see Supported Form Response Methods.

1.4.2.4 Non-unique target window?

If the Agent cannot uniquely distinguish the target window from other, similar windows, (i.e., when another window is instantiated whose window title, class, and module name are identical to those of the target window), the Agent might erroneously respond to such a window in addition to the target window. For more information on the causes of this issue and steps for resolving it, see Troubleshooting Window Detection.

1.4.2.5 Target window title blank or dynamic?

Blank window titles require no special configuration; dynamic text in the window title can be matched using either regular expressions or environment variables. For more information, see Using Matching to Improve Response Accuracy.

1.4.2.6 Target window class dynamic?

If the window class of the target window is partially or fully dynamic, you must use matching to allow the Agent to uniquely identify the target window by its title. For more information, see Using Matching to Improve Response Accuracy.

1.4.2.7 Target fields and controls appear in the Form Wizard?

In most situations, the Form Wizard successfully detects and displays the credential fields and controls present in the target window. If no fields or controls are visible in the Form Wizard, or if the items listed do not correspond to any of the fields or controls in the target window, you may need to use "SendKeys" to interact with that field or control. For more information, see Supported Form Response Methods.

1.4.2.8 Non-unique or dynamic Control IDs in the form?

Once you have identified the credential fields and controls that you wish to enable for sign-on, check that their Control IDs are unique. If you discover duplicates, Logon Manager's response to the application might be unreliable; in such cases, use ordinals to interact with the fields and controls in question. For more information, see Supported Form Response Methods.

1.4.2.9 Application requires confirmation of new password?

Some applications prompt the user to confirm the new password when performing a password change. If the target application displays such a dialog, configure the password change form, then configure a "Confirm Password" form that will respond to the confirmation dialog. For instructions, see Configuring a Form.

1.4.2.10 Application displays a password change success and/or failure dialogs?

Some application display a message indicating whether password change was a success or a failure. In such cases, define a password change success or a password change failure form in the application template. For instructions, see Configuring a Form.

1.5 Configuring a Form

The procedures in this section use concepts and terminology explained earlier in this guide. When performing the procedures in this section, refer to Determining the Optimal Configuration for a Formto make configuration decisions that best suit the target application.

1.5.1 Configuring a Form Using Control IDs

To configure a Windows application form that will use the Control IDs response method, do the following:

1. Open the Logon Manager Administrative Console. By default, the shortcut is located at Start > Programs > Oracle > ESSO-LM Administrative Console.

2. In the left-hand tree, select the Applications node and do one of the following:

- If you want to create a new template and define the logon form, click Add in the right-hand pane; in the New Application dialog, enter a descriptive name for the template and click Finish. The new template appears in the list of stored templates.

Caution:

If two or more application templates are named such that the name of one of the templates occurs in the beginning of the name of another template, the Agent will erroneously use the template with the shortest name to respond to all of the affected applications. To avoid this behavior, ensure that your template names do not begin with the same string of text.

- If you want to add a logon form definition to an existing template, do the following, expand the Applications node and select the desired template (the template appears in the right-hand pane) and click Add at the bottom of the pane.

3. In the Form Wizard that appears, configure the fields and controls that you want the Agent to interact with when responding to the target form. In the "Form Type"screen, select the desired form type and click Next.

4. In the "Application Window" screen, select the window that contains the target form. A thick blue border appears around the chosen window to indicate your selection.

Note:

If you see two or more windows that share the same value for any of the parameters, the Agent might erroneously respond to all of those windows, instead of only the target window. For more information on this issue, see Troubleshooting Window Detection.

5. In the "Credential Fields" screen, select and configure the target fields and controls from among the objects in the list as follows:

1. (Optional) If your form requires the injection of the same data into multiple fields (e.g., injecting the password into a Password and a Confirm Password field), enable the Allow multiple field designation option.

2. Right-click each desired field or control and select its function from the context menu.

Caution:

While the Detect Fields feature is accurate the majority of the time, Oracle recommends always configuring fields and controls manually for guaranteed accuracy.

3. If the application requires that Logon Manager interacts with its fields and controls using the "SendKeys" method, which emulates user input such as keystrokes and mouse clicks, select Use "SendKeys" for this form instead of IDs. To determine whether your application requires this option, see Understanding Form Response.)

4. If the application requires that Logon Manager addresses its fields and controls via ordinals rather than Control IDs, select Use ordinals instead of control IDs. (To determine whether your application requires this option, see Understanding Form Response.)

6. In the "Summary" screen, review your configuration choices. If you want to change any of the options you selected, click Back, otherwise, click Finish.

7. In the template properties dialog that appears, click OK to save the new form definition.

Note:

If you want to configure additional options for the template and you are familiar with their locations and functionalities, you may do so now, if you desire. Configuration procedures for options present in this dialog are included later in this guide.

8. Publish your changes to the repository as described in Publishing a Template to the Repository, if applicable.

1.5.2 Configuring a Form Using "SendKeys"

To configure a Windows application form that will use the SendKeys response method, do the following:

1. Open the Logon Manager Administrative Console. By default, the shortcut is located at Start > Programs > Oracle > Logon Manager Console.

2. In the left-hand tree, select the Applications node and do one of the following:

- If you want to create a new template and define the logon form, click Add in the right-hand pane; in the New Application dialog, enter a descriptive name for the template and click Finish. The new template appears in the list of stored templates.

Caution:

If two or more application templates are named such that the name of one of the templates occurs in the beginning of the name of another template, the Agent will erroneously use the template with the shortest name to respond to all of the affected applications. To avoid this behavior, ensure that your template names do not begin with the same string of text.

- If you want to add a logon form definition to an existing template, expand the Applications node and select the desired template (the template appears in the right-hand pane), then click Add at the bottom of the pane.

3. In the Form Wizard that appears, configure the fields and controls that you want the Agent to interact with when responding to the target form. In the "Form Type"screen, select the desired form type and click Next.

4. In the "Application Window" screen, select the window that contains the target form. A thick blue border appears around the chosen window to indicate your selection.

Note:

If you see two or more windows that share the same value for any of the parameters, the Agent might erroneously respond to all of those windows, instead of only the target window. For more information on this issue, see Troubleshooting Window Detection.

5. In the "Credential Fields" screen, select the Use "Send Keys" for this form instead of IDs check box and click Next.

6. In the "Summary" screen, review your configuration choices. If you want to change any of the options you selected, click Back, otherwise, click Finish.

7. In the template properties dialog that appears, select the Fields tab.

8. Click Edit to display the SendKeys editor dialog.

9. Configure your SendKeys actions as desired. For detailed descriptions of each option, see the Console help.

Note:

To configure an action as programmatic (i.e., using the Control IDs response method) while the form is in "SendKeys" mode, enable the Inject directly into control option for the action.

10. When you have finished, click OK to save your changes and dismiss the SendKeys editor dialog.

Note:

If you want to configure additional options for the template and you are familiar with their locations and functionalities, you may do so now, if you desire. Configuration procedures for options present in this dialog are included later in this guide.

11. Click OK in the form properties dialog to save your form configuration.

12. Publish your changes to the repository as described in Publishing a Template to the Repository, if applicable.

1.5.3 Using Matching to Improve Response Accuracy

Matching is a mechanism that allows Logon Manager to uniquely distinguish a window and the form it contains from other windows and forms that may be encountered in a session. The term "matching" refers to the comparison of the values of certain parameters, such as window title or a field label, to the value stored in a template.

For example, an application might instantiate dialog boxes that serve different purposes, such as informative messages, wizards, and logon forms, but share the same window title and class; in such a case, you would configure matching against unique elements within the form to limit Agent response to that specific form.

Logon Manager allows you to match against the values of the following criteria:

- Window title, including blank and partially or fully dynamic values

- Window class, including constriction to specific values

- Executable name (also referred to as a module name)

- A field, control, or a text string

1.5.3.1 Matching for a Blank or Dynamic Value

You can use regular expressions supported by the Microsoft .NET Framework to formulate the text pattern that the Agent should recognize as a match for a criterion. Wildcards, such as ? (single character) and * (any combination of characters, excluding space), are the most commonly used regular expressions.

For example:

- Je???e will match both Jeanne and Jessie. It will not, however, match Jeanine, because neither the length of the string nor character order match.

- Je*e will match against all words that begin with Je and end with e; all three examples above are matches in this case.

- Afx:400000:0:10011:0:* will match against all window classes whose last six digits are variable. Afx:400000:0:10011:0:130927 would be a match in this case.

If the target criterion, (for example, a window title) contains one or more system variables, such as the currently logged in user name, you can use the variable name as part of the matching text pattern. For example, the following pattern will result in a match against a window title that begins with Password Expired - and includes the currently logged on user's name in uppercase:

Password Expired - %UC%%DOMAINUSER%

To match against:

- A partially or fully dynamic value, use regular expressions, environment variables, and static text, as appropriate, to create a text string that will cause a successful match against the target parameter value.

- Against a blank value, specify the null regular expression ^$ as the value.

Note:

Blank window titles are supported automatically; they do not require any special configuration.

Before completing the procedures in this section, do the following:

1. Launch the Logon Manager Administrative Console.

2. In the tree in the left-hand pane, expand the Applications node and select the desired template.

3. In the right-hand pane, select the General tab.

4. Click Edit to bring up the form properties dialog.

5. Continue to the desired procedure:

- Matching Against a Window Title

- Matching Against a Window Class

- Matching Against an Executable Name

- Matching Against a Field, Control, or Text String

1.5.3.2 Matching Against a Window Title

To match against one or more static or dynamic window titles, do the following:

1. In the template properties dialog, select the Identification tab.

2. In the "Window Titles" section, do one of the following:

- To add a new matching rule, click Add.

- To modify an existing matching rule, select the rule in the list and click Edit.

3. In the "Window Title" dialog, select the desired matching type:

- Exact matches the string strictly as entered. Use with static window titles.

- Wildcard allows matching using a combination of text and a wildcard. Use with blank or dynamic window titles.

- Regular expression allows matching using a combination of text and regular expressions. Use with dynamic window titles.

For more information, see Matching for a Blank or Dynamic Value.

4. Enter the desired text string against which the Agent will perform the match.

5. Click OK to add the new matching rule.

6. Click OK to close the properties dialog.

1.5.3.3 Matching Against a Window Class

To match against one or more static or dynamic window classes, do the following:

1. In the form properties dialog, select the Matching tab.

2. Specify the allowable window classes as follows:

- If you don't know the exact value(s) of the class(es) you want to specify, click Choose in the Allowable Class field, select the target window in the dialog that appears, and click OK. The class of the selected window populates the Allowable Class field.

- If you know the exact value(s) of the class(es) you want the Agent to recognize, enter them as a comma-delimited list into the Allowable Class field. If you want to match against one or more dynamic window classes, select the Regular Expression check box and include the desired regular expressions in the list.

3. Specify the window classes you want the Agent to ignore (i.e., never respond to) as follows:

- If you don't know the exact value(s) of the class(es) you want to specify, click Choose in the Ignore this window class field, select the target window in the dialog that appears, and click OK. The class of the selected window populates the Ignore this Window Class field.
If you know the exact value(s) of the class(es) you want the Agent to recognize, enter them as a comma-delimited list into the Ignore this Window Class field. If you want to match against one or more dynamic window classes, select the Regular Expression check box and include the desired regular expressions in the list.

4. Click OK to close the properties dialog.

1.5.3.4 Matching Against an Executable Name

To match against a specific executable name, do the following:

Note:

Matching against executable names supports exact matching only. Wildcards or regular expressions are not supported.

1. In the form properties dialog, select the Identification tab.

2. In the "AppPath Keys" section, do one of the following:

- To add a new matching rule, click Add.

- To modify an existing matching rule, select the rule in the list and click Edit.

3. In the "AppPath Key" dialog, enter the desired value and click OK.

4. Click OK to close the template properties dialog.

1.5.3.5 Matching Against a Field, Control, or Text String

Use the Matching tab to map user credentials of the currently selected logon to other logon, password-change or password-confirmation forms (referred to here as target forms) within the same application. The Agent uses the match criteria you supply to distinguish among similar forms that use the same credential data. This lets the Agent apply a single set of user credentials appropriately to these multiple forms. You can use also use matching to identify forms that the Agent should ignore.

To match for a specific field or control, do the following:

1. In the template properties dialog, select the Matching tab.

2. In the "Matches" section, do one of the following:

- To add a new matching rule, click Add.

- To modify an existing matching rule, select the rule in the list and click Edit.

3. In the Control Match Wizard that appears, select the desired matching type.

4. In the "Application Window" screen, select the target window.

5. In the "Match Fields" screen that appears, configure the desired match rules. For each field, control, or text string that you want to match against, select the desired item in the list and right-click it, then select the desired match criterion from the context menu:

- Class: instructs the Agent to match against the numeric class value of this item.

- Style: instructs the Agent to match against the numeric style value of this item.

- Text: instructs the Agent to match against the text presented by this item. When prompted, enter the desired match string into the dialog box that appears and click OK.

When you have made your selections, click Next.

6. In the "Credential Fields" screen, select and configure the credential fields and controls that the Agent will use to complete the logon upon a successful match:

1. Right-click each desired field or control and select its function from the context menu.

Note:

If a "submit" button (usually labeled OK, Logon, etc.) is not visible in the list, Logon Manager will still send a "submit" action to the application after injecting credentials.

2. If the application requires that Logon Manager interacts with its fields and controls using the "SendKeys" method, which emulates user input such as keystrokes and mouse clicks, select Use "SendKeys" for this form instead of IDs. (To determine whether your application requires this option, see Understanding Form Response.)

3. If the application requires that Logon Manager addresses its fields and controls via ordinals rather than Control IDs, select Use ordinals instead of control IDs. (To determine whether your application requires this option, see Understanding Form Response.)

4. Click Next.

7. In the "Summary" screen, review your configuration choices. If you want to change any of the options you selected, click Back; otherwise, click Finish.

1.5.4 Configuring an Application as a Service Logon

If an application window changes its contents after it has been initially detected by Logon Manager, you must configure it as a service logon.

Note:

Enabling this option will cause Logon Manager to actively poll the application's window for updates, consuming additional CPU time (compounding with each additional window being polled), and should only be used if all other detection options have been exhausted.

To configure the application as a service logon, do the following:

1. Open the desired template.

2. Select the Miscellaneous tab and check the Service Logon check box.

3. Obtain the application's window class:

1. Select the General tab,

2. In the list of form definitions, select the logon form and click Edit.

3. In the form properties dialog, select the Matching tab and note down the value present in the Allowable Class field - this is the window class detected in the application by Logon Manager.

4. Save your changes and push the updated template to the repository, if applicable.

5. Add the application's window class to the list of window classes the Agent will recognize as system services:

1. Load your global Agent settings set.

2. In the left-hand tree, navigate to Global Agent Settings > End-User Experience > Application Response > Windows Application.

3. Select the check box next to the Supported Window Classes for Services option, if it is not already selected.

4. In the field next to the above option, add the window class you noted down in step 3c to the list of existing classes, separated by a semicolon.

6. Save your changes and push the updated Supported Window Classes for Services setting to the repository as part of your administrative overrides.

1.5.5 Disabling Automatic "SendKeys" Fallback

If Logon Manager is unable to respond to an application programmatically (i.e., using the "Control IDs" method), by default it will automatically fall back to the "SendKeys" response method and retry injection. In certain scenarios, this automatic fallback behavior might be undesirable - for example, Logon Manager might inadvertently inject credentials into the wrong window or application, exposing the credentials to the end-user. To disable this automatic fallback behavior, do one of the following:

- To disable automatic "SendKeys" fallback for a specific form definition, disable the Fall back to SendKeys if direct injection fails option in the Options tab in that form's properties dialog.

- To disable automatic "SendKeys" fallback globally, set the Allow fallback from control IDs to SendKeys option under Global Agent Settings > <Target Settings Set> > User Experience > Application Response to No and publish your changes to the repository.

1.6 Testing the Configuration of a Form

Once you have created and configured a form, complete the following steps to test it before publishing:

1. In the left-hand tree, expand the Applications node and navigate to the target template.

2. Right-click the target template and select Test from the context menu.

3. In the "Logon Manager Template Test Manager" window that appears, do the following:

1. In the Forms pane, select the target form.

2. Follow the instructions displayed in the Interactions pane.

3. If the Agent responds to the application as desired and the test has completed successfully, click Finish; If the Agent is not responding to the application as desired, click Close and follow the troubleshooting flowcharts in this section to determine and correct the problem, then repeat steps 1-3 to test the corrected configuration.

1.6.1 Testing the Configuration of a Logon Form

1.6.1.1 Agent detects window?

Once the Agent has been provided with the template, it will automatically respond to the target application, unless the automatic response feature has been explicitly disabled. If the Agent fails to respond to the application, seeTroubleshooting Window Detection.

1.6.1.2 Agent injects credentials?

If credentials have been stored for the target application in the user's store, the Agent will inject them into the appropriate fields upon successful application detection. The Agent will also automatically submit the credentials unless the "Auto-Submit" feature has been explicitly disabled. If credential injection fails, see Troubleshooting Form Response When Using Control IDs and Troubleshooting Form Response When Using "SendKeys".

1.6.1.3 Logon loop occurring on logout?

Some applications display their logon screen upon logout, which causes the Agent to enter a logon loop and effectively prevents the user from logging out of the application unless the Agent is shut down. If this happens, see Troubleshooting a Logon Loop.

1.6.1.4 Agent responding properly after application is restarted?

If the target application is shut down and restarted, the Agent should respond to the application and log the user on. If logon does not occur, it is possible that the application is running in the system space instead of the user space and thus requires active polling instead of passive message queue monitoring by the Agent. If this is the case, you must follow the instructions in Configuring an Application as a Service Logon.

1.6.2 Testing the Configuration of a Password Change Form

1.6.2.1 Agent detects the window?

Once the Agent has been provided with the template, it will automatically respond to the target application, unless the automatic response feature has been explicitly disabled. If the Agent fails to respond to the application, see Understanding Window Detection.

1.6.2.2 Agent injects and submits credentials?

When the Agent detects the password change, it injects credentials into the appropriate fields and submits them to the application, unless the Auto Submit feature has been explicitly disabled. If credential injection is erratic or does not occur at all, see Troubleshooting Form Response When Using Control IDs and Troubleshooting Form Response When Using "SendKeys".

1.6.2.3 New password satisfies application's password policy?

If the new password generated by Logon Manager does not satisfy the application's own password policy, password change will be unsuccessful. If you determine this to be the case, compare the password generation policy currently deployed to the Agent with the password policy of the target application and correct any inconsistencies that may cause password change failure.

1.6.2.4 Agent responds to password change form as if it were a logon?

If the Agent responds to the password change form as if it were a logon form (i.e., Agent injects and submits the user's currently stored credentials), check for the following;

- Configuration mistakes in the template, such as incorrect form type, incorrect field and control definitions, and so on.

- Check whether the password change form has a dynamic window title or class, and configure the template accordingly.

- If you are using matching, check whether you are using the correct matching type and examine your matching strings for errors.

1.7 Publishing a Template to the Repository

Once you have successfully tested your application template, you can distribute it to end-user machines by publishing it to the selected target container within your repository, either in a directory-style hierarchy (default), or as a flat configuration file.

Note:

For more information on deploying Logon Manager with a repository and best practices for structuring the repository tree, see the guide Deploying Logon Manager with a Directory-Based Repository guide for your platform.

Before performing this procedure, make sure you are familiar with the structure and configuration of your repository.

To select and publish the desired templates and other configuration objects to the repository:

1. Launch the Logon Manager Administrative Console.

2. Right-click the Applications node and select Publish… from the context menu. The "Publish to Repository" dialog appears.

3. In the Available configuration objects list, navigate to and select the desired objects.

Note:

Only categories for which objects have been configured will appear in this list. For example, if no password generation policies exist, the corresponding category will not appear in this list.

4. Click >> to move the selected objects to the Selected objects to be published list. (To remove an object from this list and not publish it, select the object and click <<.)

5. Select the target container to which you want to publish the selected objects.
If you have previously published to the desired container, select it from the Target Repository drop-down list.

If you have not previously published to the desired container, or if the target container path does not appear in the Target Repository drop-down list, you must use the Browse feature to find and select the target container:

1. Click Browse to browse the directory tree.

Note:

If you are not already connected to the directory, the Console will prompt you to provide the required connection information.

2. In the "Browse for Repository" dialog that appears, navigate to and select the target container.

Note:

If you want to create a new container, right-click the desired parent container, select New Container from the context menu, enter the desired name for the new container, and click OK to complete the process.

6. (Optional) If your environment calls for storing configuration objects in flat-format, select the check box Store selected items in configuration files, rather than as individual objects.

Note:

Selecting this option will overwrite all items stored in existing configuration files, if present in the target container.

7. (Optional) If you want to create the first-time use object (FTUList), select the corresponding check box.

Note: This option only becomes active if you choose to store your configuration objects in flat format in step 6.:

8. Click Publish. The Console publishes the selected objects to the target repository.

Caution:

Do not attempt to dismiss the dialog or close the Console until the publishing process completes. The dialog will disappear automatically when the objects have been published.

For more information on the publishing process, see the Logon Manager Administrative Console help.

1.8 Troubleshooting Window Detection

Use the steps below to diagnose erratic window detection.

1.8.1 Agent detects the window?

If the Agent does not detect the window, first ensure that the Auto-Recognize option in the Options tab of the target form definition's properties dialog is enabled; if it is, proceed to the next step.

1.8.2 Agent responds to target window but also to other windows?

Since the Agent will respond to all windows that possess the characteristics defined in the template, a default form configuration (created by simply completing the Form Wizard) may result in undesired response to windows that should be otherwise ignored. It is critical to configure the template to be as specific as possible so that the Agent can uniquely identify the target window.

Note:

This situation is sometimes referred to as a "duplicate event model" because the Agent is facing multiple sign-on events which it cannot uniquely distinguish from one another.

To decide whether more granular response control is necessary, examine the list in the Form Wizard window for duplicate window titles, module names, and window classes when creating a template. In the following example, two instances of the "Login Tester" application share their module (parent process) names and window class values, and will thus appear as the same application to the Agent.

In such cases, you must use matching to place more specific constraints on the values of the criteria that uniquely identify the window and form to the Agent.

1.8.3 Agent detects window when using the "Logon Using Logon Manager" tray icon option?

Manually invoke window detection by using the Logon Using Logon Manager option from the Agent's system tray icon, then do one of the following:

- If the Agent detects the window, you may have to configure the application as a service logon; continue to the next step.

- If the Agent does not detect the target window even when you manually invoke detection by using the Logon Using Logon Manager option from the Agent's tray icon, review the template for common configuration errors, such as a mistyped window title or class; also, determine whether the window title and/or class are dynamic, and reconfigure the template as appropriate.

1.8.4 Application running as a service or a user other than the current?

If the application is running in the system space (under the SYSTEM account), rather than in the user space (under the currently logged in user's account), or the application has been launched under a user account different from the currently logged in user, you must configure it as a service logon. This allows the Agent to actively poll the application instead of passively responding to events in the currently logged on user's Windows message queue. For instructions, see Configuring an Application as a Service Logon.

1.8.5 Window title changes after detection?

If the title of the target window changes after the Agent has detected the window but before it begins responding to the window (for example, if the window title changes when the logon form is invoked), you must configure the application as a service logon. This allows the Agent to actively poll the application instead of passively responding to events in the currently logged on user's Windows message queue. For instructions, see Configuring an Application as a Service Logon.

1.9 Troubleshooting Form Response When Using Control IDs

1.9.1 Agent populates fields but does not submit the logon?

If the credentials are inserted by not automatically submitted, first check that the Auto-Submit option is enabled for the application. If Auto Submit is enabled but the Agent still does not submit them to the application, press Enter after the Agent has populated the fields and see whether the credentials are submitted. If the credentials are submitted, remove the Submit action from the template - this will allow the Agent to use its default submit action, the Enter keystroke.

1.9.2 Application rejects injected credentials?

If the application rejects the submitted credentials, enable WM_CHAR-style messaging in the application template - this causes the Agent to use an alternate API to interact with the fields and controls in the window. To do so, select the General tab in the template, select the target form, click Edit, and select the Use WM_CHAR messages to fill controls check box in the Options tab of the form properties dialog.

1.9.3 Fields populated erratically?

If the Agent populates the fields erratically, i.e., inserts wrong, truncated, garbled, or blank values, one or more of the target Control IDs might be dynamic. In such case, use ordinals instead of Control IDs to uniquely identify fields and controls within the form. Ordinals are sequential ID numbers assigned by the Agent to each object in the window, from top to bottom, left to right, which allow the Agent to uniquely identify the detected fields and controls separately from Control IDs.

To switch a form from using Control IDs to using ordinals, select the form in the General tab in the template, click Edit, and click Wizard in the form properties dialog. Then, follow the steps in Configuring a Form Using Control IDs to re-create the form definition but select the Use ordinals instead of control IDs check box when you arrive at the "Credential Fields" screen. The new configuration choices you make in the wizard will overwrite the existing form definition.

If the issue persists even when using ordinals, consider using the "SendKeys" method of interacting with the application. For more information, see Configuring a Form Using "SendKeys".

1.10 Troubleshooting Form Response When Using "SendKeys"

1.10.1 Pre-filled fields cause erroneous logon?

Some applications might pre-fill the logon fields when the logon form is displayed - for example, the user name field might be pre-filled with the name of the last successfully logged on user. You may have to send one or more Backspace or Delete key strokes to clear such a pre-filled field before injecting credentials into it.

1.10.2 Cursor always starts in the same field and retains focus?

If the cursor does not always start in the same field and the field loses focus before the Agent populates it, see if the application permits you to navigate to the field through a specific hotkey combination (such as Alt+U) or by using standard Windows keys, such as Tab, arrows, and so on. If you cannot use keystrokes to navigate to the field, use a mouse click action whose coordinates point to within the target field to allow the Agent to "click" within the field, as shown in the example below.

1.10.3 Multiple values injected into a single field?

If the Agent is inserting multiple values (e.g., both the user name and the password) into a single field, it might be firing the "SendKeys" actions too quickly for the application to respond properly. In such cases, experiment with slowing down the action firing rate until credential injection is reliable. To do so, either insert a "Delay" action in between other actions, or set the SendKeys event interval global Agent setting under End-User Experience >Response to either Use for slow system or Use for very slow system.

1.10.4 Switching to "SendKeys" with journal hooks restores reliable injection?

If the Agent continues injecting multiple values into a single field after you have tried the suggestions in the previous step, switch the form interaction method to "SendKeys" with journal hooks. To do so, select the General tab in the application template, select the desired form, click Edit, select the Fields tab, and set the Transfer Method option to SendKeys using Journal Hook.

Note:

The "SendKeys" with journal hooks option causes the Agent to use an alternate API to send keystrokes and mouse clicks to the application; it is typically the most effective in Citrix environments.

1.10.5 Characters missing from injected values?

If you find that individual characters are omitted from the injected field values, the Agent might be firing the "SendKeys" actions too quickly for the application to accept them properly. In such cases, experiment with slowing down the action firing rate until credential injection is reliable. To do so, either insert a "Delay" action in between other actions or set the SendKeys event interval global Agent setting under End-User Experience >Response to either Use for slow system or Use for very slow system.

1.10.6 Using mouse click actions to focus on fields results in successful logon?

If logon is still unsuccessful, consider using mouse click actions to focus on all fields and controls within the form. Be aware that because each mouse click action requires exact coordinates of the field or control you want to click, those coordinates must remain static in order for the mouse click to succeed. Thus, mouse click actions might not be reliable for windows whose contents shift when the window is resized or displayed in different resolutions.

If none of the above steps resolve your issue, contact Oracle Support for assistance.

1.11 Troubleshooting Matching

1.11.1 Target field or control recognized by Control Match Wizard?

If the field or control targeted for matching do not appear in the Control Match Wizard, even after enabling the Show all fields option, matching might not be possible. In such cases, please contact Oracle Support for assistance.

1.11.2 Non-unique or dynamic Control IDs in the form?

If one or more of the target Control IDs are non-unique or dynamic, use ordinals instead of Control IDs to uniquely identify fields and controls within the form. Ordinals are sequential ID numbers assigned by the Agent to each object in the window, from top to bottom, left to right, which allow the Agent to uniquely identify the detected fields and controls separately from Control IDs.

To switch a form from using Control IDs to using ordinals, select the form in the General tab in the template, click Edit, and click Wizard in the form properties dialog. Then, follow the steps inConfiguring a Form Using Control IDs to re-create the form definition but select the Use ordinals instead of control IDs check box when you arrive at the "Credential Fields" screen. The new configuration choices you make in the wizard will overwrite the existing form definition.

1.12 Troubleshooting a Logon Loop

Some applications display their logon form upon logout, which causes Logon Manager to recognize the logon form and automatically log you back on to the application. This creates an endless "logon loop" preventing you from logging out of the application. To prevent this loop from occurring, the administrator may choose to enable the logon grace period feature which forbids Logon Manager from logging on to an application within set time period since the last logon.

1.12.1 Post-logout form different from standard logon form?

Oracle recommends that you consider the "Logon Loop Grace Period" as well as matching if the logon form presented upon logout is sufficiently different from the application's standard logon form. (For more information on matching, see Using Matching to Improve Response Accuracy.) If the forms cannot be uniquely distinguished, use the "Logon Loop Grace Period" feature described below.

1.12.2 Configuring the "Logon Loop Grace Period" option resolves logon loop?

If the post-logout form cannot be uniquely distinguished from the standard logon form, configure a grace period that will prevent the Agent from automatically logging on to the same application if the specified grace period has not fully elapsed.

To configure the logon loop grace period timer, do the following:

1. In the Logon Manager Administrative Console, open the desired template and select the Miscellaneous tab.

2. In the Logon Loop Grace Period field, select the desired mode of operation from the drop-down list:

- Prompt - if the Agent detects the application's logon form while the grace period is in effect, the Agent will prompt the user whether to complete the logon or ignore the application.

- Silent - if the Agent detects the application's logon form while the grace period is in effect, the Agent will ignore the application and not log the user on.

- None - deactivates the grace period timer. Agent will respond to the application every time it detects the application's logon form.

3. Do one of the following, depending on what you want the Agent to do while the grace period is in effect:

- If you want the Agent to log the user on each time the launch of the application's executable is detected, select the Reset for each process check box.

- If you would like the Agent to ignore the application until the grace period has expired, leave the Reset for each process check box blank.

4. Save your changes and commit them to your repository, if applicable.

Note:

If you have configured the logon grace period timer, and logon loop is still occurring for a specific form definition, make sure that the Adhere to logon loop grace period option in the form definition's Options tab is enabled.

If this does not resolve the logon loop for the application, contact Oracle Support for assistance.

1.13 Troubleshooting Java Application Issues

Use the steps below to diagnose and resolve issues specific to Java applications.

1.13.1 Installed JRE is a supported brand and version?

Refer to the release notes for your version of Logon Manager for a list of supported JREs. If the installed JRE is not supported, you must either upgrade Logon Manager to a release that supports your current JRE, or replace the current JRE with a version supported by your release of Logon Manager.

1.13.2 Using Oracle JInitiator or another JRE not made by Oracle or IBM?

While no issues have been reported when deploying Logon Manager with Oracle JInitiator or non-Oracle/non-IBM JREs, Oracle does not support nor warrant the proper functioning of Logon Manager with such JREs.

1.13.3 JHO loaded?

In certain situations, a configuration issue might prevent the JHO from loading when the Java application launches. To verify that the JHO is installed and running, use a process viewer tool, such as Microsoft Spy++ (included with Microsoft Visual Studio) or SysInternals Process Explorer to verify that the JVM executable has spawned the ssojho.dll child thread.

The example below shows the properties box of the Sun JVM executable javaw.exe in Process Explorer showing the ssojho.dll child thread running:

If the JHO is not loading for the target JRE, check that the permissions required by the JHO are being granted through the user's .java.policy file (located in their home directory) as described in the next section.

1.13.4 Verifying and Repairing the Permissions Required by the JHO

The JHO requires that a set of specific permissions is granted to it via the user's .java.policy file so that it can properly operate in the context of the target JRE. If these permissions are not in effect, Logon Manager will be unable to detect or respond to Java applications.

1.13.4.1 Verifying That the Required Permissions Are Being Granted

Every time Logon Manager starts, the permissions are copied from a template .java.policy file (located in %INSTALLDIR%\v-GO SSO\Helper\Java) to the user's .java.policy file located in the user's home directory. These permissions are then automatically granted to the JHO every time a Java application is launched.

If you suspect that the required permissions are not being granted to the JHO, check your JRE's log after starting Logon Manager for any missing permission exceptions referencing the JHO. If such exceptions are present, the required permissions are not being granted. This can be caused by one of the following:

- The user's .java.policy file does not contain the permissions required by the JHO,

- The target JRE's security settings (usually stored in the JRE's java.security file) do not reference the user's .java.policy file.

1.13.4.2 Restoring the Missing JHO Permissions

If the user's .java.policy file is missing the required JHO permissions, the file's ACL might be preventing Logon Manager from writing the permissions to it; in such case, check the file's ACL to make sure that write privileges are not being denied.

If the ACL is correct and the required permissions are not present in the user's .java.policy file, do one of the following:

- If the user's .java.policy file contains other permissions or configuration information that you want to preserve, edit the file and manually add the missing JHO permissions.

- If the user's .java.policy file does not contain other permissions or configuration information that you wish to preserve, simply delete it and restart Logon Manager; the file will be recreated and the required permissions inserted automatically.

Note:

As JREs are updated by their vendors, it is possible that a future release introduces one or more new permissions that will be required by the JHO but which could not be accounted for at the time of Logon Manager's release. In such case, examine your JRE's error log for any missing permission exceptions after launching Logon Manager and a target Java application and add those permissions to Logon Manager's .java.policy template file so that they can be granted via the user's .java.policy file the next time Logon Manager starts.

1.13.5 Configuring the Behavior of the Java Helper Object (JHO)

Logon Manager provides global Agent settings that allow you to control the following aspects of the JHO's behavior:

- Exclude specific JRE versions

- Exclude specific JRE vendors

- Define a response delay to account for the loading of Java applets

- Define a response delay to account for the initialization of the JRE

- Define a delay between response retries

- Define a maximum number of response retries

- Define specific hierarchy, window, component and injection type events that the JHO will recognize or ignore

These settings are located in the tree in the Administrative Console at the following location:

Global Agent Settings > Live > User Experience > Application Response > Java Applications

To learn more about these settings and how to configure them, see the Console help. For even more granular control, Logon Manager also provides registry settings described in the next sections. Oracle recommends these settings be used only by experienced administrators.

1.13.5.1 Manually Restricting the JHO to Specific JREs

Aside from the Console settings described earlier, Logon Manager provides registry settings that allow you to create extremely granular inclusion and exclusion rules that Logon Manager will use to decide whether to load the JHO for the target application. You can specify, via regular expressions, the Java Virtual Machine (JVM) executables, JAR files, and command-line parameters that you want the JHO to consider.

When configuring these settings, keep the following in mind:

- If the value for a given setting is omitted, the specified default is used; if a value is set, all non-matching values are ignored.

- The JHO processes the inclusion rules first, followed by the exclusion rules.

- The N suffix is a unique numerical identifier that bundles settings belonging to a specific application. The JHO will process the bundles sequentially in ascending order. The N suffix is a positive integer starting at 1.

- You can determine the application's host JVM executable and launch command using the Trace Logging utility. The beginning of the Java trace log will indicate the host JVM and the launch command for the application.

The settings are located at the following path in the Windows Registry: HKEY_LOCAL_MACHINE\SOFTWARE\Passlogix\Extensions\AccessManager\JHO

The settings are divided into the following categories:

- JHO Inclusion Rules

- JHO Exclusion Rules

- Allowed Java Runtime Environment (JRE) Versions

1.13.5.1.1 JHO Inclusion Rules

Use these settings to specify the host JVM executables, application JAR files, and command-line parameters that will cause the JHO to load for the target application. The values are case-insensitive regular expressions.

Setting

Description

JhoIncludeHostNameN

Specifies the application's host JVM executable(s).

For example, if you want the JHO to load when the application is hosted by a JVM executable named java.exe or javaw.exe, set the value as follows: JhoIncludeHostName1=.*javaw?\.exe No-value default:

All executables are accepted (i.e., JHO will load for any executable).

JhoIncludeHostCommandLineN

Specifies the command used to launch the application. The command string usually includes the full path and name of the JVM executable, the JAR file, as well as any required command-line parameters.

For example, if you want the JHO to only load when the application's JAR file is named Login.jar (while the rest of the command is allowed to vary), set the value as follows: JhoIncludeHostCommandLine1=.*Login\.jar.* No-value default: All command strings accepted (i.e., JHO will load for any command).

1.13.5.1.2 JHO Exclusion Rules

Use these settings to specify the host JVM executables, application JAR files, and command-line parameters that will cause the JHO to ignore the target application. The values are case-insensitive regular expressions.

Setting

Description

JhoExcludeHostNameN

Specifies the application's host JVM executable(s).

For example, if you want the JHO to ignore the application when the host JVM executable is named "java.exe" or "javaw.exe", set the value as follows: JhoExcludeHostName1=.*javaw?\.exe No-value default: Blank (i.e., nothing will cause the JHO to ignore the application)

JhoExcludeHostCommandLineN

Specifies the command used to launch the application. The command string usually includes the full path and name of the JVM executable, the JAR file, and any required command-line parameters.

For example, if you want the JHO to ignore the application when its JAR file is named "Login.jar" (but the rest of the command is non-consequential), set the value as follows: JhoExcludeHostCommandLine1=.*Login\.jar.* No-value default: Blank. (i.e., nothing will cause the JHO to ignore the application)

1.13.5.1.3 Allowed Java Runtime Environment (JRE) Versions

These settings allow you to specify the desired JRE/JDK versions for which the JHO will load; all versions falling outside of the specified range will be ignored and the JHO will not load.

The values for both settings must follow the format x.y.z, where:

- x is the major revision

- y is the minor revision

- z is denotes the release type (feature, maintenance, or update) and build ID of the installed JRE (for example, 1.6.0_07)

Setting

Description

JhoMinimumJavaVersion

Specifies the lowest allowed JRE/JDK version.

Default value:

1.2 (the earliest JRE version supported by the JHO)

JhoMaximumJavaVersion

Specifies the highest allowed JRE/JDK version.

Default value:

Blank (i.e., no upper JRE version limit is imposed)

1.13.5.2 Manually Customizing the Event Response Behavior of the Java Helper Object (JHO)

Aside from the settings provided in the Console, Logon Manager provides registry settings that control the event response behavior of the JHO at an even more granular level. You can use these settings to troubleshoot and optimize Logon Manager performance when responding to Java applications by modifying the JHO's response to specific events when a Java application has been detected.

The settings are located within the following key in the Windows registry: HKEY_LOCAL_MACHINE\SOFTWARE\Passlogix\Extensions\AccessManager

1.13.5.2.1 Event Response Configuration Settings

Setting

Description

JhoHierarchyEventProcessing

Determines which Java hierarchy events are recognized. Set the flag as follows:

HIERARCHY_EVENT_CHANGED = 0x1

The above value instructs the JHO to recognize all hierarchy events.

JhoEventWaitTimeout

Determines the event processing timeout for JHO controls (in milliseconds). The default value of 0 instructs the JHO to wait indefinitely.

JhoWindowEventProcessing

Determines which Java window events are recognized. This flag is a combination of the following values:

· WINDOW_EVENT_OPENED = 0x1

· WINDOW_EVENT_CLOSED = 0x2

· WINDOW_EVENT_ACTIVATED = 0x4

· WINDOW_EVENT_DEACTIVATED = 0x8

· WINDOW_EVENT_CLOSING = 0x10

· WINDOW_EVENT_ICONIFIED = 0x20

· WINDOW_EVENT_DEICONIFIED = 0x40

By default, all window events are recognized.

JhoComponentEventProcessing

Determines which Java component events are recognized. This flag is a combination of the following values:

· COMPONENT_EVENT_SHOWN = 0x1

· COMPONENT_EVENT_HIDDEN = 0x2

· COMPONENT_EVENT_ADDED = 0x4

· COMPONENT_EVENT_REMOVED = 0x8

By default, all component events are recognized.

JhoInjectType

Determines the injection type used by the JHO to submit data to the controls. This flag takes one of the following values:

· INJECT_TYPE_DEFAULT = 0

· INJECT_TYPE_METHOD = 1

· INJECT_TYPE_ACCESSIBLE = 2

· INJECT_TYPE_NONACCESSIBLE = 3

· INJECT_TYPE_ROBOT = 4

By default this flag is set to INJECT_TYPE_DEFAULT, in which case the JHO attempts injection using each of following methods, in the order shown, until injection is successful:

· INJECT_TYPE_METHOD (if an appropriate set method had been found for the control)

· INJECT_TYPE_ACCESSIBLE (if the control supports accessibility)

· INJECT_TYPE_NONACCESSIBLE

· INJECT_TYPE_ROBOT

For combo and list boxes, the JHO always uses INJECT_TYPE_METHOD.

1.13.5.2.2 Recommended JHO Event Response Configuration Defaults

We recommend the following default settings on new installations of Logon Manager:

- JhoWindowEventProcessing=0x3

- JhoComponentEventProcessing=0xB

- JhoHierarchyEventProcessing=0x0

These values instruct the JHO to recognize the following events:

- WINDOW_EVENT_OPENED (0x1)

- COMPONENT_EVENT_SHOWN (0x1)

- WINDOW_EVENT_CLOSED (0x2)

- COMPONENT_EVENT_HIDDEN (0x2)

- COMPONENT_EVENT_REMOVED (0x8)

2 Configuring and Diagnosing
Web Application Templates

This chapter explains the concepts necessary to understand how and why you should configure Web application templates to solve specific sign-on scenarios, as explained later in this chapter, as well as the recommended best-practice procedures for configuring and testing Windows application forms, and diagnosis and resolution steps for the most common issues that may cause the Agent to erratically detect and/or respond to Web forms.

This chapter covers the following topics:

- Overview of a Sign-On Event

- Understanding Web Form Detection

- Understanding Form Response

- Determining the Optimal Configuration for a Form

- Configuring a Form

- Testing the Configuration of a Form

- Publishing a Template to the Repository

- Troubleshooting Web Form Detection

- Troubleshooting Form Response when Using Control IDs

- Troubleshooting Form Response When Using "SendKeys"

- Troubleshooting Detection Matching

- Troubleshooting a Logon Loop

- Troubleshooting Java Application Issues

Tip:

If the steps in this chapter do not resolve your issue, you can troubleshoot further by tracing and logging the activity of Logon Manager and submitting the logged information to Oracle Support for analysis. For this purpose, Oracle provides the Trace Controller utility, available from Oracle Support. For information on how to use the utility, see the "Using the Trace Controller Utility" topic in the Enterprise Single Sign-On Suite Administrator's Guide.

2.1 Overview of a Sign-On Event

Logon Manager can be configured to detect and respond to a wide range of sign-on events, such as logon, password change, and variations of thereof; support is provided for a diverse range of forms, fields, controls, and event flows.

In order to recognize Web forms, Logon Manager monitors the running Web browser(s) and detects whenever a Web page has completed loading in the browser.

For each completely loaded page, Logon Manager does the following:

1. Detects the target Web page and form. Whenever a new URL is accessed through the browser being monitored, Logon Manager:

1. Examines the page URL and compares it to the URLs stored in all available Web application templates.

2. Loads the first template that matches the detected URL.

3. Examines the page's Document Object Model (DOM) and identifies each field and control configured in the form definition.

4. (Optional) Examines the page's source code and performs any additional matching configured in the form definition.

2. Agent responds to the form and completes the logon. When detection is complete and a positive match is found, the Agent follows the configuration stored in the template to determine how to interact with the fields and controls in the form. Typically, the Agent does the following:

1. Retrieves the associated credentials from the user's store (if they exist) and injects them into the appropriate fields. (If the credentials don't exist, the Agent prompts the user to store them.)

2. Performs the actions necessary to submit the credentials to the application for processing.

3. (Optional) Detects any follow-up forms, such as logon or password change success or failure messages, and performs the required action.

2.2 Understanding Web Form Detection

In order to communicate with the installed Web browser(s), Logon Manager uses helper objects that hook into the browser(s) and provide Logon Manager with a means of querying the browser for data, such as the page URL, DOM, and HTML source, as well as inject credentials into the target fields and submit them upon successful detection.

The helper objects run as the following background processes:

- For Microsoft Internet Explorer: SSOBHO.EXE

- For Mozilla Firefox: SSOWEBHO.EXE

Whenever the Web browser completes loading a page, the respective helper object notifies Logon Manager of this event and a 500ms grace period timer starts. During this grace period, one of the following happens:

- If the current page is not refreshed or another page does not begin loading, Logon Manager begins detection.

- If the current page is refreshed, or if another page begins loading, Logon Manager restarts the timer and waits until the page has finished loading before beginning detection.

Note:

If the page is refreshed or another page starts loading after detection has begun, Logon Manager aborts detection and waits for the page to finish loading, then starts the 500ms grace period timer and waits for it to elapse as described above.

Usually, the browser's status bar, located at the bottom of the browser window, indicates the page has completed loading by displaying an appropriate message, such as "Done" or "Finished."

Once detection begins, Logon Manager examines the following characteristics of the page for comparison against available templates:

- URL

- Target fields and controls

- (Optional) Any additional matching criteria, such as text, HTML code, and element attributes, which have been configured in the template for the target form.

Note:

An application template is a set of configuration options that instruct the Logon Manager Agent how to detect and respond to Web application forms in order to successfully complete the logon.

Keep in mind that in situations listed below you will have to configure your application as a Windows application instead of as a Web application:

- You are using Internet Explorer and the target form is implemented as an ActiveX control

- You are using Mozilla Firefox and the target form is displayed using the browser's built-in authentication dialog

See Configuring and Diagnosing Windows Application Templates for more information.

2.2.1 Supported Form Types

As of the release date of this document, Logon Manager supports the following types of forms in Web applications:

- Logon

- Logon success (a message confirming successful logon)

- Logon failure (a message indicating the injected credentials have been rejected)

- Password change

- Password change success (a message confirming successful password change)

- Password change failure (a message indicating the new password was rejected)

A single template can contain definitions for the multiple forms that the Web application can display. For most applications, you need to only define the forms to which you want Logon Manager to respond.

Note:

Defining a form comprises providing unique identification criteria, specifying the action to take when the form is detected, and the specific way in which the action (e.g., injecting credentials) should be performed.

Logon Manager can automatically populate the appropriate fields in a form with credentials retrieved from the user's credential store, as well as operate the form's controls to submit the credentials to the application for processing. Configuration options that instruct the Agent how to interact with the form's fields and controls are stored in the template.

2.2.2 Understanding URL Detection

The first criterion Logon Manager considers during Web form detection is the Web address, or URL of the target page. This is usually the address you see in the browser's address bar after the page has finished loading, though in certain scenarios you might find that the actual URL you really want to specify in your form definition is the URL of an element of a page, such as the container or form element (these terms are explained in the next section) that actually contains the logon fields and controls.

A page URL is structured as follows:

Depending on the way the Web application has been deployed, the URL can be static or partially dynamic. For example, a simple Web application might be deployed on a single Web server that has a static host name and exists as a single HTML page, as in the example shown above. In such case, you can configure the form definition to match against such a URL and enjoy a working template.

Many enterprise Web applications, on the other hand, are deployed on multiple servers that are load-balanced or clustered, and the individual instance URLs are masked behind a single entry URL.

For example, while the URL used to access the Web application might simply be

the actual URLs to the individual load-balanced instances might be

Most enterprise Web applications employ active scripting technologies, such as JavaScript or PHP, to pass data back and forth between the browser and the Web server and/or database. Such applications will employ one or more dynamic parameters, or variables, such as unique session IDs, in the page URL.

For example:

Some applications stack URL variables by separating them with a variable delimiter symbol, usually an ampersand (&):

In most enterprise Web application scenarios, you will find the combination of dynamic host names and dynamic parameters, and will need to account for both in order to successfully configure your form definition. Logon Manager allows for matching against dynamic URLs via regular expressions, as well as a global Agent setting that determines the URL matching precision used by Logon Manager for all Web applications.

2.2.2.1 Understanding URL Matching Precision

URL matching precision determines how many segments of the host URL, counting from right to left, within a page URL are considered during detection.

For example, at the default precision level of 2, if the host name URL is application URL is

then both the above host URL as well as the URLs of the individually-hosted instances of the application shown below will be positive matches for the template:

This is equivalent to masking the last segment of the host URL either via a wildcard:

or via regular expression:

Note:

Certain URLs might include Top Level Domains (TLD) that consist of two segments (e.g., .co.uk for England, .co.au for Australia, and so on) instead of the typical single-segment TLD (e.g., .com, .net, and so on). In such cases, you must consider the extra segment in the host URL when configuring URL matching precision and/or Web application templates.

If you increase URL matching precision to 3, then Logon Manager will match against three consecutive segments of the host URL - in our example, it will match the entire host name exactly as it appears:

Variations in the server name will thus not be permitted and anything other than the exact host URL configured in the template will be rejected by Logon Manager during detection. In our example, the URLs of the individual instances of the Web application shown above would not constitute positive matches.

Follow these guidelines when determining the optimal URL matching precision for your environment:

- If the URL matching precision is set too low, Logon Manager may mistake one intranet application for another and respond with incorrect credentials.

- If URL matching precision is set too high, an application served through a distributed infrastructure with unique host names may be erroneously recognized as separate applications due to the varying host URL.

- Typically, set URL matching precision to 5 (the maximum value). This will ensure that Logon Manager only responds when the URL of the application requesting logon exactly matches the URL stored in the template. The auto-recognize feature will have limited functionality.

- If you want to get the maximum benefit from Logon Manager's auto-recognize feature for Web applications, leave URL matching precision at its default value of 2. However, response to intranet applications might be impaired.

Logon Manager allows you to set the URL matching precision level globally via the Administrative Console. The option is located under Global Agent Settings > End-User Experience >Response > Web Apps. For more information on configuring the Agent and publishing your changes to end-user machines, see the section "Configuring Logon Manager" in the Enterprise Single Sign-On Suite Administrator's Guide..

2.2.2.2 Obtaining the URL of a Page, Element, or Pop-Up

In certain situations, the URL of a page or element within a page might not be readily obtainable, but is necessary to complete the form definition in the template. For example, you might need to obtain the URL for:

- An embedded form that loads from a different URL than the URL of the Web page

- A logon processing script that passes data back and forth between the browser and the Web server and/or database

- An image, or an embedded multimedia object

- A pop-up

In such cases, do one or more of the following to obtain the desired URL:

- Hit F11 to display the browser's address bar, if it is not visible

- Right-click within the object or form and select Properties; the Properties dialog might reveal the object's URL

- Examine the HTML source code of the page after it has completed loading and find the object in question

- Use a third-party tool, such as HTTPWatch or URL Getter to obtain the URL of the element, especially if the URL is partially dynamic. In some cases, viewing the source code of the page might be enough to obtain the complete URL of the object in question.

2.2.3 Understanding Field Detection

Once Logon Manager has positively matched the detected URL to a template, it examines the page's Document Object Model (DOM) in order to detect the fields configured in the form definition.

For each field and control, the Agent looks at the name or ordinal of:

- The parent frame element

- The parent form element

- The target field element

In order for a field to be successfully identified, all three values must match the values configured in the form definition in the template. The figure and corresponding code example below illustrate the structure of a simple Web page containing a logon form.

Note:

The vast majority of today's Web pages no longer use frames to sub-divide their content. For detection purposes, Logon Manager treats the <html> container as the master frame in the page, identifying it with the ordinal value of 0. In most cases, you will never have to change that value.

Note the hierarchical, nested structure of the code which corresponds to the parent-child relationship of the elements of the rendered page.

Note:

Each pair of opening and closing tags in the above example is an element - a piece of code that constitutes a functional entity within the page, for example a frame, a form, or a field.

When you configure a form definition in a template manually, you can identify the frame, form, and field elements to Logon Manager by:

- Value of the element's name attribute, or, if not specified,

- Ordinal, an index number assigned by Logon Manager to elements of each supported type according to the order in which they appear in the page's DOM.

2.2.3.1 Understanding HTML Elements

As mentioned in the previous section, an element in HTML is a piece of code that constitutes a functional entity within the page, for example a frame, a form, or a field. An element can be a single line of code - a single tag such as <input>, or consist of an opening and closing tag, such as <div>…</div> and everything in between those tags.

For example, a typical <input> element looks as follows:

Note the code after the element declaration ( <input) - these are the element's attributes. Each attribute has a name and value in the form:

The straight double-quotes (inch-marks) are required for the attribute value to be recognized.

2.2.3.2 Understanding the Frame Element

A frame is a legacy container that allows the sectioning of a Web page by defining a frameset and specifying the size of each frame and the HTML document that it will display. The vast majority of Web sites today no longer employ this technique and use logical containers defined in the XHTML standard, such as <div> and <table> in tandem with CSS formatting to achieve sectioning. Therefore, in most scenarios, you will notice that Logon Manager treats the <html> container as the master (and only) frame in the page, identifying it as frame 0.

When configuring your fields and detection matching rules, you will not have to change the frame identifier, unless your Web application is a legacy application and specifically requires this - for example, it uses a logon form that exists as a standalone HTML document and is displayed in a frame in the parent Web page. You can identify such a page by examining its DOM or source and looking for the frameset definition, denoted by the <frameset> tag. An example of a frameset definition looks as follows:

A frame can be identified by the <frame> tag:

2.2.3.3 Understanding the Form Element

A <form> element defines an HTML form, which is a logical entity containing one or more input fields (described in the next section).

A <form> element definition references a script or another resource that accepts and processes the values entered into those fields and submitted through the browser.

For example:

In our example, the logon_form.html page handles the user authentication; when the user submits the form, the logon_form.html receives the values entered into the form's input fields and executes the appropriate authentication logic.

2.2.3.4 Understanding the Input Elements Supported by Logon Manager

Typically, an HTML form field is defined as an input element of a specific class, denoted by the tag and type attribute used to define the element. When configuring a form definition, Logon Manager recognizes the following element types:

Logon Manager Field Type

Input Element Types Accepted by the Logon Manager Field Type

· User name/ID

· Password

· Third Field

· Fourth Field

· Text - a text field identified by the <input> tag of type="text". Text entered into this field is unmasked.

· Password - a text field identified by the <input> tag of type="password". Text entered into this field is masked.

· Select-one - a list field identified by the <select> tag that permits the selection of a single list item as its value.

· Select-multiple - a list field identified by the <select multiple … > tag that permits the selection of one or more list items as its value.

· Submit

· Submit - a button control identified by the <input> tag of type="submit". Executes the code specified in the action attribute of the <form> tag (usually, calls an HTML document or script that contains the application's logon logic.)

· Button - a button control identified by the <input> tag of type="button". Functionally identical to the submit type <input> element, except allows a greater degree of styling.

· Image -a hyperlinked image identified by the <input> tag of type="image" that executes the referenced link when clicked.

· IMG -an image identified by the <img src= tag and wrapped in either an anchor (<A HREF=) tag or JavaScript onClick action which executes the submit URL when clicked.

· Anchor - the most common manifestation of a text hyperlink (by default, appears as blue underlined text in a page). Identified by the <A HREF="…"> tag.

2.2.4 Recommended Page Inspection Tools

When provisioning Web applications, Oracle highly recommends obtaining a page inspection tool that will display the page's DOM (and optionally, source code) in an easily navigable and searchable manner, allowing for much easier and faster understanding of the page's structure.

2.2.4.1 DOM Inspector for Mozilla Firefox

An example of such a tool is the DOM Inspector add-on for Mozilla Firefox. The DOM of our example page would appear in DOM Inspector as follows:

The hierarchical structure of the page is displayed in a navigable tree in the left pane and clicking an element highlights it in the browser window and displays the element attributes and their values in the right pane, making it easy to identify and understand target page elements without sifting through the page's source code. This tool is especially useful for large, complex pages.

The DOM Inspector is available from the Mozilla Firefox Add-Ons site at http://addons.mozilla.org.

2.2.4.2 Firebug for Mozilla Firefox

A more advanced and flexible tool similar to DOM Inspector is the Firebug add-on for Mozilla Firefox. Firebug sports all of the features of DOM inspector and adds full source code display in the DOM tree including visual highlighting of each code element on mouse-over. Users can also modify the code and see the changes in the browser window. While Firebug is aimed mainly at Web developers, it can prove itself invaluable during analysis of complex Web pages.

Firebug is available from the Mozilla Firefox Add-Ons site at http://addons.mozilla.org.

2.2.5 Understanding Detection Matching

If the URL and the elements discussed above are not enough to uniquely identify a logon form within a page, you may specify additional detection criteria to further narrow down the detection scope via matching. The term "matching" refers to the comparison of the values of certain parameters, such as element names or attribute values, to the values stored in the application's template.

For example, if a Web application is down for maintenance, attempting logon may result in the logon form being redisplayed with an error message indicating the reason of the logon failure. To prevent Logon Manager from repeatedly attempting logon in such a scenario, you would define two logon forms in the template and use text matching in one of the definitions to match against the error message text and instruct Logon Manager to ignore the logon form displaying the error.

Note:

This section explains the principles behind the matching mechanism necessary to successfully configure matching for a Web application. For actual instructions in configuring matching via the Console, see Configuring Additional Field Detection Criteria.

Logon Manager allows you to match against:

- Text displayed on the page

- HTML code within the page's source code

- Names and values of attributes of page elements

To illustrate the above matching types, we will use the example from pp. 15-16. The example displays a header, "Enterprise Web Application," which is implemented as a <div> container to allow for easy inline-styling of that specific piece of text:

2.2.5.1 Detection Matching vs. Offset Matching

Logon Manager offers two kinds of matching, detection, and offset. In almost all scenarios, you will always use detection matching, and never offset matching. The latter is useful for legacy pages using framesets in which frames are not identified by a name attribute. In such case, Logon Manager will assign ordinals to the frames in the order the frames appear in the page's DOM. To match on elements within a specific frame in such a frameset, you would specify its ordinal as the value for the Offset Start parameter in the Matching tab of the form definition dialog.

2.2.5.2 Matching Against Text on the Page

The most commonly used matching mode, you can match against the header text itself, regardless of its formatting. For example, to match against "Enterprise Web Application" by configuring the matching rule as follows:

- Tag: div

- Criteria: Text

- Value: Enterprise Web Application

- Match whole value: Yes

- Use regular expression: No

In this configuration, the following will be matched:

2.2.5.3 Matching Against HTML Code in the Page's Source

The HTML matching mode allows you to match against any piece of code within the page's source code. Most common use of this mode is to match against rendered text including its markup, but can also be used for matching a specific piece of code that is unique to the page.

Note:

Due to the nature of the HTML specification, Logon Manager cannot match on a <span> tag.

For example, to match against "Enterprise Web Application" but not "Enterprise Web Application", you would set up your matching rule as follows:

- Tag: div

- Criteria: HTML

- Value: <b>Enterprise Web Application></b>

- Match whole value: Yes

- Use regular expression: No

This configuration would result with the following match:

Note:

The Match Whole Value option forces Logon Manager to match against the complete string entered in the Value field, and is enabled by default. To allow for partial matches on the page, (e.g., <b>Enterprise), disable this option.

To match against the entire opening tag of the above <div> container, you would specify it as the criterion value and specifying its parent element as the tag:

- Tag: body

- Criteria: HTML

- Value: <div id="page-header"…

- Match whole value: Yes

- Use regular expression: No

This would result in the following match:

2.2.5.4 Matching Against Names and Values of Element Attributes

You can also match against a specific attribute or its value within an element. For example, you can match against the value of the id attribute of the <div> element:

- Tag: div

- Criteria: Attribute

- Attribute name: id

- Value: page-header

- Match whole value: Yes

- Use regular expression: No

This would result in the following match:

Leaving the Value field blank would, however, result in a match on the attribute name:

2.2.5.5 Constructing Complex Rule Chains Using Logic Operators

Logon Manager allows you to chain individual matching rules using Boolean logic operators to create complex rule chains that only result in a positive match in a very specific set of circumstances.

For example, you may want to create a match rule chain for a password change form that displays a success message when the password has successfully been changed, while still displaying the password change fields and controls. In such case you would want Logon Manager to ignore the form once the success message is displayed so that Logon Manager does not enter a password change loop, while retaining proper response to the standard password change form.

To accomplish this, you would create the following rules:

- A NOT match rule for the success message text, which will cause Logon Manager to ignore the form, and

- An AND match rule for any text on the form that will result in a positive match and cause Logon Manager to respond when the success message is not present.

Based on our example, you would configure the above rules as follows:

Rule 1

- Tag: html

- Criteria: Text

- Value: Logon error

- Match whole value: Yes

- Use regular expression: No

- Operation: NOT

Rule 2

- Tag: html

- Criteria: Text

- Value: Enterprise Web Application

- Match whole value: Yes

- Use regular expression: No

- Operation: AND

Note:

When defining a NOT match rule, you must always follow it with an AND rule that will result in a positive match. Otherwise, Logon Manager will not respond to the form.

Other common matching rule chaining examples are shown below. To get a positive match on:

- Rule 1 AND Rule 2 - configure both rules with the AND operator, in that order.

- Rule 1 OR Rule 2 - configure Rule 1 with the AND operator and Rule 2 with the OR operator, in that order.

- Rule 1 AND Rule 2 but NOT Rule 3 - same as above. Place the NOT rule first in the chain, followed by the two AND rules.

- Rule 1 OR Rule 2 but NOT Rule 3 - configure Rule 1 as an AND rule, Rule 2 as an OR rule, and Rule 3 as a NOT rule, then place the NOT rule first in the chain, followed by the AND rule and the OR rule.

2.2.6 Using Wildcards to Configure Detection Criteria

Wildcards, such as ? (single character) and * (any combination of characters, excluding space), are the most commonly used methods of accounting for dynamic detection criteria. Use the Wildcard option when configuring a criterion in a form definition and follow the guidelines below:

- Je???e will match both Jeanne and Jessie. It will not, however, match Jeanine, because neither the length of the string nor character order match.

- Je*e will match against all words that begin with Je and end with e; all three examples above are matches in this case.

- webapp*.company.com will match against all URLs that contain a host name that starts with webapp. This technique is useful for matching against the URLs of applications that are load-balanced and masked via a common URL and load from a different physical host each time they are accessed, causing the URL to vary.

2.2.7 Using Regular Expressions to Configure Detection Criteria

You can also use regular expressions supported by the ATL framework to formulate the text pattern that Logon Manager should recognize as a match for the criteria discussed earlier in this guide. (Use the Regular expression option when configuring a criterion in a form definition.) For your reference, the most commonly used operators and meta-characters are listed below:

Expression

Description

[ ]

Indicates a character class that matches any character inside the brackets.

Example: [abc] matches "a," "b," and "c."

( )

Indicates a character grouping operator.

Example: (\d+,)*\d+ matches a list of numbers separated by commas, such as "1" or "1,23,456".

{ }

Indicates a match class.

|

Separates two expressions, exactly one of which matches.

Example: T|the matches "The" or "the".

.

Matches any single character.

^

If ^ occurs at the start of a character class, it negates the character class. A negated character class matches any character except those inside the brackets.

Example: [^abc] matches all characters except "a", "b", and "c".

If ^ is at the beginning of the regular expression, it matches the beginning of the input.

Example: ^[abc]will only match input that begins with "a," "b," or "c".

$

At the end of a regular expression, $ matches the end of the input.

Example: [0-9]$ matches a digit at the end of the input.

-

In a character class, a hyphen indicates a range of characters.

Example: [0-9] matches any of the digits "0" through "9."

!

Negates the expression that follows.

?

Indicates that the preceding expression is optional: it matches once or not at all.

Example: [0-9][0-9]? matches "2" and "12".

+

Indicates that the preceding expression matches one or more times.

Example: [0-9]+ matches "1," "13," "666," and so on.

*

Indicates that the preceding expression matches zero or more times.

??,+?,*?

"Non-greedy" versions of ?, +, and *. These match as little as possible, unlike the greedy versions that match as much as possible.

Example: Given the input <abc><def>, <.*?> matches <abc> while <.*> matches <abc><def>.

\

Escape character that forces the next character to be interpreted literally.

Example: [0-9]+ matches one or more digits, but [0-9]\+ matches a digit followed by a plus character).

If \ is followed by a number n, it matches the nth match group (starting from 0).

Example: <{.*?}>.*?</\0> matches <head>Contents</head>.

The \ is also used for abbreviations, the most common of which are shown below:

2.3 Understanding Form Response

Once Logon Manager has successfully identified the Web form and its input fields, it uses the appropriate helper object to populate the target fields and actuate the submit control in the form. Depending on how the Web page is coded, you will want to use one of the response methods described below.

2.3.1 Control IDs

This is the default and preferred form response method for most Web applications. This method allows Logon Manager to use the browser's API to programmatically inject the appropriate credentials into the target fields, and engage the submit control.

However, if a Web page is written in a way that hampers or even prohibits Logon Manager's ability to programmatically interact with the form's fields and controls, and/or if there are additional actions required to complete the sign-on event, such as selecting a check box or manually setting focus on a specific field, you may also have to use the "SendKeys" method, in tandem with the "Control IDs" method, to interact with the form.

2.3.2 "SendKeys"

This method allows the Agent to interact with the target form by emulating user input, such as keystrokes and mouse clicks. Use this method if the Agent is unable to programmatically interact with the form's fields and controls. For example, if the logon form is implemented using Adobe Flash, you will need to send mouse-clicks to select the target fields, send keystrokes to populate them, then send a final mouse-click to engage the submit control.

2.3.3 Control IDs with "SendKeys"

This method is a "best-of-both-worlds" combination of the two above methods and is the preferred way of solving sign-on scenarios that require actions that cannot be performed programmatically. Control IDs are used to interact with the form wherever possible, while keystrokes and mouse clicks are sent to accomplish tasks such as setting field focus, selecting a check box, and other actions that the Agent cannot perform programmatically within the target application.

For example, if fields must be populated in a specific order due to cascading validation (i.e., the password field becomes active only once the user name field has been populated), you would use the "Control IDs to inject credentials into the fields, but send a Tab keystroke via "SendKeys" between each field injection to advance field focus.

Note:

To achieve this "mixed" mode, configure the form to initially use the "SendKeys" response method , then configure the desired "SendKeys" actions; while configuring the actions, enable the Inject directly into control option for actions that you wish to retain the "Control IDs" programmatic response method.

2.4 Determining the Optimal Configuration for a Form

When Configuring a Form, use the information in this section to determine its optimal configuration based on the requirements and features of the target application.

2.4.1 Determining the Optimal Configuration for a Logon Form

2.4.1.1 Target fields and controls appear in the Web Form Wizard?

In most situations, the Web Form Wizard successfully detects and displays the credential fields and controls present in the target form. If some or all fields or controls are missing, do one of the following:

- If no fields or controls are visible in the Form Wizard, the logon form has a separate URL or is in a pop-up. Obtain this URL as described in Obtaining the URL of a Page, Element, or Pop-Upand supply it to the wizard instead of the page's main URL.

- If the submit controls are not recognized, enable the "Show Anchor Tags" option to reveal controls implemented as anchor (i.e.,<A HREF=) tags.

- If fields are still not visible, contact Oracle Support to obtain further assistance.

2.4.1.2 Non-unique or dynamic field names?

If the names of the target field elements are non-unique or dynamic, use ordinals instead of element names to identify the fields to Logon Manager. Examine the page's DOM and/or source code to determine whether this is the case. For more information, seeUnderstanding Field Detection.

2.4.1.3 Dynamic page or element URL?

If the URL of the page or form element is dynamic, you will need to use wildcards or regular expressions to limit Agent response to the desired URL or range of URLs. For more information, see Understanding URL Detection.

2.4.1.4 Logon form is a Flash applet?

If the logon form has been implemented in Adobe Flash, Logon Manager will not be able to programmatically interact with its fields and controls; in such cases, use the "SendKeys" method to interact with the form.

2.4.1.5 "Submit" control is an image?

If the "submit" control is an image whose URL is dynamic (i.e., the image is hosted in a distributed environment and the host name portion of its URL is not static), you must use wildcards or regular expressions to specify the desired range of URLs as valid for the control; otherwise, Logon Manager will stop detecting the control as soon as the control URL deviates from the original static value used for configuring the template. For more information, see Understanding URL Detection.

2.4.1.6 Other fields on the page besides target fields?

If there are other input fields and controls on the page aside from the target fields, use matching to limit Agent response to the desired fields. For more information, see Configuring Additional Field Detection Criteria.

2.4.1.7 Application displays a logon success and/or failure message?

Some applications display a message indicating whether logon was a success or a failure. In such cases, define a logon success and/or a logon failure form in the application template.

2.4.2 Determining the Optimal Configuration for a Password Change Form

2.4.2.1 Logon and password change forms on the same screen?

Some applications might present password change forms that also contain logon-related fields or controls, such as a user name field or a Change Password button, which invokes the application's password change (PWC) form. If the Auto Submit feature is enabled and the Agent responds to such application, the user is logged in automatically without being given the option to change the password.

In order to allow the user to select the desired course of action, define the logon and password change forms in the template. The Agent will prompt the user for the desired course of action (logon or password change) when it responds to an application with consolidated logon and password change forms.

Note:

You also have the option to configure a grace period for the "action chooser" feature, during which the Agent will automatically assume that logon is the preferred action and log the user on without prompting to choose the desired action. This option, named Action Chooser Grace Period, is available in the Miscellaneous tab in the application template dialog.

2.4.2.2 Action required to initiate password change?

If the form requires an action to initiate password change, such as selecting a checkbox, due to the nature of Web applications, Logon Manager may not be able to complete that action programmatically. In such cases,, use the "SendKeys" method to interact with the target control if possible; otherwise, instruct users to perform the require action manually.

2.4.2.3 Target fields and controls appear in the Web Form Wizard?

In most situations, the Web Form Wizard successfully detects and displays the credential fields and controls present in the target form. If some or all fields or controls are missing, do one of the following:

- If no fields or controls are visible in the Form Wizard, the logon form has a separate URL or is in a pop-up. Obtain this URL as described inObtaining the URL of a Page, Element, or Pop-Up and supply it to the wizard instead of the page's main URL.

- If the submit controls are not recognized, enable theShow Anchor Tagsoption to reveal controls implemented as anchor (i.e.,<A HREF=) tags.

- If fields are still not visible, contact Oracle Support to obtain further assistance.

2.4.2.4 Application requires confirmation of new password?

Some applications prompt the user to confirm the new password when performing a password change. If the target application displays such a form, define a second logon form in the template and configure it to respond to the password confirmation form.

2.4.2.5 Need to inject the same data into more than one field?

If you need to inject the same data into more than one field, .e.g., the form contains a "Password" and a "Confirm Password" field and you want the Agent to inject the new password into both of them, enable the Allow Multiple Field Designation option in the Web Form Wizard and assign the fields accordingly.

2.4.2.6 Application displays a password change success and/or failure message?

Some application display a message indicating whether password change was a success or a failure. In such cases, define a password change success or a password change failure form in the application template.

2.4.2.7 Non-unique or dynamic field names?

If the names of the target field elements are non-unique or dynamic, use ordinals instead of element names to identify the fields to Logon Manager. Examine the page's DOM and/or source code to determine whether this is the case. For more information, see Understanding Field Detection.

2.4.2.8 Dynamic page or element URL?

If the URL of the page or form element is dynamic, you will need to use wildcards or regular expressions to limit Agent response to the desired URL or range of URLs. For more information, seeUnderstanding URL Detection.

2.4.2.9 "Submit" control is an image?

If the "submit" control is an image whose URL is dynamic (i.e., the image is hosted in a distributed environment and the host name portion of its URL is not static), you must use wildcards or regular expressions to specify the desired range of URLs as valid for the control; otherwise, Logon Manager will stop detecting the control as soon as the control URL deviates from the original static value used for configuring the template. For more information, seeUnderstanding URL Detection.

2.4.2.10 Other fields on the page besides target fields?

If there are other input fields and controls on the page aside from the target fields, use matching to limit response to the desired fields. For more information, see Configuring Additional Field Detection Criteria.

2.5 Configuring a Form

The procedures in this section use concepts and terminology explained earlier in this guide. When performing the procedures in this section, refer to Determining the Optimal Configuration for a Form to make configuration decisions that best suit the target application.

2.5.1 Basic Configuration

To complete a basic configuration of a form, do the following:

Note:

You can begin the configuration process more quickly by clicking the Logon Manager button in the target application's title bar (if enabled) and selecting Create Template from the context menu that appears.

1. Open the Logon Manager Administrative Console. By default, the shortcut is located in Start > Programs > Oracle > Logon Manager Console.

2. In the left-hand tree, select the Applications node and do one of the following:

- If you want to create a new template and define its first form, click Add in the right-hand pane; then, in the New Application dialog, enter a descriptive name for the template and click Finish. The new template appears in the list of stored templates.

Caution:

If two or more application templates are named such that the name of one of the templates occurs in the beginning of the name of another template, the Agent will erroneously use the template with the shortest name to respond to all of the affected applications. To avoid this behavior, ensure that your template names do not begin with the same string of text.

- If you want to add a form definition to an existing template, expand the Applications node and select the desired template (the template appears in the right-hand pane; then click Add at the bottom of the pane.

3. In the Web Form Wizard that appears, configure the fields and controls that you want the Agent to interact with when responding to the target form.

4. In the "Form Type"screen, select the desired form type and click Next.

5. In the next screen, enter the URL of the target page, form, or element and wait for it to complete loading in the preview pane.

Note:

If you see two or more fields that share the same name, the Agent might respond to the form erroneously when configuration is complete. In such cases enable the Use ordinals instead of names option to uniquely identify the input fields to the Agent via ordinals (consecutive index numbers). For more information, see Understanding Web Form Detection.

6. In the field list at the bottom of the screen, select and configure the target fields and controls from among the objects in the list as follows:

Note:

If one or more fields or controls are missing from the list, you may have to configure them manually. In such cases, complete the remainder of the Wizard as-is, then follow the instructions in Manually Configuring a Field or Control for each affected input field.

By default, all fields and controls use the "Control IDs" response method. If you want to use the "SendKeys" response method for one or more fields, define them as described in this procedure, then follow the instructions in Configuring a Field or Control Using the "SendKeys" Method.

1. (Optional) If your form requires the injection of the same data into multiple fields (e.g., injecting the password into a Password and a Confirm Password field), enable the Allow multiple field designation option.

2. Right-click each desired field or control and select its function from the context menu. The selected field will be highlighted in the page preview.

Caution:

While the Detect Fields feature is accurate the majority of the time, Oracle recommends always configuring fields and controls manually for guaranteed accuracy.

Note:

If a "submit" button (usually labeled OK, Logon, etc.) is not visible in the list, Logon Manager will still send a "submit" action to the application after injecting credentials. This action is equivalent to the user manually pressing the Enter key.

3. If the submit control is missing, it might be implemented as an anchor (i.e., <A HREF=) or an image (i.e., <IMG SRC=). In such cases, enable the Show anchor tags and/or Show non-input fields option, respectively, to expose such a control.

4. When you have configured all of the visible input fields, click OK.

7. The Console displays the properties dialog for the Web form definition you have just configured. Do one of the following:

- If you have successfully completed all of the target input fields using the Web Form Wizard and require no further configuration, click OK in the dialog to dismiss it, then publish your changes to the repository as described in Publishing a Template to the Repository, if applicable.

- If you were unable to configure one or more target fields using the Web Form Wizard, continue to step 3 in Manually Configuring a Field or Control.

- If you need to modify existing or specify additional URL detection criteria, continue to Configuring URL Detection Criteria.

WARNING:

Oracle highly recommends removing the default wildcard regular expression prefix of .*? from your URL definitions to prevent potential phishing attacks.

- If you need to configure additional field detection criteria via the Matching tab, continue to Configuring Additional Field Detection Criteria.

Note:

If the contents of the page are dynamic, i.e., change after the page has completed loading, select the Dynamic Page option in the Options tab to enable active page polling. This will allow the Agent to monitor the page for changes.

2.5.2 Manually Configuring a Field or Control

If you were unable to configure an input field using the Web Form Wizard, or if you want to change a field's existing configuration, follow the procedures below.

2.5.2.1 Configuring a Field or Control Using the "Control IDs" Method

1. In the Console, expand the Applications node and select the desired template.

2. In the General tab, select the desired form definition and click Edit.

3. In the form properties dialog appears, select the Fields tab.

4. To configure a new field, click Add; to modify the configuration of an existing field, select the field in the list and click Edit.

5. In the "Web Field" dialog that appears, do the following:

Note:

See Understanding Field Detection to understand the values you need to specify here.

1. In the Function drop-down list, select the field's purpose. The available values are Username/ID, Password, Third Field, and Fourth Field.

2. In the Frame field, enter the name or ordinal of the field's parent frame element.

3. In the Form field, enter the name or ordinal of the field's parent form element.

4. In the Field Type drop-down list, select the type of the target input field.

5. In the Field Identification field, click the … (ellipsis) button and select the method that you want Logon Manager to identify the field (the available methods are field name, ordinal number, and matching), enter the appropriate value(s) for the selected identification method, and click OK to save your changes and dismiss the dialog.
For more information on configuring matching, see Understanding Detection Matching.

6. Click OK to save your field definition to the template.

6. Repeat steps i - vi for each additional field you want to configure.

7. Click OK in the form properties dialog to dismiss it.

8. Publish your changes to the repository, as described in Publishing a Template to the Repository, if applicable.

2.5.2.2 Configuring a Field or Control Using the "SendKeys" Method

Logon Manager does not allow the direct addition of "SendKeys" actions after the form's response method has been changed to "SendKeys." To add a new action to a form definition that has been switched to the "SendKeys" response method, you must first switch the form back to the "Control IDs" method, add the desired action as described in Configuring a Field or Control Using the "Control IDs" Method, then switch the form definition back to the "SendKeys" method. This procedure explains how to convert existing "Control IDs" actions to "SendKeys" actions and how to configure the converted "SendKeys" actions.

Note:

When you switch a "SendKeys" form definition back to "Control IDs," all "SendKeys" actions whose Inject directly into control option has been disabled will be deleted. Oracle highly recommends planning your form configuration thoroughly before you begin the configuration procedure.

To configure your "SendKeys" actions, do the following:

1. In the Console, expand the Applications node and select the desired template.

2. In the General tab, select the desired form definition and click Edit.

3. In the form properties dialog that appears, select the Fields tab.

4. (Optional) If this is the first time you are switching to the "SendKeys" method, select SendKeys in the "Transfer Method" selector.

Note:

When you select the "SendKeys" method, all actions in the "Fields" list are converted to "SendKeys" actions with the Inject directly into control option (found in the action's property dialog) enabled. In other words, those actions remain programmatic until you disable the Inject directly into control option for each action that you want to be executed using the "SendKeys" method. Oracle recommends using programmatic injection whenever possible and using "SendKeys' only when programmatic interaction with a field or control is not possible.

To learn about when to use the SendKeys using journal hook option, see Troubleshooting Form Response When Using "SendKeys".

The Fields tab display changes to reflect the "SendKeys" response method:

5. To change the order in which the "SendKeys" actions are executed, select the action whose position you want to change, and use the up and down arrow buttons to move it.

6. To configure a "SendKeys" action, select it from the list, click Edit, and use the "SendKeys" dialog that appears to configure the action. Consult the Console help for an explanation of each option present in the dialog.

7. When you have configured all of your actions, click OK to save your changes and dismiss the "SendKeys" dialog.

8. Click OK in the form properties dialog to dismiss it.

9. Publish your changes to the repository, as described in Publishing a Template to the Repository, if applicable.

2.5.3 Configuring URL Detection Criteria

If you need to modify the default URL detection criteria configured by the Web Form Wizard or specify additional criteria, do the following:

WARNING:

Oracle highly recommends removing the default wildcard regular expression prefix of .*? from your URL definitions to prevent potential phishing attacks.

1. In the Console, expand the Applications node and select the desired template.

2. In the General tab, select the desired form definition and click Edit.

3. In the form properties dialog that appears, select the Identification tab.

4. To configure a new URL definition, click Add; to modify the configuration of an URL definition, select the definition in the list and click Edit.

5. In the URL definition properties dialog that appears, select the desired match type, enter the desired match criterion, and click OK to store your URL definition.

Note:

See Understanding URL Detection to understand the values you need to specify here.

6. Repeat steps 4-5 to configure any additional URL definitions.

7. Click OK in the form properties dialog to dismiss it.

8. Publish your changes to the repository, as described in Publishing a Template to the Repository, if applicable.

2.5.4 Configuring Additional Field Detection Criteria

If you need to configure additional field detection criteria in either standard or offset matching mode, do the following:

1. In the Console, expand the Applications node and select the desired template.

2. In the General tab, select the desired form definition and click Edit. The form properties dialog appears.

3. In the dialog, select the Matching tab and complete the steps below in either the Detection Match or the Form Offset Match sections, depending on the desired matching type (see Detection Matching vs. Offset Matching for more information).

Note:

When performing offset matching, you must specify the Offset Start value.

4. To configure a new matching rule, click Add; to modify an existing rule, select the rule in the list and click Edit.

5. In the "Match Criteria" dialog that appears, do the following:

Note:

See Understanding Detection Matching to understand the values you need to specify here.

1. In the Tag field, specify the name of the parent element.

2. (Optional) If there are multiple instances of the parent element within the page, determine its ordinal, select the Match tag instance box and enter the ordinal in the value field.

3. In the Criteria field, select the desired matching mode.

4. In the Value field, enter the target criterion value.

5. For most scenarios, leave the Match whole value option enabled; this will cause Logon Manager to match strictly against the criterion value. If you disable this option, Logon Manager will also consider partial matches against the criterion value as positive.

6. If you want to use regular expressions as part of the criterion value, enable the Use regular expression option.

7. (Optional) If you are creating a matching rule chain to form a complex matching rule, select the desired Boolean operator from the Operation drop-down list to indicate how this rule will chain with the preceding rule.

8. Click OK to save your matching rule.

6. Repeat step 5 for each additional matching rule.

7. Click OK in the form properties dialog to dismiss it.

8. Publish your changes to the repository, as described in Publishing a Template to the Repository, if applicable.

2.6 Testing the Configuration of a Form

Once you have created and configured a form, Oracle highly recommends that you test your configuration before deploying it to end-user workstations. To do so, use the Template Test Manager feature found in the Administrative Console.

Caution:

The Template Test Manager provides interactive troubleshooting and remediation instructions for the most common configuration problems; it is not, however, designed to cover every possible problem scenario. For thorough troubleshooting, follow the instructions in this guide in conjunction with the Template Test Manager, as described below.

Complete the following sets of steps to test your form configuration before publishing:

1. In the left-hand tree, expand the Applications node and navigate to the target template.

2. Right-click the target template and select Test from the context menu.

3. In the "Logon Manager Template Test Manager" window that appears, select the target form in the Forms pane and follow the instructions displayed in the Interactions pane.

4. Do one of the following:

- If the Agent responds to the application as desired and the test has completed successfully, click Finish.

- If the Agent is not responding to the application as desired, and the instructions provided by the Template Test Manager do not resolve the issue, click Close and follow the troubleshooting flowcharts in the rest of this guide to determine and correct the problem. When you have finished, repeat steps 1-3 to test the corrected configuration.

2.6.1 Testing the Configuration of a Logon Form

2.6.1.1 Agent detects form?

Once the Agent has been provided with the template, it will automatically respond to the target form, unless the automatic response feature has been explicitly disabled. If the Agent fails to respond to the form, see Troubleshooting Web Form Detection.

2.6.1.2 Agent injects credentials?

If credentials have been stored for the target application in the user's store, the Agent will inject them into the appropriate fields upon successful application detection. The Agent will also automatically submit the credentials unless the "Auto-Submit" feature has been explicitly disabled. If credential injection fails, see Troubleshooting Form Response when Using Control IDs.

2.6.1.3 Logon loop occurring on logout?

Some applications display their logon screen upon logout, which causes the Agent to enter a logon loop and effectively prevents the user from logging out of the application unless the Agent is shut down. If this happens, see Troubleshooting a Logon Loop.

2.7 Testing the Configuration of a Password Change Form

2.7.1 Agent detects the form?

Once the Agent has been provided with the template, it will automatically respond to the target form, unless the automatic response feature has been explicitly disabled. If the Agent fails to respond to the application, seeTroubleshooting Web Form Detection.

2.7.2 Agent injects and submits credentials?

When the Agent detects the password change, it injects credentials into the appropriate fields and submits them to the application, unless the Auto Submit feature has been explicitly disabled. If credential injection is erratic or does not occur at all, see Troubleshooting Form Response when Using Control IDs.

2.7.3 New password satisfies application's password policy?

If the new password generated by Logon Manager does not satisfy the application's own password policy, password change will be unsuccessful. If you determine this to be the case, compare the password generation policy currently deployed to the Agent with the password policy of the target application and correct any inconsistencies that may cause password change failure.

2.7.4 Agent responds to password change form as if it were a logon?

If the Agent responds to the password change form as if it were a logon form (i.e., Agent injects and submits the user's currently stored credentials), check for the following;

- Configuration mistakes in the template, such as incorrect element or form type, erroneous input field definitions, and so on.

- Check whether the password change form has a dynamic URL and update the template accordingly if it does.

- If you are using detection matching, check whether you are using the correct matching type and examine your matching strings for errors.

2.8 Publishing a Template to the Repository

Once you have successfully tested your application template, you can distribute it to end-user machines by publishing it to the selected target container within your repository, either in a directory-style hierarchy (default), or as a flat configuration file.

Note:

For more information on deploying Logon Manager with a repository and best practices for structuring the repository tree, see the guide Deploying Logon Manager with a Directory-Based Repository.

Before performing this procedure, make sure you are familiar with the structure and configuration of your repository.

To select and publish the desired templates and other configuration objects to the repository:

1. Launch the Logon Manager Administrative Console.

2. Right-click the Applications node and select Publish… from the context menu. The "Publish to Repository" dialog appears.

3. In the Available configuration objects list, navigate to and select the desired objects.

Note:

Only categories for which objects have been configured will appear in this list. For example, if no password generation policies exist, the corresponding category will not appear in this list.

4. Click >> to move the selected objects to the Selected objects to be published list. (To remove an object from this list and not publish it, select the object and click <<.)

5. Select the target container to which you want to publish the selected objects.
If you have previously published to the desired container, select it from the Target Repository drop-down list.

If you have not previously published to the desired container, or if the target container path does not appear in the Target Repository drop-down list, you must use the Browse feature to find and select the target container:

1. Click Browse to browse the directory tree.

Note:

If you are not already connected to the directory, the Console will prompt you to provide the required connection information.

2. In the "Browse for Repository" dialog that appears, navigate to and select the target container.

If you want to create a new container, right-click the desired parent container, select New Container from the context menu, enter the desired name for the new container, and click OK to complete the process.

6. (Optional) If your environment calls for storing configuration objects in flat-format, select the check box Store selected items in configuration files, rather than as individual objects.
Selecting this option will overwrite all items stored in existing configuration files, if present in the target container.

7. (Optional) If you want to create the first-time use object (FTUList), select the corresponding check box.
This option only becomes active if you choose to store your configuration objects in flat format in step 6.

8. Click Publish. The Console publishes the selected objects to the target repository.

Caution:

Do not attempt to dismiss the dialog or close the Console until the publishing process completes. The dialog will disappear automatically when the objects have been published.

For more information on the publishing process, see the Logon Manager Administrative Console help.

2.9 Troubleshooting Web Form Detection

Use the steps below to diagnose erratic form detection.

2.9.1 "Logon Using Logon Manager" tray icon option results in successful detection?

If the Agent does not detect the form, but invoking the Logon Using Logon Manager option from the Agent's system tray icon results in successful detection do the following:

- Make sure that the Auto-recognize option in the form definition's Options tab is enabled.

- Check the template for errors such as incorrect or imprecise URL and input field definitions, matching rules, and so on.

2.9.2 Page completed loading?

The Agent will not begin detection until the browser indicates that the page has loaded completely. If the page is loading slowly, you must allow it to load completely before deciding whether detection is occurring properly. Usually, the browser's status bar, located at the bottom of the browser window, indicates the page has completed loading by displaying an appropriate message, such as "Done" or "Finished."

2.9.3 Is the appropriate helper object running?

In order to communicate with the installed Web browser(s), the Agent uses helper objects that hook into the browser(s) and provide Logon Manager with a means of sending and receiving data to/from the browser. If the helper objects are not running in the background, Logon Manager will be unable to communicate with the browser(s). For more information, see Understanding Web Form Detection.

2.9.4 Removing all detection and offset matching rules results in successful detection?

You might have configured one or more matching rules in a way which prevents successful detection of the target Web form. Remove all matching rules and re-add them one by one while testing detection until you identify the offending rule.

2.9.5 Truncating URL definition to host.domain form results in successful detection?

The URL might contain a dynamic segment which is preventing the Agent from detecting the form consistently. Simplify the URL definition to host.domain form and test the template - if detection is successful, rebuild your URL definition one segment at a time until the offending segment is identified, then use regular expressions to accommodate the dynamic segment. For more information, see Understanding URL Detection.

If the above steps do not resolve the issue, contact Oracle Support to obtain further assistance.

2.10 Troubleshooting Form Response when Using Control IDs

2.10.1 Agent detects the form?

If the Agent does not detect the form at all and does not attempt response, see Understanding Web Form Detection to identify possible problems in template configuration that might be hampering detection.

2.10.2 Agent injects credentials but does not submit them?

If the Agent successfully detects the fields and injects the correct credentials, but is unable to automatically submit them to the application for processing, press Enter to see if the credentials are submitted, then do one of the following:

- If pressing Enter submits the credentials, remove the "submit" input field definition from the template. When the "submit" field definition is absent, the Agent will send its default submit action - the Enter keystroke.

- If pressing Enter does not submit the credentials, instruct the users to submit them manually.

2.10.3 Fields populated erratically?

If the Agent populates the fields erratically, i.e., inserts wrong, truncated, garbled, or blank values, one or more of the target element names might be non-unique or dynamic. In such case, use ordinals instead of element names to uniquely identify the elements to Logon Manager.

If the above steps do not resolve the issue, contact Oracle Support to obtain further assistance.

2.11 Troubleshooting Form Response When Using "SendKeys"

2.11.1 Pre-filled fields cause erroneous logon?

Some applications might pre-fill the logon fields when the logon form is displayed - for example, the user name field might be pre-filled with the name of the last successfully logged on user. You may have to send one or more Backspace or Delete key strokes to clear such a pre-filled field before injecting credentials into it.

2.11.2 Cursor always starts in the same field and retains focus?

If the cursor does not always start in the same field and the field loses focus before the Agent populates it, see if the application permits you to navigate to the field through a specific hotkey combination (such as Alt+U) or by using standard Windows keys, such as Tab, arrows, and so on. If you cannot use keystrokes to navigate to the field, use a mouse click action targeting the desired field or control.

2.11.3 Multiple values injected into a single field?

If the Agent is inserting multiple values (e.g., both the user name and the password) into a single field, it might be firing the "SendKeys" actions too quickly for the application to respond properly. In such cases, experiment with slowing down the action firing rate until credential injection is reliable. To do so, either insert a "Delay" action in between other actions, or set the SendKeys event interval global Agent setting under End-User Experience >Response to either Use for slow system or Use for very slow system.

2.11.4 Switching to "SendKeys" with journal hooks restores reliable injection?

If the Agent continues injecting multiple values into a single field after you have tried the suggestions in the previous step, switch the form interaction method to "SendKeys with journal hook." To do so, select the General tab in the application template, select the desired form, click Edit, select the Fields tab, and set the Transfer Method option to SendKeys using journal hook.

Note:

The "SendKeys using journal hook" method causes the Agent to use an alternate API to send keystrokes and mouse clicks to the browser; it is typically the most effective in Citrix environments.

2.11.5 Characters missing from injected values?

If you find that individual characters are omitted from the injected field values, the Agent might be firing the "SendKeys" actions too quickly for the application to accept them properly. In such cases, experiment with slowing down the action firing rate until credential injection is reliable. To do so, either insert a "Delay" action in between other actions or set the SendKeys event interval global Agent setting under End-User Experience >Response to either Use for slow system or Use for very slow system.

2.11.6 Using mouse click actions to focus on fields results in successful logon?

If logon is still unsuccessful, consider using mouse click actions to focus on all fields and controls within the form.

If none of the above steps resolve your issue, contact Oracle Support for assistance.

2.12 Troubleshooting Detection Matching

2.12.1 Removing all matching rules restores form detection?

If removing all matching rules from the form definition in the template restores proper form detection, re-add the rules one by one until the offending rule is identified. Then, either broaden the scope of the offending rule (for example, specify an HTML container that's "one-above" in the site's DOM hierarchy than the currently specified one), or remove the offending rule completely and see if detection is restored. If disabling matching completely does not restore detection, the problem lies elsewhere. See Troubleshooting Web Form Detection to resolve the problem.

If the above steps do not resolve the issue, contact Oracle Support to obtain further assistance.

2.13 Troubleshooting a Logon Loop

Some applications display their logon form upon logout, which causes Logon Manager to recognize the logon form and automatically log you back on to the application. This creates an endless "logon loop" preventing you from logging out of the application. To prevent this loop from occurring, the administrator may choose to enable the logon grace period feature which forbids Logon Manager from logging on to an application within set time period since the last logon.

2.13.1 Post-logout form URL from standard logon form URL?

If the URL of the logon form presented upon logout is different from the URL of the standard logon form, modify the URL definition in the template so that the URL of the post-logon form is no longer a positive match. See Configuring URL Detection Criteria for instructions.

2.13.2 Post-logout form different from standard logon form?

If the logon form presented upon logout is sufficiently different from the application's standard logon form, use matching to uniquely distinguish between the two logon forms. See Configuring Additional Field Detection Criteria for instructions.

2.13.3 Configuring the "Logon Loop Grace Period" option resolves logon loop?

If the post-logout form cannot be uniquely distinguished from the standard logon form, configure a grace period that will prevent the Agent from automatically logging on to the same application if the specified grace period has not fully elapsed.

To configure the logon loop grace period timer, do the following:

1. In the Logon Manager Administrative Console, open the desired template and select the Miscellaneous tab.

2. In the Logon Loop Grace Period field, select the desired mode of operation from the drop-down list:

- Prompt - if the Agent detects the application's logon form while the grace period is in effect, the Agent will prompt the user whether to complete the logon or ignore the application.

- Silent - if the Agent detects the application's logon form while the grace period is in effect, the Agent will ignore the application and not log the user on.

- None - deactivates the grace period timer. Agent will respond to the application every time it detects the application's logon form.

3. Do one of the following, depending on what you want the Agent to do while the grace period is in effect:

- If you want the Agent to log the user on each time the launch of the application's executable is detected, select the Reset for each process check box.

- If you would like the Agent to ignore the application until the grace period has expired, leave the Reset for each process check box blank.

4. Save your changes and commit them to your repository, if applicable.

Note:

If you have configured the logon grace period timer, and logon loop is still occurring for a specific form definition, make sure that the Adhere to logon loop grace period option in the form definition's Options tab is enabled.

If the above steps do not resolve the issue, contact Oracle Support to obtain further assistance.

2.14 Troubleshooting Java Application Issues

Use the steps below to diagnose and resolve issues specific to Java applications.

2.14.1 Installed JRE is a supported brand and version?

Refer to the release notes for your version of Logon Manager for a list of supported JREs. If the installed JRE is not supported, you must either upgrade Logon Manager to a release that supports your current JRE, or replace the current JRE with a version supported by your release of Logon Manager.

2.14.2 Using Oracle JInitiator or another JRE not made by Oracle or IBM?

While no issues have been reported when deploying Logon Manager with Oracle JInitiator or non-Oracle/non-IBM JREs, Oracle does not support nor warrant the proper functioning of Logon Manager with such JREs.

2.14.3 JHO loaded?

In certain situations, a configuration issue might prevent the JHO from loading when the Java application To verify that the JHO is installed and running, use a process viewer tool, such as Microsoft Spy++ (included with Microsoft Visual Studio) or SysInternals Process Explorer (http://technet.microsoft.com/en-us/sysinternals/bb896653.aspx) to verify that the JVM executable has spawned the ssojho.dll child thread.

The example below shows the properties box of the Sun JVM executable javaw.exe in Process Explorer showing the ssojho.dll child thread running:

If the JHO is not loading for the target JRE, check that the permissions required by the JHO are being granted through the user's .java.policy file (located in their home directory) as described in the next section.

2.14.4 Verifying and Repairing the Permissions Required by the JHO

The JHO requires that a set of specific permissions is granted to it via the user's .java.policy file so that it can properly operate in the context of the target JRE. If these permissions are not in effect, Logon Manager will be unable to detect or respond to Java applications.

2.14.4.1 Verifying That the Required Permissions Are Being Granted

Every time Logon Manager starts, the permissions are copied from a template .java.policy file (located in %INSTALLDIR%\v-GO SSO\Helper\Java) to the user's .java.policy file located in the user's home directory. These permissions are then automatically granted to the JHO every time a Java application is launched.

If you suspect that the required permissions are not being granted to the JHO, check your JRE's log after starting Logon Manager for any missing permission exceptions referencing the JHO. If such exceptions are present, the required permissions are not being granted. This can be caused by one of the following:

- The user's .java.policy file does not contain the permissions required by the JHO,

- The target JRE's security settings (usually stored in the JRE's java.security file) do not reference the user's .java.policy file.

2.14.4.2 Restoring the Missing JHO Permissions

If the user's .java.policy file is missing the required JHO permissions, the file's ACL might be preventing Logon Manager from writing the permissions to it; in such case, check the file's ACL to make sure that write privileges are not being denied.

If the ACL is correct and the required permissions are not present in the user's .java.policy file, do one of the following:

- If the user's .java.policy file contains other permissions or configuration information that you want to preserve, edit the file and manually add the missing JHO permissions.

- If the user's .java.policy file does not contain other permissions or configuration information that you wish to preserve, simply delete it and restart Logon Manager; the file will be recreated and the required permissions inserted automatically.

Note:

As JREs are updated by their vendors, it is possible that a future release introduces one or more new permissions that will be required by the JHO but which could not be accounted for at the time of Logon Manager's release. In such case, examine your JRE's error log for any missing permission exceptions after launching Logon Manager and a target Java application and add those permissions to Logon Manager's .java.policy template file so that they can be granted via the user's .java.policy file the next time Logon Manager starts.

2.14.5 Configuring the Behavior of the Java Helper Object (JHO)

Logon Manager provides global Agent settings that allow you to control the following aspects of the JHO's behavior:

- Exclude specific JRE versions

- Exclude specific JRE vendors

- Define a response delay to account for the loading of Java applets

- Define a response delay to account for the initialization of the JRE

- Define a delay between response retries

- Define a maximum number of response retries

- Define specific hierarchy, window, component and injection type events that the JHO will recognize or ignore

These settings are located in the tree in the Logon Manager Administrative Console at the following location:

Global Agent Settings > Live > User Experience > Application Response > Java Applications

To learn more about these settings and how to configure them, see the Console help. For even more granular control, Logon Manager also provides registry settings described in the next sections. Oracle recommends these settings be used only by experienced administrators.

2.14.5.1 Manually Restricting the JHO to Specific JREs

Aside from the Console settings described earlier, Logon Manager provides registry settings that allow you to create extremely granular inclusion and exclusion rules that Logon Manager will use to decide whether to load the JHO for the target application. You can specify, via regular expressions, the Java Virtual Machine (JVM) executables, JAR files, and command-line parameters that you want the JHO to consider.

When configuring these settings, keep the following in mind:

- If the value for a given setting is omitted, the specified default is used; if a value is set, all non-matching values are ignored.

- The JHO processes the inclusion rules first, followed by the exclusion rules.

- The N suffix is a unique numerical identifier that bundles settings belonging to a specific application. The JHO will process the bundles sequentially in ascending order. The N suffix is a positive integer starting at 1.

- You can determine the application's host JVM executable and launch command using the Trace Logging utility. The beginning of the Java trace log will indicate the host JVM and the launch command for the application.

The settings are located at the following path in the Windows Registry: HKEY_LOCAL_MACHINE\SOFTWARE\Passlogix\Extensions\AccessManager\JHO

The settings are divided into the following categories:

- JHO Inclusion Rules

- JHO Exclusion Rules

- Allowed Java Runtime Environment (JRE) Versions

2.14.5.1.1 JHO Inclusion Rules

Use these settings to specify the host JVM executables, application JAR files, and command-line parameters that will cause the JHO to load for the target application. The values are case-insensitive regular expressions.

Setting

Description

JhoIncludeHostNameN

Specifies the application's host JVM executable(s).

For example, if you want the JHO to load when the application is hosted by a JVM executable named java.exe or javaw.exe, set the value as follows: JhoIncludeHostName1=.*javaw?\.exe No-value default:

All executables are accepted (i.e., JHO will load for any executable).

JhoIncludeHostCommandLineN

Specifies the command used to launch the application. The command string usually includes the full path and name of the JVM executable, the JAR file, as well as any required command-line parameters.

For example, if you want the JHO to only load when the application's JAR file is named Login.jar (while the rest of the command is allowed to vary), set the value as follows: JhoIncludeHostCommandLine1=.*Login\.jar.* No-value default: All command strings accepted (i.e., JHO will load for any command).

2.14.5.1.2 JHO Exclusion Rules

Use these settings to specify the host JVM executables, application JAR files, and command-line parameters that will cause the JHO to ignore the target application. The values are case-insensitive regular expressions.

Setting

Description

JhoExcludeHostNameN

Specifies the application's host JVM executable(s).

For example, if you want the JHO to ignore the application when the host JVM executable is named "java.exe" or "javaw.exe", set the value as follows: JhoExcludeHostName1=.*javaw?\.exe No-value default: Blank (i.e., nothing will cause the JHO to ignore the application)

JhoExcludeHostCommandLineN

Specifies the command used to launch the application. The command string usually includes the full path and name of the JVM executable, the JAR file, and any required command-line parameters.

For example, if you want the JHO to ignore the application when its JAR file is named "Login.jar" (but the rest of the command is non-consequential), set the value as follows: JhoExcludeHostCommandLine1=.*Login\.jar.* No-value default: Blank. (i.e., nothing will cause the JHO to ignore the application)

2.14.5.1.3 Allowed Java Runtime Environment (JRE) Versions

These settings allow you to specify the desired JRE/JDK versions for which the JHO will load; all versions falling outside of the specified range will be ignored and the JHO will not load.

The values for both settings must follow the format x.y.z, where:

- x is the major revision

- y is the minor revision

- z is denotes the release type (feature, maintenance, or update) and build ID of the installed JRE (for example, 1.6.0_07)

Setting

Description

JhoMinimumJavaVersion

Specifies the lowest allowed JRE/JDK version.

Default value:

1.2 (the earliest JRE version supported by the JHO)

JhoMaximumJavaVersion

Specifies the highest allowed JRE/JDK version.

Default value:

Blank (i.e., no upper JRE version limit is imposed)

2.14.5.2 Manually Customizing the Event Response Behavior of the Java Helper Object (JHO)

Aside from the settings provided in the Console, Logon Manager provides registry settings that control the event response behavior of the JHO at an even more granular level. You can use these settings to troubleshoot and optimize Logon Manager performance when responding to Java applications by modifying the JHO's response to specific events when a Java application has been detected.

The settings are located within the following key in the Windows registry: HKEY_LOCAL_MACHINE\SOFTWARE\Passlogix\Extensions\AccessManager

2.14.5.2.1 Event Response Configuration Settings

Setting

Description

JhoHierarchyEventProcessing

Determines which Java hierarchy events are recognized. Set the flag as follows:

HIERARCHY_EVENT_CHANGED = 0x1

The above value instructs the JHO to recognize all hierarchy events.

JhoEventWaitTimeout

Determines the event processing timeout for JHO controls (in milliseconds). The default value of 0 instructs the JHO to wait indefinitely.

JhoWindowEventProcessing

Determines which Java window events are recognized. This flag is a combination of the following values:

· WINDOW_EVENT_OPENED = 0x1

· WINDOW_EVENT_CLOSED = 0x2

· WINDOW_EVENT_ACTIVATED = 0x4

· WINDOW_EVENT_DEACTIVATED = 0x8

· WINDOW_EVENT_CLOSING = 0x10

· WINDOW_EVENT_ICONIFIED = 0x20

· WINDOW_EVENT_DEICONIFIED = 0x40

By default, all window events are recognized.

JhoComponentEventProcessing

Determines which Java component events are recognized. This flag is a combination of the following values:

· COMPONENT_EVENT_SHOWN = 0x1

· COMPONENT_EVENT_HIDDEN = 0x2

· COMPONENT_EVENT_ADDED = 0x4

· COMPONENT_EVENT_REMOVED = 0x8

By default, all component events are recognized.

JhoInjectType

Determines the injection type used by the JHO to submit data to the controls. This flag takes one of the following values:

· INJECT_TYPE_DEFAULT = 0

· INJECT_TYPE_METHOD = 1

· INJECT_TYPE_ACCESSIBLE = 2

· INJECT_TYPE_NONACCESSIBLE = 3

· INJECT_TYPE_ROBOT = 4

By default this flag is set to INJECT_TYPE_DEFAULT, in which case the JHO attempts injection using each of following methods, in the order shown, until injection is successful:

· INJECT_TYPE_METHOD (if an appropriate set method had been found for the control)

· INJECT_TYPE_ACCESSIBLE (if the control supports accessibility)

· INJECT_TYPE_NONACCESSIBLE

· INJECT_TYPE_ROBOT

Note: For combo and list boxes, the JHO always uses INJECT_TYPE_METHOD.

2.14.5.2.2 Recommended JHO Event Response Configuration Defaults

We recommend the following default settings on new installations of Logon Manager:

- JhoWindowEventProcessing=0x3

- JhoComponentEventProcessing=0xB

- JhoHierarchyEventProcessing=0x0

These values instruct the JHO to recognize the following events:

- WINDOW_EVENT_OPENED (0x1)

- WINDOW_EVENT_CLOSED (0x2)

- COMPONENT_EVENT_SHOWN (0x1)

- COMPONENT_EVENT_HIDDEN (0x2)

- COMPONENT_EVENT_REMOVED (0x8)

3 Configuring and Diagnosing
Mainframe Application Templates

This part explains the concepts necessary to understand how and why you should configure mainframe application templates to solve specific sign-on scenarios, as well as the recommended best-practice procedures for configuring and testing mainframe application forms, and diagnosis and resolution steps for the most common issues that may cause the Agent to erratically detect and/or respond to application forms.

It covers the following topics:

- Overview of a Sign-On Event

- Understanding Form Detection and Response

- Determining the Optimal Configuration for a Form

- Configuring a Form

- Testing the Configuration of a Form

- Publishing a Template to the Repository

- Viewing and Modifying Emulator Configuration

- Troubleshooting Form Detection

- Troubleshooting Form Response

- Troubleshooting a Logon Loop

- Troubleshooting Detection and Response with the SSO MHO Status Tool

Tip:

If the steps presented in this chapter do not resolve your issue, you can troubleshoot further by tracing and logging the activity of Logon Manager and submitting the logged information to Oracle Support for analysis. For this purpose, Oracle Support provides the Trace Controller utility. For information on how to use the utility, see the "Using the Trace Controller Utility" topic in the Enterprise Single Sign-On Suite Administrator's Guide.

3.1 Overview of a Sign-On Event

Logon Manager can provide single sign-on capability for mainframe/host applications accessed via a terminal emulator. A terminal emulator is an application that establishes a terminal session from the user's Windows workstation to a multi-user mainframe system over a variety of protocols, including IBM 5270/5050, Telnet, SSH, and so on. Logon Manager can be configured to detect and respond to a wide range of sign-on events, such as logon, password change, and variations of thereof; support is provided for a diverse range of forms, fields, controls, and event flows.

Note:

The list of currently supported emulators can be found in the release notes for your version of Logon Manager. You can also find out whether an emulator is supported by viewing the contents of the mrfmlist.ini file using the Logon Manager Administrative Console. See Viewing and Modifying Emulator Configuration for instructions.

In order to recognize text-based mainframe application forms displayed within supported Windows-based terminal emulators, Logon Manager does the following:

1. Detects the emulator's HLLAPI interface, window, terminal session, and target form:

1. At startup, loads the emulator detection data specified in the mfrmlist.ini file and begins monitoring all HLLAPI interfaces detected on the system for new terminal sessions. (If the emulator does not provide HLLAPI notifications and polling is enabled, Logon Manager queries those emulators via HLLAPI every 700ms, by default).

Note:

The mfrmlist.ini file contains detection data (such as HLLAPI interface library name and path, window title, class, and any required custom configuration parameters) for supported terminal emulators. This data allows Logon Manager to identify and interact with emulators and the terminal sessions they display.

2. When a running emulator notifies Logon Manager via HLLAPI that a new terminal session has been opened (or, if polling is enabled, Logon Manager detects a new session in the emulator), Logon Manager searches through all available mainframe application templates for a template containing a form definition that matches the text displayed in the terminal session.

3. Once per each detected HLLAPI event (keystroke, screen update, and so on), rescans the available mainframe application templates and re-detects the specified match text.

2. Responds to the detected form and completes the logon:

1. Retrieves the associated credentials from the user's store (if they exist) and injects them at field coordinates defined in the template. (If the credentials don't exist, the Agent prompts the user to store them.)

2. Submit the credentials to the application for processing.

3. (Optional) Detects any follow-up forms or dialogs, such as new password change success or failure, and performs the required action.

3.2 Understanding Form Detection and Response

Logon Manager uses the Mainframe Helper Object (MHO), instantiated as a background process named ssomho.exe, to interact with terminal emulators via the High-Level Language API (HLLAPI). This allows Logon Manager to programmatically detect an emulator's HLLAPI interface, monitor (or query) the emulator for session instantiation, screen updates, and other events, and interact with the emulator to detect the match text, inject credentials, and submit them to the application for processing.

The MHO directly interfaces with most modern 32-bit emulators via HLLAPI. Additionally, Oracle provides support for some common non-HLLAPI emulators and 16-bit emulators, for which you need to install additional helper objects listed below (available under the Extensions >Mainframe Support node in the Logon Manager installer):

- Console windows - supports Windows command-line console windows instantiated by the cmd.exe interpreter and running 32-bit applications, such as the Microsoft Telnet client.

- PuTTY - supports the PuTTY terminal emulator.

Note:

If you need a Telnet, SSH, or RS-232 connection to an application and your current terminal emulator only supports HLLAPI for IBM 5270/5050 connections, Oracle supports and highly recommends using the free PuTTY terminal emulator for connecting via those protocols.

When Logon Manager starts, the MHO reads the contents of the mfrmlist.ini file (located in %PROGRAMFILES%\Passlogix\v-GO SSO\Helper\Emulator), which contains detection data (such as HLLAPI interface library name and location, window title and class, executable name, and any custom configuration options required to support the emulator) for the supported emulators.

Note:

While Logon Manager ships with a "factory" mfrmlist.ini file, you also have the ability to add an unlisted emulator to the file in order to permit Logon Manager to detect and interact with that emulator. For more information, see Viewing and Modifying Emulator Configuration.

The MHO then parses the configuration data for each emulator present in the mfrmlist.ini file and begins monitoring (or polling, if configured as such) each registered HLLAPI interface it detects. Once the configuration data has been loaded, the MHO monitors the detected HLLAPI interfaces for new session short-names.

For each new detected terminal session short-name, the MHO queries the emulator via HLLAPI for more information, such as the title and class of the session window. This information is matched against the window title and class present in the emulator's entry in the mfrmlist.ini file.

While HLLAPI in itself is an open standard, emulator vendors often implement terminal emulators to varying degrees of adherence and/or completeness. Because of this, some HLLAPI-enabled emulators do not properly notify Logon Manager of session events, such as session instantiation, screen updates, and so on. For those emulators, the ChangeNotificationBroken=1 configuration parameter, which enables polling, must be present within their entries in the mfrmlist.ini file.

Note:

See Viewing and Modifying Emulator Configuration for instructions on how to view an emulator entry in the mfrmlist.ini file and add this parameter, if necessary. (Oracle-tested emulators that require this parameter are preconfigured to include it in the mfrmlist.ini file "out of the box.")

Once the emulator has been positively identified, the MHO examines all available mainframe application templates for matches against the text displayed in the terminal session and loads the first template that is a positive match against the detected form text. The MHO also rescans all mainframe templates and re-detects the match text every time new HLLAPI event is detected in the emulator.

Note:

An application template is a set of configuration options that instruct the Logon Manager Agent how to detect and respond to application windows and the forms they contain.

Mainframe applications operate in text-mode, i.e., they use a set of monospaced characters displayed on a known-size grid - typically 80 rows by 25 columns - that comprises the terminal screen. Because of this, each character on the screen can be uniquely identified by a set of vertical and horizontal coordinates. When defining a mainframe application form, you provide v Logon Manager with the starting coordinates of each target field (i.e., the coordinates where Logon Manager should begin injection).

For example, the Username field begins at column 10, row 15 (i.e., Logon Manager will inject the user name starting after the semicolon in row 15), while the password field begins two rows lower, at column 10, row 17, after the Password: field text:

Note:

Logon Manager supports terminal displays of any size, and a single template will provide response to an application running in different sizes, as long as the absolute coordinates of the configured match text and fields remain the same when the screen size changes.

Tip:

Most emulators display the coordinates of the terminal cursor in their status bar. To quickly determine the coordinates of a field, position the terminal cursor at the beginning of the field and check the position displayed in the emulator's status bar.

During detection, Logon Manager retrieves the coordinates of the specified match text and checks whether that text exists at the specified coordinates, while during response, Logon Manager locates the specified field coordinates and injects credentials into those screen locations.

3.2.1 Fixed Screen Forms vs. Scrolling Screen Forms

The example shown and described earlier in this section portrays a fixed-screen application, which is the most commonly encountered type of application. However, some applications, such as Telnet clients, may utilize a scrolling-screen display. The differences are as follows:

- Fixed-screen. The application screen has a fixed horizontal (number of columns) and vertical (number of rows) size, i.e., it does not scroll vertically. Most mainframe applications, such as inventory or machine control systems, fall into this category. In a fixed-screen session, every character displayed in the session has a static position, i.e. its coordinates do not change.

- Scrolling-screen. The application screen has a fixed horizontal size (number columns) but an unlimited, or continuous, vertical size (number of rows). In a scrolling-screen session, fields do not have static coordinates; in order to locate them, Logon Manager requires you to specify the column position of the cursor (i.e., where the cursor is expected to be found horizontally after completing each step in the logon sequence), as well as the sequence of fields and actions required to complete the logon. Logon Manager can detect via HLLAPI whenever the screen has scrolled and by how much, and advance to the next field or action in the sequence as necessary.

Note:

For scrolling-screen forms Logon Manager also supports fields that have dynamic horizontal coordinates, allowing you to input a regular expression as the horizontal coordinate. For more information, see Configuring a Form.

3.2.2 Supported Form Types

As of the release date of this document, Logon Manager supports the following types of forms in mainframe applications:

- Logon

- Logon success (a message confirming successful logon)

- Logon failure (a message indicating the injected credentials have been rejected)

- Password change

- Password change success (a dialog confirming successful password change)

- Password change failure (a dialog indicating the new password was rejected)

A mainframe logon form, for example, typically contains at least a user name field, a password field, and, sometimes, additional controls that permit Logon Manager to navigate the screen. Usually credentials are submitted via the default Logon Manager "submit" action, the Enter keystroke (which should not be explicitly specified in the form definition).

Note:

Some non-HLLAPI emulators may provide a scripting language that allows you to display a Windows-style logon dialog. In such cases, you can create a Windows application template for the scripted logon dialog and use SendKeys to inject credentials and complete the logon. For instructions on creating the required script, consult the emulator documentation provided by its vendor; for instructions on creating a Windows application template, see Configuring and Diagnosing Windows Application Templates.

When defining a form in a mainframe application template, you must identify the coordinates of the target fields in the application's display. Since Logon Manager detects the emulator window before it detects the form displayed in the session screen, a single application template will work for all supported emulators that behave identically to the original emulator used to create the template. Thanks to HLLAPI, Logon Manager does not need to perform screen scraping nor does it need to analyze entire screens of text for a match - instead, Logon Manager re-detects the defined match text every time a new HLLAPI event is detected within the emulator.

The same terminal session may display different forms depending on the invoked function (i.e., logon or password change); thus, a single template can contain definitions for the multiple forms that the window can display. For most applications, you need to only define the forms to which you want Logon Manager to respond. Logon Manager can automatically populate the appropriate fields in a form with credentials retrieved from the user's credential store, as well as submit the credentials to the application for processing. Defining a form comprises providing unique identification criteria, specifying the action to take when the form is detected, and the specific way in which the action (e.g., injecting credentials) should be performed.

Note:

Logon Manager is unable to differentiate between multiple sessions of an application if the application display does not contain unique session identification information (such as a host name). For example, if you open two sessions to two mainframe hosts running the same application but each requiring different credentials, Logon Manager will attempt to complete the logon (or password change) with the credentials stored in the template for both sessions. In such cases Oracle recommends storing credentials for all possible sessions for an application within a single template and using the "Logon Chooser" feature to prompt the user to manually select the credentials for each session.

3.2.3 Supported Credential Injection Methods

Depending on the design of the target application, Logon Manager can use one of the following methods to interact with the fields and controls in the target form:

- HLLAPI - This is the default and preferred form interaction method for most mainframe applications, particularly those using the IBM 5270/5050 protocols. This method uses the HLLAPI interface to programmatically inject credentials at the specified coordinates.

- SendKeys - This method injects credentials by emulating keystrokes. Use this method if the emulator does not support HLLAPI or when special actions are required to complete the logon sequence - for example, the application requires the user to manually advance to the next field via a keystroke, and the field remains disabled until the user navigates to it. Oracle recommends using HLLAPI whenever possible for a more robust configuration.

Note:

: When configuring a mainframe application template, as soon as you begin adding additional fields or actions to the form definition after completing the wizard, Logon Manager switches from HLLAPI to SendKeys-based injection.

- SendKeys as a Windows Application - recommended only when no other injection method works, you may attempt to configure your mainframe as a Windows application and use SendKeys to both navigate the application's logon screen and inject credentials. This method is very limited in scope, as Logon Manager is unable to detect any screen updates - actions are sent to the application "blindly." For this reason, this method will only work for the application's initial screen (usually, the logon screen) and no subsequent screens that appear once logged in.

3.3 Determining the Optimal Configuration for a Form

When Configuring a Form, use the information in this section to determine its optimal configuration based on the requirements and features of the target application.

3.3.1 Determining the Optimal Configuration for a Logon Form

3.3.1.1 Emulator supported by Logon Manager out of the box?

If the emulator has been tested by Oracle and found to be compatible with Logon Manager, it is supported by Logon Manager out of the box and a corresponding entry exists for the emulator in the mfrmlist.ini file. The list of currently supported emulators can be found in the latest application release notes. It can also be determined by looking for an entry for the emulator in question in the mfrmlist.ini file, as described in Viewing and Modifying Emulator Configuration.

If the emulator is not supported by Logon Manager out of the box and it is HLLAPI-compliant, you may add it to the mfrmlist.ini file (as described in Viewing and Modifying Emulator Configuration) in order to determine whether it is fully compatible with Logon Manager. While Oracle Support will aid you in this effort should you run into configuration issues, Oracle is unable to guarantee that an untested emulator will properly function with Logon Manager in all expected capacities.

Note:

If you add an unlisted emulator to the mfrmlist.ini file and find it to be fully functional with Logon Manager, Oracle requests that you submit the emulator name and version to Oracle Support so that we can consider including official support for that emulator in the next release of Logon Manager.

3.3.1.2 Is the emulator HLLAPI-compliant?

Depending on whether the emulator is HLLAPI-compliant, do one of the following:

- If the emulator is HLLAPI-compliant but is not officially supported by Logon Manager, you can manually add the emulator to the mfrmlist.ini file to allow Logon Manager to interact with it and determine whether Logon Manager's response to the target application via that emulator is reliable.
For instructions, see Viewing and Modifying Emulator Configuration.

- If the emulator does not support HLLAPI, check whether it provides a scripting language that allows you to code a script that will display the application's logon and password-change forms as Windows-style dialogs.
If the emulator has this scripting capability, write the script according to the vendor's documentation, then configure a Windows application template to respond to the Windows-style dialogs.

For more information on creating Windows application templates, see Configuring and Diagnosing Windows Application Templates.

Note:

For assistance in writing the script, consult the emulator's vendor. Oracle is unable to provide help in the writing and/or troubleshooting of third-party scripts.

If neither of the above options is available, contact Oracle Support for assistance.

3.3.1.3 Is the emulator's HLLAPI implementation up to date?

In some cases, the emulator's initial HLLAPI implementation might be incomplete or defective. If possible, Oracle recommends researching and applying any vendor updates that improve or expand the emulator's HLLAPI implementation in a way that improves the emulator's compatibility with Logon Manager. For more information on the level of your emulator's HLLAPI implementation, consult the emulator vendor.

3.3.1.4 Non-unique target form?

When configuring the form, you must select a match text string within the form that does not appear anywhere else within the application; otherwise, Logon Manager may respond to screens that contain the non-unique match text even though they are not the target form. If a unique match text string is not present in the target form, investigate the possibility of modifying the application in order to add a piece of unique text to the form.

If modifying the application is not an option, configure the "logon chooser" feature in the template and instruct users to select the desired credentials when logging on to the affected application. For information on the "logon chooser" feature, see the Console help.

3.3.1.5 Logon form comprised of multiple screens?

Since Logon Manager treats each new screen as a separate form, if the target form is comprised of multiple screens,( i.e., the user name field is displayed, then the screen is cleared and the password field is displayed on a brand new screen), define a separate form for each of the screens.

3.3.1.6 Logon and password change (PWC) forms on the same screen?

Some applications display logon and password change fields and/or controls on the same screen. In such cases, if the Auto Submit feature is enabled and the Agent responds to such application, the user is logged in automatically without being given the option to change the password. To allow the users to choose the desired action, define the logon and password change forms in the template. The Agent will prompt the user for the desired course of action (logon or password change) when it responds to an application with consolidated logon and password change forms.

Note:

You also have the option to configure a grace period for the "action chooser" feature, during which the Agent will automatically assume that logon is the preferred action and log the user on without prompting to choose the desired action. This option, named Action Chooser Grace Period, is available in the Miscellaneous tab in the application template.

3.3.2 Determining the Optimal Configuration for a Password Change Form

3.3.2.1 Logon and password change (PWC) forms on the same screen?

Some applications display logon and password change fields and/or controls on the same screen. In such cases, if the Auto Submit feature is enabled and the Agent responds to such application, the user is logged in automatically without being given the option to change the password. To allow the users to choose the desired action, define the logon and password change forms in the template. The Agent will prompt the user for the desired course of action (logon or password change) when it responds to an application with consolidated logon and password change forms.

Note:

You also have the option to configure a grace period for the "action chooser" feature, during which the Agent will automatically assume that logon is the preferred action and log the user on without prompting to choose the desired action. This option, named Action Chooser Grace Period, is available in the Miscellaneous tab in the application template.

3.3.2.2 PWC form comprised of multiple screens?

Since Logon Manager treats each new screen as a separate form, if the target form is comprised of multiple screens,( i.e., the application prompts the user to enter the old password, clears the screen, then prompts for the new password, clears the screen again, and then prompts for confirmation of the new password), define a separate form for each of the screens.

3.3.2.3 One or more non-unique screens?

If one or more screens in a multiple-screen form are non-unique (i.e., Logon Manager cannot distinguish between them), response to those screens will be erroneous. When configuring the form, you must select a match text string within the form that does not appear anywhere else within the application; otherwise, Logon Manager may respond to screens that contain the non-unique match text even though they are not the target form. If a unique match text string is not present in the target form, investigate the possibility of modifying the application in order to add a piece of unique text to the form. If modifying the application is not an option, configure the "logon chooser" feature in the template and instruct users to select the desired credentials when logging on to the affected application.

3.3.2.4 Application requests confirmation of new password?

If the application requests the users to confirm (re-enter) the new password during password change, define a logon form that will respond to the password confirmation screen (define only the password field in this secondary logon form).

3.3.2.5 Application displays a password change success or failure message?

If the application displays a success or failure message after password change, define a password change success or a password change failure form in the template. For instructions, see Testing the Configuration of a Password Change Form.

3.4 Configuring a Form

The procedures in this section use concepts and terminology explained earlier in this guide. When performing the procedures in this section, refer to Configuring a Form to make configuration decisions that best suit the target application.

Before configuring a form, launch the desired terminal emulator, connect to the target application, and make sure its target form is displayed.

3.4.1 Basic Configuration of a Fixed-Screen Form

To complete a basic configuration of a fixed-screen form, do the following:

1. Open the Logon Manager Administrative Console. By default, the shortcut is located in Start > Programs > Oracle > Logon Manager Console.

2. In the left-hand tree, select the Applications node, then do one of the following:

- If you want to create a new template and define the logon form, click Add in the right-hand pane; then, in the New Application dialog, that appears, enter a descriptive name for the template and click Finish. The new template appears in the list of stored templates.

Caution:

If two or more application templates are named such that the name of one of the templates occurs in the beginning of the name of another template, the Agent will erroneously use the template with the shortest name to respond to all of the affected applications. To avoid this behavior, ensure that your template names do not begin with the same string of text.

- If you want to add a logon form definition to an existing template, expand the Applications node and select the desired template (the template appears in the right-hand pane), then click Add at the bottom of the pane.

3. In the wizard that appears, define the match text and fields that you want Logon Manager to interact with when logging on to the application. In the "Form Type"screen, select the desired form type and click Next.

4. In the "Screen Type" screen, click Fixed Screen.

5. When the "Paste Screen Text" screen appears, copy the entire text that comprises the target form in the emulator window to the clipboard and click Paste Text to paste it into the wizard. When you have pasted the text, click Next.

6. In the "Text to Match" screen, define the text that Logon Manager will look for in the form to uniquely identify it and match it to the template:

Note:

Oracle recommends keeping your matching rules to a minimum while retaining the desired matching behavior. Matching on large portions of text can slow down the logon process.

1. Highlight the desired match text block.

2. Press Enter to add the text matching rule.

3. Repeat steps i-ii to define additional text matching rules.

4. When you have defined the desired rules, click Next.

7. In the "Fields" screen, define the target fields into which Logon Manager will inject credentials:

1. (Optional) If your form requires the injection of the same data into multiple fields (e.g., injecting the password into a Password and a Confirm Password field), enable the Allow multiple field designation option.

2. Place the cursor at the beginning of the field into which you want Logon Manager to inject a credential.

3. Press Enter.

4. In the context menu that appears, select the desired field type.

5. Repeat steps i-iii to define additional fields.

6. When you have defined all desired fields, click Next.

8. In the summary screen that appears, review your configuration choices. If any of the choices seem erroneous, click Back and correct them; otherwise, click Finish.

9. In the form properties dialog that appears, do one of the following:

- If you need to perform additional configuration, do so now.

- If you are satisfied with the configuration, click OK to dismiss the dialog.

10. Publish your changes to the repository as described in Publishing a Template to the Repository, if applicable.

3.4.2 Basic Configuration of a Scrolling-Screen Form

To complete a basic configuration of a scrolling-screen form, do the following:

1. Open the Logon Manager Administrative Console. By default, the shortcut is located in Start > Programs > Oracle > Logon Manager Console.

2. In the left-hand tree, select the Applications node and do one of the following:

- If you want to create a new template and define the logon form, click Add in the right-hand pane, then, in the New Application dialog that appears, enter a descriptive name for the template and click Finish. The new template appears in the list of stored templates

Caution:

If two or more application templates are named such that the name of one of the templates occurs in the beginning of the name of another template, the Agent will erroneously use the template with the shortest name to respond to all of the affected applications. To avoid this behavior, ensure that your template names do not begin with the same string of text.

- If you want to add a logon form definition to an existing template, expand the Applications node and select the desired template (the template appears in the right-hand pane), then click Add at the bottom of the pane.

3. In the wizard that appears, define the match text and fields that you want Logon Manager to interact with when logging on to the application. In the "Form Type"screen, select the desired form type and click Next.

4. In the "Screen Type" screen, click Scrolling Screen.

5. When the "Paste Screen Text" screen appears, copy the entire text that comprises the target form in the emulator window to the clipboard and click Paste Text to paste it into the wizard. When you have pasted the text, click Next.

6. In the "Cursor Position" screen, specify the current position of the cursor in the emulator display as follows:

1. Click the desired location in the screen text. (You can also enter the vertical and horizontal coordinates in the Cursor Row and Cursor Column fields.)

2. Click Next.

7. In the "Text to Match" screen, define the text that Logon Manager will look for in the form to uniquely identify it and match it to the template:

Note:

Oracle recommends keeping your matching rules to a minimum while retaining the desired matching behavior. Matching on large portions of text can slow down the logon process.

1. Highlight the desired match text block.

2. Press Enter to add the text matching rule.

3. Repeat steps i-ii to define additional text matching rules.

4. When you have defined the desired rules, click Next.

8. In the "Fields" screen, define the target fields into which Logon Manager will inject credentials, in the order they appear in the application's logon sequence:

1. (Optional) If your form requires the injection of the same data into multiple fields (e.g., injecting the password into a Password and a Confirm Password field), enable the Allow multiple field designation option.

2. In the Tab Character field, select the keystroke Logon Manager will send to submit the data injected into the field to the application and advance to the next field.

3. Click Add.

4. In the dialog that appears, select the field type and click OK.

5. Repeat steps a-d to define additional fields.

6. When you have defined all desired fields, click Next.

9. In the summary screen that appears, review your configuration choices. If any of the choices seem erroneous, click Back and correct them; otherwise, click Finish.

10. In the form properties dialog that appears, do one of the following:

- If you need to perform additional configuration, see Advanced Form Configuration.

- If you are satisfied with the configuration, click OK to dismiss the dialog.

11. Publish your changes to the repository as described in Publishing a Template to the Repository, if applicable.

3.4.3 Advanced Form Configuration

This section describes the additional configuration you can perform after you have defined a form using the wizard. These are:

- Defining Window Title Matching Rules

- Defining Additional Text Matching Rules

- Defining Additional Fields

- Adding Keystrokes, Pauses, or Text to the Logon Sequence

- Configuring a Form for Dynamic Column Positioning (Scrolling-Screen Only)

- Reducing Injection Speed

- Adjusting the Emulator Polling Interval

- Adjusting the Credential Request Delay Interval

Before starting the procedures below, open the properties dialog for the desired form as follows:

1. In the Logon Manager Administrative Console's left-hand tree, expand the Applicationspane and select the desired template.

2. In the right-hand pane, select the General tab.

3. In the General tab, double-click the desired form definition.

4. Continue to the desired procedure.

3.4.3.1 Defining Window Title Matching Rules

To limit Agent response to a specific window title (or multiple variations of thereof), define one or more specific window title matching rules as follows:

Note:

Oracle recommends keeping your matching rules to a minimum while retaining the desired matching behavior. Matching on large portions of text can slow down the logon process.

1. In the Identification tab of the form properties dialog, click Add.

2. In the "Window Title" dialog that appears, do the following:

1. Select the desired matching type.

2. Enter the desired match value.

3. Click OK to save your changes.

3. When you have finished, click OK to dismiss the form properties dialog.

3.4.3.2 Defining Additional Text Matching Rules

To define additional text matching rules, do the following:

Note:

Oracle recommends keeping your matching rules to a minimum while retaining the desired matching behavior. Matching on large portions of text can slow down the logon process.

1. In the Matching tab of the form properties dialog, click Add.

2. In the dialog that appears, enter the desired match text and its starting coordinates.

3. Repeat steps 1-2 for each additional rule you want to define.

4. When you have finished, click OK to dismiss the form properties dialog and Publishing a Template to the Repository if applicable.

3.4.3.3 Defining Additional Fields

To define fields additional to the ones you have configured in the wizard, do the following:

WARNING:

If you begin this procedure, the template will be converted from a native HLLAPI template to a SendKeys template - in other words, Logon Manager will no longer inject credentials programmatically via HLLAPI, but instead will emulate user input by sending keystrokes to the emulator. This conversion is not reversible - to revert to native HLLAPI injection, you must delete the template and re-create it. For more information on native HLLAPI vs. SendKeys-based injection, see Supported Credential Injection Methods.

1. In the Fields tab of the form properties dialog, click Edit.

2. In the dialog that appears, select the Fields tab.

3. In the tab, select the desired field type, and enter its coordinates (fixed-screen only).

4. Use the up/down arrows to adjust the order of the logon sequence.

5. Repeat steps 2-3 for each additional field.

6. When you have finished, click OK to dismiss the form properties dialog and Publishing a Template to the Repository, if applicable.

3.4.3.4 Adding Keystrokes, Pauses, or Text to the Logon Sequence

To add keystrokes, pauses, or text to the logon sequence, do the following:

WARNING:

If you begin this procedure, the template will be converted from a native HLLAPI template to a SendKeys template - in other words, Logon Manager will no longer inject credentials programmatically via HLLAPI, but instead will emulate user input by sending keystrokes to the emulator. This conversion is not reversible - to revert to native HLLAPI injection, you must delete the template and re-create it. For more information on native HLLAPI vs. SendKeys-based injection, see Supported Credential Injection Methods.

1. In the General tab of the form properties dialog, click Edit in the "Fields" section.

2. In the dialog that appears, do one of the following:

- To add a keystroke, select the Special Keys tab, select the keystroke category and then the keystroke itself, and click Insert.

- To add a pause, select the Delay tab, specify the length of the pause in seconds, and click Insert.

- To add text, select the Text tab, enter the desired text string, and click Insert.

3. Select the newly inserted action(s) and use the up/down arrows to adjust their order in the logon sequence.

4. Repeat steps 2-3 for each additional field.

5. When you have finished, click OK to dismiss the form properties dialog and Publishing a Template to the Repository, if applicable.

3.4.3.5 Configuring a Form for Dynamic Column Positioning (Scrolling-Screen Only)

To configure a scrolling-screen form for dynamic column positioning, do the following:

1. Select the Options tab of the form properties dialog.

2. In the Column position of cursor field, enter a number or regular expression that defines the possible horizontal position(s) of the cursor in the form.

3. When you have finished, click OK to dismiss the form properties dialog and Publishing a Template to the Repository, if applicable.

3.4.3.6 Reducing Injection Speed

By default, Logon Manager injects and submits credentials with no delay between those actions. To reduce the injection speed, do the following:

1. Select the Options tab of the form properties dialog.

2. In the Field Delay field, enter the desired amount of time Logon Manager should wait after populating each field, in milliseconds.

3. When you have finished, click OK to dismiss the form properties dialog and Publishing a Template to the Repository, if applicable.

3.4.3.7 Adjusting the Emulator Polling Interval

By default, if polling is enabled, Logon Manager queries the emulator via HLLAPI for new events every 700 ms. To adjust the length of this polling interval, do the following:

1. Open the Logon Manager Administrative Console and load the current set of your global Agent settings.

2. In the left-hand tree, expand Global Agent Settings > <current settings set> > End-User Experience > Response > Host Mainframe Apps.

3. In the right-hand pane, select the check box next to the Polling Interval option and enter the desired interval length, in milliseconds, into the field.

4. When you have finished, Publishing a Template to the Repository, if applicable.

3.4.3.8 Adjusting the Credential Request Delay Interval

When a user logs on to a mainframe application for which a template exists but no credentials have yet been stored, Logon Manager prompts the user to store the credentials. If the user dismisses the dialog without storing the credentials, Logon Manager will wait for a default of 60 seconds and the next time the user interacts with the application, Logon Manager will prompt the user to store the credentials again. To change how long Logon Manager waits before re-prompting the user to store credentials for the application, do the following:

1. Open the Logon Manager Administrative Console and load the current set of your global Agent settings.

2. In the left-hand tree, expand Global Agent Settings > <current settings set> > End-User Experience > Response > Host Mainframe Apps.

3. In the right-hand pane, select the check box next to the Credential Request Interval option and enter the desired interval length, in milliseconds, into the field.

4. When you have finished, Publishing a Template to the Repository, if applicable.

3.5 Testing the Configuration of a Form

Once you have created and configured a form, complete the following steps to test it before publishing:

1. In the left-hand tree, expand the Applications node and navigate to the target template.

2. Right-click the target template and select Test from the context menu.

3. In the "Logon Manager Template Test Manager" window that appears, select the target form in the Forms pane, then follow the instructions displayed in the Interactions pane.

4. Do one of the following:

- If the Agent responds to the application as desired and the test has completed successfully, click Finish.

- If the Agent is not responding to the application as desired, click Close and follow the troubleshooting flowcharts in this section to determine and correct the problem, then repeat steps 1-3 to test the corrected configuration.

3.5.1 Testing the Configuration of a Logon Form

3.5.1.1 Agent detects the form?

Once the Agent has been provided with the template, it will automatically respond to the target application, unless the automatic response feature has been explicitly disabled. If the Agent fails to respond to the application, see Troubleshooting Form Detection.

3.5.1.2 Agent injects credentials?

If credentials have been stored for the target application in the user's store, the Agent will inject them into the appropriate fields upon successful application detection. The Agent will also automatically submit the credentials unless the "Auto-Submit" feature has been explicitly disabled. If credential injection fails, see Troubleshooting Form Response .

3.5.1.3 Logon loop occurring on logout?

Some applications display their logon screen upon logout, which causes the Agent to enter a logon loop and effectively prevents the user from logging out of the application unless the Agent is shut down. If this happens, see Troubleshooting a Logon Loop.

3.5.1.4 Logon failure or expired password exceptions accounted for in the template?

If the logon attempt fails, (for example, due to bad credentials), or the stored password has expired, most applications will display an appropriate message, but Logon Manager will not be by default aware of what happened and will attempt to log on again. In order to avoid this, set up a matching rule that will expect either a blank (no text) or space characters in the exact location of the error message. This way, whenever the message is displayed, the match rule will not be satisfied and Logon Manager will not attempt logon.

3.5.2 Testing the Configuration of a Password Change Form

3.5.2.1 Agent detects the form?

Once the Agent has been provided with the template, it will automatically respond to the target application, unless the automatic response feature has been explicitly disabled. If the Agent fails to respond to the application, seeTroubleshooting Form Detection.

3.5.2.2 Agent injects and submits credentials?

When the Agent detects the password change, it injects credentials into the appropriate fields and submits them to the application, unless the Auto Submit feature has been explicitly disabled. If credential injection is erratic or does not occur at all, see Troubleshooting Form Response.

3.5.2.3 New password satisfies application's password policy?

If the new password generated by Logon Manager does not satisfy the application's own password policy, password change will be unsuccessful. If you determine this to be the case, compare the password generation policy currently deployed to the Agent with the password policy of the target application and correct any inconsistencies that may cause password change failure.

3.5.2.4 Agent responds to password change form as if it were a logon?

If the Agent responds to the password change form as if it were a logon form (i.e., Agent injects and submits the user's currently stored credentials), make sure that your password change form definition is not using the same match text string as your logon form definition - if it does, either match on a different string of text or, if possible, modify either of the application screens to include a piece of text against which Logon Manager can match uniquely.

If the Agent is still not responding to the form, see Troubleshooting Detection and Response with the SSO MHO Status Tool.

3.6 Publishing a Template to the Repository

Once you have successfully tested your application template, you can distribute it to end-user machines by publishing it to the selected target container within your repository, either in a directory-style hierarchy (default), or as a flat configuration file.

Note:

For more information on deploying Logon Manager with a repository and best practices for structuring the repository tree, see the Logon Manager Best Practices guide for your platform.

Before performing this procedure, make sure you are familiar with the structure and configuration of your repository.

To select and publish the desired templates and other configuration objects to the repository:

1. Launch the Logon Manager Administrative Console.

2. Right-click the Applications node and select Publish… from the context menu. The "Publish to Repository" dialog appears.

3. In the Available configuration objects list, navigate to and select the desired objects.

Note:

Only categories for which objects have been configured will appear in this list. For example, if no password generation policies exist, the corresponding category will not appear in this list.

4. Click >> to move the selected objects to the Selected objects to be published list. (To remove an object from this list and not publish it, select the object and click <<.)

6. Select the target container to which you want to publish the selected objects.
If you have previously published to the desired container, select it from the Target Repository drop-down list.

If you have not previously published to the desired container, or if the target container path does not appear in the Target Repository drop-down list, you must use the Browse feature to find and select the target container:

1. Click Browse to browse the directory tree.

Note:

If you are not already connected to the directory, the Console will prompt you to provide the required connection information.

2. In the "Browse for Repository" dialog that appears, navigate to and select the target container.

Note:

If you want to create a new container, right-click the desired parent container, select New Container from the context menu, enter the desired name for the new container, and click OK to complete the process.

7. (Optional) If your environment calls for storing configuration objects in flat-format, select the check box Store selected items in configuration files, rather than as individual objects.
Selecting this option will overwrite all items stored in existing configuration files, if present in the target container.

8. (Optional) If you want to create the first-time use object (FTUList), select the corresponding check box.
This option only becomes active if you choose to store your configuration objects in flat format in step 6.

9. Click Publish. The Console publishes the selected objects to the target repository.

Caution:

Do not attempt to dismiss the dialog or close the Console until the publishing process completes. The dialog will disappear automatically when the objects have been published.

For more information on the publishing process, see the Logon Manager Administrative Console help.

3.7 Viewing and Modifying Emulator Configuration

The mfrmlist.ini file contains configuration information that allows it to detect and interact with terminal emulators.

Note:

This mfrmlist.ini file is located in: %PROGRAMFILES%\Passlogix\v-GO SSO\Helper\Emulator

The most important configuration parameters for each emulator are:

- Full path and file name of the HLLAPI library file

- Session short -name

- Window title

- Window class

- Polling toggle (for emulators that do not properly notify the MHO of HLLAPI events)

For a full list of parameters and their descriptions, see Emulator Configuration Parameter Reference.

To view or edit an emulator's configuration stored in the mfrmlist.ini file, do the following:

WARNING:

Do not modify the mfrmlist.ini file in an external editor - doing so will render mainframe support inoperable for any emulator whose configuration you edit in the external editor. This is because the Console's built-in editor automatically recalculates and updates the "magic number" stored in the Context parameter for each emulator when that emulator's configuration changes - an external editor will not update this magic number.

1. Launch the Logon Manager Administrative Console.

2. From the Tools menu, select ModifyConfiguration > MfrmList.
The Console displays the mfrmlist.ini in a built-in editor.

At the top of the file there is a list of all emulators whose configuration data is stored as sections in the remainder of the file.

3. To modify existing configuration data, navigate to that section (to quickly jump to a specific section, select it from the Section drop-down list), locate the desired parameter and modify its value as desired.

WARNING:

Do not modify the value of the Context parameter.

To add a section for a new emulator, do the following:

1. Add an entry at the end of the list at the top of the file in the following format:
EMUxx=NewSectionName

where xx is one more than the number of the last entry in the list.

2. Create the new section in the following format:
[NewSectionName]

Parameter1=Value1

Parameter2=Value1

…

ParameterN=ValueN

Caution:

The name of the new section must match the name you specified in the EMUxx entry at the top of the file in step 2a.

4. When you have finished, click Save to commit your changes and recalculate the Context parameters for all entries in the file.

5. Launch the newly added emulator and connect to an application session.

6. Use the MHO Status Tool to confirm that the MHO has successfully attached to the emulator's HLLAPI interface and detected the open session. See Troubleshooting Detection and Response with the SSO MHO Status Tool for instructions.

3.7.1 Emulator Configuration Parameter Reference

The table below lists the available emulator configuration parameters (and their values) that you can use to create an entry in the mfrmlist.ini file.

Note:

Boolean-type parameters support the following values: true, y, yes, 1, false, n, no, 0.

Setting

Description

GroupName

Type: text

(Groups emulator definitions and only allows one in a group to load

Type: text

DisplayName

Type: text

Used internally on the command line to other MHO processes

RegistryName

Type: text

Specifies an INI file name to check.

Windows directory will be searched first, then the PATH variable.

If this value is specified, RegistryLoc specifies a section name and ValueName specifies an entry name in the section and must not be omitted.

Special Values:

WinIni - Indicates that the Windows INI file should be checked.

RegistryLoc

Type: text

Registry location path (see also: RegistryName, ValueName)

Specifies a registry location to search for ValueName in HKEY_LOCAL_MACHINE\Software tree.

Special Values:

\HKEY_CURRENT_USER\Software\"- If the entry starts with this text (case-sensitive), HKEY_CURRENT_USER\Software will be searched instead of HKEY_LOCAL_MACHINE\Software.

ValueName

Type: text

Registry key name (see also: RegistryName, StripFileName, DLLFile)

The value that specifies a registry or section name that specified the location of DLLFile.

If RegistryLoc is omitted, this value directly specifies where to load DLLFile from.

Special Values:

WinDir - Load dll from Windows directory.

SysDir - Load dll from Windows System directory.

HomeDir - Load dll from Logon Manager Installation directory.

EmulDir - Load dll from Logon Manager Emulator Installation directory.

"\" - If the path starts with this value, load dll from the specified directory on the drive where Windows is installed.

DLLFile

Type: text

Name of the dll to load.

StripFileName

Type: boolean

Strip the filename from the retrieved registry string.

PresentationSpaceSharing

Type: special

SUPER_WRITE to put emulator in a supervisor mode (not all emulators support this)

Process

Type: special

shared causes the emulator to be loaded in the original copy of the mho. Anything else and a new process is spawned.

ConvertPosType

Type: special

long, short - Use enhanced or standard HLLAPI interface for Convert Position and Convert RowCol (99) function.

Default: HLLAPIType setting.

QuerySessionsType

Type: special

long32, long, short, both - short and long will use standard or enhanced HLLAPI interface for Query Sessions (10) function. both will attempt to use enhanced HLLAPI interface first and then standard, if enhanced fails (doesn't always work, specifying correct value is better.) long32 is used for the Windows command prompt HLLAPI emulation.

Default: HLLAPIType setting.

ValidateQuerySessionsData

Type: boolean

Validates the data returned from QuerySessions before using it.

QuerySessionStatusType

Type: special

long, short - Use enhanced or standard HLLAPI interface for Query Session Status (22) function.

Default: HLLAPIType setting.

QueryHostUpdateType

Type: special

long, short - Use enhanced or standard HLLAPI interface for Query Host Update (24) function.

Default: HLLAPIType setting.

StartNotificationType

Type: special

long, short - Use enhanced or standard HLLAPI interface for Start Host Notification (23) function.

Default: HLLAPIType setting.

PlatformSize

Type: numeric

16, 32 - 16-bit or 32-bit HLLAPI.

Default: 32

IntSize

Type: numeric

16, 32 - Integer size used by the emulator.

Default: 32

QuerySystemType

Type: special

long, short - Use enhanced or standard HLLAPI interface for Connect Presentation Space (20) function.

Default: HLLAPIType setting.

UpdateNotificationHandling

Type: special

Special handling for return codes when update notification has occurred.

For example:

1.ReconnectSession

for return code 1, call internal function ReconnectSession

Functions available:

RecheckResetConnection - Calls reset, reattempts login

CheckLoginStatusAndReset - If no logins are pending, reset HLLAPI subsystem

ReconnectSession - Attempt to connect to the session

FirstLogin - Some emulators refuse to admit the screen has changed when first connecting

StartNotification - Attempt a login to the current session

WindowClass

Type: regexlist

Semicolon-separated list of regular expressions.

Window class matching. Includes regular expressions. Matches substrings.

WindowTitle

Type: regexlist

Semicolon-separated list of regular expressions.

Window title matching. Matches substrings.

Special Values:

$s - substituted by a session's short name. Substitution occurs before regular expression matching.

UseSendKeys

Type: regexlist

Use HLLAPI Send Key (3) to send keystrokes to the emulator (not to be confused with Windows SendKeys) instead of HLLAPI Copy String to Presentation Space (15)

QuerySystemRequired

Type: boolean

Make sure that the system is queried before doing a reset.

ChangeNotiticationBroken

Type: boolean

Some emulators did not implement change notification.

RequireVisibleWindow

Type: boolean

Don't log in if the window is hidden.

EmulatorFixedRowWidth

Type: boolean

Some emulators are incapable of determining how wide a row is.

HllapiExportedCallName

Type: text

The DLL's exported function name. Required if it's not "hllapi."

LogonUsingTimeout

Type: numeric

How long to wait for logon screen to appear in milliseconds.

Default: 1000

LoginDelay

Type: numeric

Do not log in sooner than this many milliseconds following the last attempt.

Default: 1

WinHLLAPIStartup

Type: version

If specified, calls WinHLLAPIStartup with specified requested version after loading the DLL. Calls WinHLLAPICleanup before unloading the dll.

If the call fails, dll will not be loaded.

Ex: 1.0 or 1.1

HllapiParamCommand

Type: boolean

Emulator requires all settings to be passed to it

IgnoreErrorCount

Type: boolean

After a few errors, some emulators need to be reset, others stop working if you do [true, false]

SupportsHwnd

Type: boolean

Logon Manager extension to HLLAPI spec. Only implemented in SsoConNT and SSoConCP [true, false]

HLLAPIType

Type: special

long, short - Use enhanced or standard HLLAPI interface for all HLLAPI functions.

Default: short

ConnectSessionType

Type: special

long, short - Use enhanced or standard HLLAPI interface for Connect Presentation Space (5) function.

Default: HLLAPIType setting.

3.8 Troubleshooting Form Detection

3.8.1 Agent detects the form when invoking the "Logon Using Logon Manager" tray icon option?

Manually invoke window detection by using the Logon Using Logon Manager option from the Agent's system tray icon, then do one of the following:

- If the Agent detects the window, the configuration data for your emulator may be missing from the mfrmlist.ini file, or it might be erroneous. See Viewing and Modifying Emulator Configuration for instructions on understanding and editing the contents of the mfrmlist.ini file.

- If the Agent does not detect the target window even when you manually invoke detection by using the Logon Using Logon Manager option from the Agent's tray icon, do the following:

- Make sure that the Auto-recognize option in the form definition's Options tab is enabled.

- Review the template for common configuration errors, such as a mistyped window title or class; also, determine whether the window title and/or class are dynamic, and reconfigure the template as appropriate.

3.8.2 Valid entry for the emulator exists in mfrmlist.ini?

If the emulator has been tested by Oracle and found to be compatible with Logon Manager, it is supported by Logon Manager out of the box and a corresponding entry exists for the emulator in the mfrmlist.ini file. The list of currently supported emulators can be found in the latest Logon Manager release notes, and can also be determined by looking for an entry for the emulator in question in the mfrmlist.ini file, as described in Viewing and Modifying Emulator Configuration.

If the emulator is not supported by Logon Manager out of the box and it is HLLAPI-compliant, you may add it to the mfrmlist.ini file (as described in Viewing and Modifying Emulator Configuration) in order to determine whether it is fully compatible with Logon Manager. While Oracle Support will aid you in this effort should you run into configuration issues, Oracle is unable to guarantee that an untested emulator will properly function with Logon Manager in all expected capacities.

Note:

If you add an unlisted emulator to the mfrmlist.ini file and find it to be fully functional with Logon Manager, Oracle requests that you submit the emulator name and version to Oracle Support so that we can consider including official support for that emulator in the next release of Oracle.

3.8.3 Has "Host/Mainframe Support" global Agent setting been disabled?

Check whether previously made changes to Logon Manager's configuration erroneously disabled the "Host/Mainframe Support" global Agent setting, located in the Logon Manager Administrative Console tree under Global Agent Settings > End-User Experience > Response > Host/Mainframe Apps. If the option is disabled, re-enable it and Publishing a Template to the Repository, if applicable.

3.8.4 Match text, field text, and corresponding coordinates correct?

Check whether the match text, field text, and the respective coordinates stored in the template match what's displayed by the application and correct any mismatches, if found. For more information Understanding Form Detection and Response.

3.8.5 Emulator's HLLAPI implementation up to date and enabled?

In some cases, the emulator's initial HLLAPI implementation might be incomplete or defective. If possible, Oracle recommends researching and applying any vendor updates that improve or expand the emulator's HLLAPI implementation in a way that improves the emulator's compatibility with Logon Manager. Also, make sure that the emulator's HLLAPI support is enabled and that the emulator is exposing session short-names via HLLAPI. If it doesn't, Logon Manager will be unable to detect a session within the emulator.

For more information on the level of your emulator's HLLAPI implementation, as well as instructions for configuring it, consult the emulator vendor. The Console help also provides quick tips on enabling HLLAPI support in most commonly used emulators.

3.8.6 Appropriate mainframe support component installed?

In order to interface with terminal emulators via HLLAPI, Logon Manager requires that the Mainframe Support (available under the Extensions node in the Logon Manager installer) is installed. Additionally, depending on your emulator, you might have to install additional helper components to fully enable Logon Manager with the emulator. (For more information on these helper components, see Understanding Form Detection and Response.)

If the Agent still does not detect the form, see Troubleshooting Detection and Response with the SSO MHO Status Tool.

3.9 Troubleshooting Form Response

3.9.1 Agent detects the form?

If the Agent does not detect the form, check whether the Auto-Recognize feature has been disabled, and if so, re-enable it. If the feature has not been disabled, see Troubleshooting Form Detection.

3.9.2 Agent injects credentials but does not submit them?

If the credentials are injected not automatically submitted, first check that the Auto-Submit option is enabled for the application - this causes the Agent to send the Enter keystroke as the default submit action. If Auto Submit is enabled but the Agent still does not submit them to the application, the application might require a special keystroke other than Enter (such as PF4) in order to submit the credentials. In such case, disable the Auto Submit feature and add the special keystroke to the logon sequence as described in Adding Keystrokes, Pauses, or Text to the Logon Sequence.

3.9.3 Enter keystroke explicitly added to the logon sequence?

If you have explicitly added the Enter keystroke to the logon sequence and the application is exhibiting erroneous behavior during logon, remove the Enter keystroke from the logon sequence. When the Auto Submit feature is enabled, the Agent automatically sends the Enter keystroke as the default submit action - together with the explicit Enter keystroke you have added, the application is receiving two Enter keystrokes instead of the expected one, which causes undesired behavior after logon.

3.9.4 Fields populated erratically?

If the Agent populates the fields erratically, i.e., inserts wrong, truncated, garbled, or blank values, check whether the field coordinates defined in the template are correct (by comparing them to the actual display shown in the emulator), and if not, correct them. If the coordinates are correct, add a pause after each action, as described in Adding Keystrokes, Pauses, or Text to the Logon Sequence. If the issue persists even after adding the pauses, see Troubleshooting Detection and Response with the SSO MHO Status Tool to determine the point of failure.

3.10 Troubleshooting a Logon Loop

Some applications display their logon form upon logout, which causes Logon Manager to recognize the logon form and automatically log you back on to the application. This creates an endless "logon loop" preventing you from logging out of the application. To prevent this loop from occurring, the administrator may choose to enable the logon grace period feature which forbids Logon Manager from logging on to an application within set time period since the last logon.

3.10.1 Post-logout form different from standard logon form?

Oracle recommends that you consider the "Logon Loop Grace Period" as well as matching if the logon form presented upon logout is sufficiently different from the application's standard logon form. If the forms cannot be uniquely distinguished, use the "Logon Loop Grace Period" feature described below.

3.10.2 Configuring the "Logon Loop Grace Period" option resolves logon loop?

If the post-logout form cannot be uniquely distinguished from the standard logon form, configure a grace period that will prevent the Agent from automatically logging on to the same application if the specified grace period has not fully elapsed.

To configure the logon loop grace period timer, do the following:

1. In the Logon Manager Administrative Console, open the desired template and select the Miscellaneous tab.

2. In the Logon Loop Grace Period field, select the desired mode of operation from the drop-down list:

- Prompt - if the Agent detects the application's logon form while the grace period is in effect, the Agent will prompt the user whether to complete the logon or ignore the application.

- Silent - if the Agent detects the application's logon form while the grace period is in effect, the Agent will ignore the application and not log the user on.

- None - deactivates the grace period timer. Agent will respond to the application every time it detects the application's logon form.

3. Do one of the following, depending on what you want the Agent to do while the grace period is in effect:

- If you want the Agent to log the user on each time the launch of the application's executable is detected, select the Reset for each process check box.

- If you would like the Agent to ignore the application until the grace period has expired, leave the Reset for each process check box blank.

4. Save your changes and commit them to your repository, if applicable.

Note:

If you have configured the logon grace period timer, and logon loop is still occurring for a specific form definition, make sure that the Adhere to logon loop grace period option in the form definition's Options tab is enabled.

If this does not resolve the logon loop for the application, contact Oracle Support for assistance.

3.11 Troubleshooting Detection and Response with the SSO MHO Status Tool

The MHO provides a HLLAPI status interface that displays real-time information describing MHO's interaction with terminal emulators. To display this interface, execute the MHO executable (ssomho.exe) with the /showmho switch:

<program_files_folder>\Passlogix\v-GO-SSO\Helper\Emulator\ssomho.exe /showmho

Oracle highly recommends creating a desktop shortcut to the tool so that you can launch the tool easily at your convenience without having to remember the exact syntax.

Note:

If the MHO does not detect at least one active HLLAPI interface on the system, it will shut down to conserve resources, which may impair the troubleshooting process. In order to keep the MHO running continuously, install the "DOS Window Support" component (described in Understanding Form Detection and Response), which will always expose its active HLLAPI interface to the MHO.

3.11.1 Understanding the MHO Status Tool Interface

The MHO status interface looks as follows:

The interface is comprised of the following sections:

- HLLAPI DLL Status pane - displays all the emulator entries present in the mfrmlist.ini file and the status of the associated HLLAPI interfaces: o Running - the emulator's interface has been detected and hooked on to by the MHO. Expanding a node with a Running status displays the detected session. In our example above, the NetManage Chameleon Hostlink emulator is in this state.

- Not loaded - the emulator's interface was not detected by the MHO. Expand this node to view the reason for the load failure is displayed as a sub-node under the emulator node. Typical reasons include:

- Registry path not found - the registry key which defines the path to the emulator's HLLAPI Dynamically Linked Library (DLL) cannot be found at the location specified in the mfrmlist.ini file. Consult the emulator vendor to obtain the correct value for this parameter and modify the mfrmlist.ini file entry for the emulator to correct this problem. In our example above, the IBM Personal Communications emulator is showing this error.

- DLL failed to load - the emulator's HLLAPI library was not found at the location specified by the registry path described above, or the file that exists at the specified location is corrupted and cannot be hooked on to by the MHO. In our example above, the Seagull BlueZone emulator is showing this error.

- Log data pane - this pane displays real-time information describing the interaction between the MHO and the emulator selected in the "HLLAPI DLL Status" pane.

The check boxes above the log data pane enable or disable the display of the following classes of events:

- HLLAPI - all HLLAPI communication between the MHO and the detected emulator interfaces. Leave this checked at all times or no log data will be captured.

- Emulator - emulator events such as user input or window instantiation.

- QuerySessions - session-related events, such as list of open sessions, detected session short-names, and so on.

- Screens - content of the emulator's display. Every time the MHO receives (or detects, if polling is enabled) a screen update event, the contents of the updated screen are captured.

- MatchData - attempted matches against the match text defined in the template, as well as the outcome of those attempts.

As the information displayed in the log data pane scrolls by quickly, whenever you notice something of interest, select the Pause check box to temporarily pause the data capture and copy the data in question into a text editor for more thorough analysis.

3.11.2 Using the MHO Status Tool to Diagnose Session Detection and Response

If you have created a mainframe application template but Logon Manager is not detecting the terminal session, the most common causes are:

- The emulator is not exposing a session short-name via HLLAPI. Logon Manager uses the session short-name to detect the session and initiate text matching. Some emulators require explicit configuration to expose the session short-name, either globally, or on a per-session basis. In this case, you would see the emulator listed in the "HLLAPI DLL Status" pane as Running but expanding the emulator's node would reveal no active session even though the session was connected in the emulator itself. Consult the vendor's documentation for information on how to enable this required feature.

- The emulator's HLLAPI support is disabled or not installed. In this case, you would see the emulator listed in the "HLLAPI DLL Status" pane as "Not loaded" and expanding its node would reveal either the "Registry path not found" or the "DLL failed to load" error described in the previous section. Consult the vendor's documentation for information on how to enable or install HLLAPI support.

- Bug or HLLAPI-noncompliance in the emulator's code. Consult the vendor to determine if an update is available. For example, with all event types enabled in the "Log data pane," you would not see any screen update events or session-related information (such as session opening or closing) even though the emulator would appear as "Running" in the "HLLAPI DLL Status" pane and expanding its node revealed a detected session.

Oracle Legal Notices

Copyright Notice

Copyright © 1994-2014, Oracle and/or its affiliates. All rights reserved.

Trademark Notice

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

License Restrictions Warranty/Consequential Damages Disclaimer

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

Warranty Disclaimer

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

Restricted Rights Notice

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

Hazardous Applications Notice

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Third-Party Content, Products, and Services Disclaimer

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Alpha and Beta Draft Documentation Notice

If this document is in preproduction status:

This documentation is in preproduction status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.