About the IAG form authentication engine

Applies To: Intelligent Application Gateway (IAG)

The Whale Communications Intelligent Application Gateway (IAG) 2007 form authentication engine can be used in conjunction with Web and browser-embedded applications, to handle HTML forms sent by the application to the end user for the following implementations:

• Login forms: in this implementation, the form authentication engine automatically replies to authentication requests from the application. This option is used for applications that request users to authenticate using an HTML form, when the option “Automatically Reply to Application-Specific Authenticating Requests” is activated for the application, and the selected request type is “HTML Form” or “Both”.

  • For portal trunks, you configure this option in the Add Application Wizard.

  • For Webmail and Basic trunks, you configure this option in the Create New Trunk Wizard.

  • Once you add the application to a portal trunk, or create a trunk to publish a single Web application, you can change the selected configuration in the Web Settings tab of the Application Properties dialog box.

• Change Password forms: this option is used to update IAG’s internal credentials database with the new password, when a user changes the password during a session using an application’s Change Password form. In this implementation, when a user changes the password, the form authentication engine stores the new password in the internal credentials database. It can be used for applications that enable users to change their password during a session using an HTML form, and is implemented for both user-initiated and application-initiated password changes.

  Note

  The form authentication engine does not disrupt the application’s inherent login or change password flows.

The form authentication engine is configured by default to handle Login and Change Password HTML forms for out-of-the-box applications that use either of these form-types.

For example:

• Since the Citrix NFuse® FR3 application requires users to login using HTML forms, the form authentication engine is configured to handle login forms for this application.

• For the Microsoft Outlook Web Access 2003 application, the form authentication engine is configured to handle both Login and Change Password forms, since the application uses HTML forms for both interactions.

For generic applications, that are not supported out-of-the-box, and use HTML forms, you have to manually configure the form authentication engine to handle the forms. If required, you can also change the default configuration settings for out-of-the-box applications.

This topic describes:

• The manner in which the form authentication engine handles Login and Change Password forms.

• How you configure the form authentication engine.

Functional operation

This section describes how the form authentication engine processes HTML forms.

How Login Forms Are Processed

This section describes how the form authentication engine processes a Login HTML form, in order to automatically reply to an application’s authentication request. Since all transactions between the application server and the endpoint computer pass through IAG, the engine can intercept the form whenever necessary, in order to complete the authentication process with no user intervention.

Login forms are usually processed as follows:

• The user tries to login by sending the login request to the application server.

• The application server responds by sending the Login form.

• The form authentication engine intercepts the form on its way to the browser, and processes it as follows:

  • Depending on the configuration of this feature, the Engine can insert real or dummy values in input fields.

  • The Engine injects “autosubmit” and Onload Handler scripts, which will cause the form to be automatically returned from the browser to the application.

  It then sends the form to the endpoint browser.

• The Login form is displayed on the endpoint browser, and is then returned to the application without user intervention.

• The form authentication engine intercepts the form on its way from the browser, and processes it as follows:

  • Retrieves the user credentials from IAG’s internal credentials database.

  • Inserts the real values where required, replacing dummy values inserted previously.

  It then sends the filled-in form to the application server.

• The application server sends a response. If the authentication is successful, the user is logged in.

• Depending on the configuration, the form authentication engine can intercept the response and analyze it before transferring it to the endpoint browser, in order to determine whether the authentication was successful.

If the process fails at any stage, the form authentication engine sends the original Login form to the endpoint browser, so that the user can manually log into the application.

How Change Password Forms Are Processed

This section describes how the form authentication engine processes a Change Password HTML form, in order to update the internal credentials database with the new password. Since all transactions between the application server and the endpoint computer pass through IAG, the Engine can intercept the form whenever required in order to retrieve the new credentials from the form.

Change Password forms are usually processed as follows:

• When a password change is initiated, either by the user or by the application, the application server sends a Change Password form to the endpoint browser. At this stage, the form authentication engine can partially fill the form, such as fill in the user name or domain name, depending on the configuration of this option.

• The user fills in the required fields and submits the form, and the endpoint browser returns the Change Password form to the application server.

• The form authentication engine intercepts the form on its way to the application server, and analyzes it. If the user’s credentials have changed, the engine updates the internal credentials database with the new credentials. These credentials are used then by IAG for the remainder of the session, or until the credentials are changed again.

• At this stage, some applications might require the user to reauthenticate. In this case, the following takes place:

  • If the option “Automatically Reply to Application-Specific Authenticating Requests” is activated for the application, the Form authentication engine replies to the authentication request with the user’s new credentials.

  • If the option “Automatically Reply to Application-Specific Authenticating Requests” is not activated for the application, the authenticating request is forwarded to the user. The user replies to the request with the new credentials.

  Once the authentication is accepted by the application, the user can continue to work with the application.

Configuring the form authentication engine

The stages you go through in order to configure the form authentication engine include:

• Optionally configure browsers, browser groups, or scripts in the form authentication engine ’s data definition file, as described in Form authentication engine Custom Data Definition File.

• The authentication engine ’s configuration file refers to the data definition file whenever browsers or scripts must be defined. • Create and configure a custom configuration file, as described in Form authentication engine Custom Configuration File.

• Optionally, and for Login forms only, define your own “autosubmit” script, as described in Autosubmit Script. These scripts can be contained in stand-alone files, or as part of the data definition file.

• If the HTML form requires client-side processing, define it as described in Client-Side Processing.

• If the HTML form includes multi-value variables such as checkboxes, define them as described in Multi-Value Variables.

Conventions Used in the Engine’s Data Definition and Configuration Files

The Form authentication engine data definition and configuration files follow these conventions:

• Tag names are uppercase:

  <TAG>...</TAG>

• Attribute names are lowercase:

  <TAG attribute=value>...</TAG>

• Element values are either lower or upper case:

  <TAG>value</TAG>

  <TAG>VALUE</TAG>

  The case for each element is included in the element description, where relevant.

• Attribute values are lower case:

  <TAG attribute=value>...</TAG>

• Some XML elements take regular expressions in the data. When regular expressions are used, this is indicated in the description of the element usage. When using regular expressions, note the following:

  • Use the syntax described in Appendix B: “Regex++, Regular Expression Syntax”

  • In order to use a character as is, make sure it is preceded by a slash. For example, to use the asterisk (*) wildcard in data that takes regular expressions, enter \*

• For the following characters, CDATA type should be used:
  ampersand (&); angle brackets (< and >), quotation marks (").

  For example: <NAME><![CDATA[p&ssword]]></NAME>

Before You Begin

Before you begin, you should examine the application or applications for which you are configuring the form authentication engine, and identify the following for each application and for each form:

• Application-type:

  • If you are configuring the engine for a generic application, make sure the type you define here is identical to the type you will enter when you add the application to the trunk, in the Add Application Wizard, in the step “Application Setup”.

  • If you are changing the configuration of an out-of-the-box application, you can use the Editor to find the definition of the application-type in IAG, as described in Finding the Application Type in Editor.

  • For Basic trunks, the application-type is always OtherWeb.

    Note

    The application type must be alphanumeric, without spaces and without punctuation marks. It is recommended that the name is significant so that it can be easily identified.

• Primary host URL, that is, location of the page containing the Login or Change Password form.

• If required, one or more secondary host URLs, that is, alternative location or locations of the page containing the form.

• Whether different forms are used for different browsers.

• Name or ID used to identify the form.

• Method used to send the form.

• Whether the form contains an onload handler in the <BODY> tag, and whether different handler types are used for different browsers (Login forms only).

• How the application server responds to the success or failure of the form submission, in order for the Engine to be able to evaluate the result (optional).

• Names of the following controls:

  • For Login forms: controls that the form authentication engine fills in automatically in the form.

  • For Change Password forms: controls that the user fills in the form.

• Whether the form requires client-side processing in order to fill in any of the controls, and the names of the relevant controls.

Form authentication engine Custom Data Definition File

This section describes how you create and define a custom form authentication engine data definition file. This file is used to:

• Define browsers so that they are identified by the form authentication engine. The default file includes all browsers that are fully supported by IAG. You may add browsers to the file, but IAG support for such browsers is limited, as described in Supported Browsers in System Requirements.

• Create groups of browsers to which different form definitions in the configuration file refer.

• Hold scripts that are referred to from the configuration file.

The steps you need to take in order to prepare the data definition file are described in Creating a Custom Form authentication engine Data Definition File.

The contents of the data definition file, and explanations of how to define the file, are described in Syntax of the Form authentication engine Data Definition File.

Creating a Custom Form authentication engine Data Definition File

This section describes how you prepare and configure a custom form authentication engine data definition file.

To create a custom form authentication engine data definition file

1. Access the following location on IAG:

   …\Whale-Com\e-Gap\Von\Conf

2. Under the Conf folder, create the following subfolder:

   CustomUpdate.

   If such a folder already exists, use the existing folder.

3. From the Conf folder, copy the following file to the CustomUpdate subfolder:

   FormLoginDataDefinitions.xml

   Warning

   Do not make any changes to the default files located under the Conf folder.

4. Edit the file as required, as described in Syntax of the Form authentication engine Data Definition File.

5. At the Configuration program, click the Activate icon to activate the configuration, select the option “Apply changes made to external configuration settings”, and click Activate>.

Syntax of the form authentication engine Data Definition File

The data definition file contains the following:

• Browser definitions, described in <USER_AGENTS>.

• Browser group definitions, described in <USER_AGENT_GROUPS>.

• Scripts, described in <SCRIPTS>.

  Warning

  Do not change the root element in the data definition file:

  <WHLFILTFORMLOGIN_DATA_DEFINITIONS ver="x.x">

<USER_AGENTS>

Description

Defines the browsers that are supported by the form authentication engine. The default data definition file includes the browsers that are fully supported by IAG. You may add additional browsers to the list, but IAG support for such browsers is limited, as described in Supported Browsers in System Requirements. It is recommended that before attempting to add new browsers to the list, you contact technical support.

Usage

Only one <USER_AGENTS> element can reside in the data definition file.

Attributes & Attribute Values

None.

Child Elements

<USER_AGENTS> must contain one or more <USER_AGENT> elements.

[<USER_AGENTS>][<USER_AGENT>]

<USER_AGENT>

Description

Each <USER_AGENT> element defines a single browser, including:

• A unique ID to which the engine’s configuration file refers, and which is used within the data definition file to create groups of browsers.

• The name of the browser.

• The method by in which the browser is identified by the USER_AGENT header value, in the header sent by the browser.

Usage

An unlimited number of <USER_AGENT> elements can reside under

<USER_AGENTS>.

Attributes & Attribute Values

Attribute	Values	Type/Comments
id	An alphanumeric string	Mandatory. A short and unique ID that identifies the browser, for example: <USER_AGENT id="IntExplorer"> Note The string should not include spaces or special characters. Upper and lower case characters can be used, but these must be replicated exactly when you refer to the ID.

Child Elements

<USER_AGENT> must contain one each of the following elements:

• <NAME>.

• <SIGNATURE>.

[<USER_AGENTS>][<USER_AGENT>] > [<NAME>]

<NAME>

Description

The browser name.

Usage

• One, and only one, <NAME> element must be nested under each <USER_AGENT> element.

• Can contain special characters, mixed case, and spaces.

  For example: <NAME>Internet Explorer</NAME>

Attributes & Attribute Values

None.

Child Elements

None.

[<USER_AGENTS>][<USER_AGENT>] > [<SIGNATURE>]

<SIGNATURE>

Description

The browser’s signature in the header sent by the browser, in the USER_AGENT header value.

Usage

• One, and only one, <SIGNATURE> element must be nested under each <USER_AGENT> element.

• Can take an exact string or regular expressions, depending on the value of the check_by attribute.

Attributes & Attribute Values

Attribute	Values	Type/Comments
check_by	search, regex	Mandatory. The method used to identify the USER_AGENT header value in the header sent by the browser: search–an exact string regex–regular expressions

Child Elements

None.

Sample USER_AGENTS Code

In this sample code, note the following:

• The Internet Explorer browser is identified by the ID “IntExplorer”, which is used to refer to this <USER_AGENT> from within the data definition file, and from the configuration file.

• In the first <USER_AGENT> element, the Internet Explorer browser is identified by an exact string.

• In the second <USER_AGENT> element, the Mozilla® browser is identified by regular expressions.

  <USER_AGENTS>

  <USER_AGENT id="IntExplorer">

  <NAME>Internet Explorer</NAME>

  <SIGNATURE check_by="search">MSIE</SIGNATURE>

  </USER_AGENT>

  <USER_AGENT id="Mozilla">

  <NAME>Mozilla</NAME>

  <SIGNATURE check_by="regex">

  Mozilla/.*\(Macintosh;.*\).*Gecko\/.*

  </SIGNATURE>

  </USER_AGENT>

  </USER_AGENTS>

<USER_AGENT_GROUPS>

Description

Defines groups of browsers to which the configuration file refers. In cases where the form defined in the configuration file supports more than one browser, this mechanism enables you to enter a single value, instead of listing all of the relevant browsers. A browser group can include any browsers defined as <USER_AGENT> elements.

• ie

• Netscape

• any

Usage

Only one <USER_AGENT_GROUPS> element can reside in the data definition file.

Attributes & Attribute Values

None.

Child Elements

<USER_AGENT_GROUPS> must contain one or more <USER_AGENT_GROUP> elements.

[<USER_AGENT_GROUPS>][<USER_AGENT_GROUP>]

<USER_AGENT_GROUP>

Description

Defines a browser group.

Usage

• An unlimited number of <USER_AGENT_GROUP> elements can reside under <USER_AGENT_GROUPS>.

• The name you define here is used in the configuration file to refer to the browser group.

Attributes & Attribute Values

Attribute	Values	Type/Comments
name	An alphanumericstring	Mandatory. A short and unique ID that identifies the browser group. The string should not include spaces or special characters. Upper and lower case characters can be used, but these must be replicated exactly when you refer to the ID.

Child Elements

Each <USER_AGENT_GROUP> element must contain one or more <USER_AGENT_ID> elements.

[<USER_AGENT_GROUPS>] > [<USER_AGENT_GROUP>] > [<USER_AGENT_ID>]

<USER_AGENT_ID>

Description

The ID of a browser to be included in the browser group.

Usage

• An unlimited number of <USER_AGENT_ID> elements can reside under <USER_AGENT_GROUP>.

• The value you enter must be a browser ID, as defined in the id attribute of the <USER_AGENT> element.

• The same browser ID can be used in different browser groups.

Attributes & Attribute Values

None.

Child Elements

None.

Sample USER_AGENT_GROUPS Code

• ie

• Netscape

• any

<USER_AGENT_GROUPS>

<USER_AGENT_GROUP name="ie">

<USER_AGENT_ID>IntExplorer</USER_AGENT_ID>

</USER_AGENT_GROUP>

<USER_AGENT_GROUP name="Netscape">

<USER_AGENT_ID>NetscapeBrowser</USER_AGENT_ID>

</USER_AGENT_GROUP>

<USER_AGENT_GROUP name="any">

<USER_AGENT_ID>IntExplorer</USER_AGENT_ID>

<USER_AGENT_ID>NetscapeBrowser</USER_AGENT_ID>

</USER_AGENT_GROUP>

<USER_AGENT_GROUP name="ie_based">

<USER_AGENT_ID>IntExplorer</USER_AGENT_ID>

</USER_AGENT_GROUP>

<USER_AGENT_GROUP name="mozilla_based">

<USER_AGENT_ID>NetscapeBrowser</USER_AGENT_ID>

<USER_AGENT_ID>Firefox</USER_AGENT_ID>

<USER_AGENT_ID>Safari</USER_AGENT_ID>

<USER_AGENT_ID>Camino</USER_AGENT_ID>

<USER_AGENT_ID>Mozilla</USER_AGENT_ID>

</USER_AGENT_GROUP>

<USER_AGENT_GROUP name="all_supported">

<USER_AGENT_ID>IntExplorer</USER_AGENT_ID>

<USER_AGENT_ID>NetscapeBrowser</USER_AGENT_ID>

<USER_AGENT_ID>Firefox</USER_AGENT_ID>

<USER_AGENT_ID>Safari</USER_AGENT_ID>

<USER_AGENT_ID>Camino</USER_AGENT_ID>

<USER_AGENT_ID>Mozilla</USER_AGENT_ID>

</USER_AGENT_GROUP>

</USER_AGENT_GROUPS>

<SCRIPTS>

Description

This element can contain Java or Visual Basic® scripts to which you refer from the configuration file.

• WhaleHandler

• WhaleSubmitStandard

Usage

Only one <SCRIPTS> element can reside in the data definition file.

Attributes & Attribute Values

None.

Child Elements

<SCRIPTS> must contain one or more <SCRIPT> elements.

[<SCRIPTS>] > [<SCRIPT>]

<SCRIPT>

Description

Contains a script to which the configuration file refers.

Usage

• An unlimited number of <SCRIPT> elements can reside under <SCRIPTS>.

• The name attribute is used in the configuration file to refer to this script.

Attributes & Attribute Values

Attribute	Values	Type/Comments
name	An alphanumeric string	Mandatory. A short and unique ID that identifies the browser. The string should not include spaces or special characters. Upper and lower case characters can be used, but these must be replicated exactly when you refer to the ID. Caution, do not use the following: Names already in use in other scripts in the data definition file. The names WhaleSubmit or WhaleOnload, as these are reserved for use by IAG.

Child Elements

<SCRIPT> must contain one each of the following elements:

• <LANGUAGE>.

• <BODY>.

[<SCRIPTS>][<SCRIPT>] > [<LANGUAGE>]

<LANGUAGE>

Description

The script language.

Usage

• One, and only one, <LANGUAGE> element must be nested under each <SCRIPT> element.

• The values you can give include:

  • javascript—Javascript

  • vbscript—Visual Basic

Attributes & Attribute Values

None.

Child Elements

None.

[<SCRIPTS>][<SCRIPT>] > [<BODY>]

<BODY>

Description

Contains the script.

Usage

One, and only one, <BODY> element must be nested under each <SCRIPT> element.

Attributes & Attribute Values

Attribute	Values	Type/Comments
encoding	cdata, base64	Mandatory. Defines whether the string uses plain text or encoding: cdata–plain text base64–base64 encoding Tip Use the Editor to view and edit encoded strings. For a description refer to Editor.

Child Elements

None.

Sample SCRIPTS Code

<SCRIPTS>

<SCRIPT name="WhaleHandler">

<LANGUAGE>javascript</LANGUAGE>

<BODY encoding="cdata">

<![CDATA[

var gSafeOnload = new Array();

function WhaleOnload()

{

for (var i=0; i < gSafeOnload.length; i ++)

{

gSafeOnload[i]();

}// for i

}// WhaleOnload

if (window.onload)

{

gSafeOnload[0] = window.onload;

gSafeOnload[gSafeOnload.length] = WhaleSubmit;

window.onload = WhaleOnload;

}

else

{

window.onload = WhaleSubmit;

} // if window.onload

]]>

</BODY>

</SCRIPT>

<SCRIPT name="WhaleSubmitStandard">

<LANGUAGE>javascript</LANGUAGE>

<BODY encoding="cdata">

<![CDATA[

function WhaleSubmit()

{

formsCol = document.forms;

if (formsCol.length == 1)

{

document.forms[0].submit();

}

else

{

alert("more than one form");

}

return false;

}

]]>

</BODY>

</SCRIPT>

</SCRIPTS>

Form authentication engine Custom Configuration File

This section includes the following:

• The steps you need to take in order to prepare a custom configuration file, in Creating a Custom Form authentication engine Configuration File.

• Description of the configuration file, in Syntax of the Form authentication engine Configuration File.

• Sample code for both Login and Change Password configurations, in Sample Login Form Configuration.

  Note

  Some of the elements in the configuration file are related to pre-defined or user-defined items located in the data definition file. For more information on the contents and definitions of this file, refer to Form authentication engine Custom Data Definition File.

Creating a Custom Form authentication engine Configuration File

This section describes how you prepare and configure a custom configuration file. Use this file to handle HTML forms for custom applications, as well as to change the default settings of out-of-the-box applications. The same file is used for both Login and Change Password forms, for all relevant applications.

To create a custom configuration file

1. Access the following location on IAG:

   …\Whale-Com\e-Gap\Von\Conf\WizardDefaults\FormLogin

2. Under the FormLogin folder, create the following subfolder:

   CustomUpdate. If such a folder already exists, use the existing folder.

3. From the FormLogin folder, copy the following file to the CustomUpdate subfolder:

   FormLoginCustom.xml

4. Rename the file you have just copied FormLogin.xml

   Warning

   Do not make any changes to the default pages and scripts located under the FormLogin folder.

5. The file you have copied in step 3 contains one sample <APPLICATION> XML element. For each application you are configuring here, you need to create a dedicated <APPLICATION> element, and edit the values of each element as required.

   • The file contains one sample element. Replicate this element for each relevant application, and edit the values as required.

     Tip

     For out-of-the-box applications, you can copy the relevant <APPLICATION> section from the default configuration file, and edit the default settings as required. The default configuration file, FormLogin.xml, is located under the FormLogin folder.

   • Under the <APPLICATION> element, for each Login or Change Password form used by the application, you have to configure a dedicated <USAGE> element.

   • For a full description of the configuration file and the <APPLICATION> element, refer to Syntax of the Form authentication engine Configuration File.

     Warning

     After you edit the file as required, make sure to delete all unused elements. Note that, though the “autosubmit” script is not usually used with Change Password forms, for compatibility reasons, the elements that are related to this script must be defined for both form-types. Thus, the <SCRIPT_NAME> and <POLICY> elements must be included in the configuration of all forms.

6. When you finish editing the configuration file, at the Configuration program, click the Activate icon to activate the configuration, select the option “Apply changes made to external configuration settings”, and click Activate>.

Syntax of the Form authentication engine Configuration File

The Form authentication engine configuration file is structured as follows:

• For each custom application that requires form authentication, one <APPLICATION> element is nested under the root element. For a description of this element, including the elements nested under it, refer to <APPLICATION>.

• The same <APPLICATION> element handles all Login and Change Password forms for the application, as applicable. For each form, one <USAGE> element is nested under the <APPLICATION> element.

  Warning

  Do not change the root element in the file:

  <WHLFILTFORMLOGIN ver="x.x">

<APPLICATION>

Description

Provides the Engine with the information required to handle an application’s Login and Change Password forms.

Usage

• An unlimited number of <APPLICATION> elements can reside in the configuration file.

• One <APPLICATION> element is required for each application that uses custom form authentication.

Attributes & Attribute Values

None.

Child Elements

• <APPLICATION_TYPE>.

• <USAGE>.

[<APPLICATION>] > [<APPLICATION_TYPE>]

<APPLICATION_TYPE>

Description

The application type.

Usage

• One, and only one, <APPLICATION_TYPE> element must be nested under the <APPLICATION> element.

• For a description of the application-type, refer to Before You Begin.

Attributes & Attribute Values

None.

Child Elements

None.

[<APPLICATION>] > [<USAGE>]

<USAGE>

Description

Defines the configuration for a specific usage, either a Login form or a Change Password form.

Usage

• An unlimited number of <USAGE> elements can reside under each <APPLICATION> element.

• One <USAGE> element is required for each HTML form that is processed by the application:

  • If an application uses both Login and Change Password forms, you must define <USAGE> elements for both form-types.

  • If an application uses multi-forms, for example different Login forms for various user groups, you must define an individual <USAGE> element for each form.

Attributes & Attribute Values

Attribute	Values	Type/Comments
description	change_password, form_login	Mandatory. Defines the type of form being processed.

Child Elements

<USAGE> contains the following child elements:

• Mandatory <PRIMARY_HOST_URL>.

• Optional <SECONDARY_HOST_URL>.

• Mandatory <SCRIPT_NAME>.

• Mandatory <USER_AGENT>.

• <MULTIPLE_LOGIN> is optional for Login forms, and mandatory for Change Password forms.

• Mandatory <LOGIN_FORM>.

[<APPLICATION>] > [<USAGE>] > [<PRIMARY_HOST_URL>]

<PRIMARY_HOST_URL>

Description

The primary URL of the form. If there is more than one form in the current application, for example a Login form and a Change Password form, each form must have a unique <PRIMARY_HOST_URL> value.

Usage

• One, and only one, <PRIMARY_HOST_URL> element must be nested under each <USAGE> element.

• All <PRIMARY_HOST_URL> elements nested under the same <APPLICATION> element must have unique values.

• Must be a regular expression.

  Note

  Tune the URL as strictly as possible.

Attributes & Attribute Values

None.

Child Elements

None.

[<APPLICATION>] > [<USAGE>] > [<SECONDARY_HOST_URL>]

<SECONDARY_HOST_URL>

Description

Additional, secondary URL or URLs for the form.

For example: for an application where the primary URL is used for the first attempt to access the application, and the secondary URL is used for all subsequent attempts.

Usage

• <SECONDARY_HOST_URL> is optional.

• An unlimited number of <SECONDARY_HOST_URL> elements can be nested under each <USAGE> element.

• All <SECONDARY_HOST_URL> elements nested under the same <APPLICATION> element must have unique values.

• Must be a regular expression.

  Note

  Tune the URL as strictly as possible.

Attributes & Attribute Values

None.

Child Elements

None.

[<APPLICATION>] > [<USAGE>] > [<SCRIPT_NAME>]

<SCRIPT_NAME>

Description

Name of the “autosubmit” script that causes the form to be returned from the browser to the Form authentication engine without user intervention. You can create a custom script, or use the default WhaleSubmitStandard script provided in the data definition file.

• For a description of where the “autosubmit” script is used in the login process, refer to How Login Forms Are Processed in Functional Operation.

• For a detailed description of the script, and of how to create a custom script, refer to Autosubmit Script Functional Operation.

Usage

• One and only one <SCRIPT_NAME> element must be nested under each <USAGE> element.

• You can use the same script for different forms, or create a different script with a different name for each form.

• The location of the script is indicated by the source attribute.

Attributes & Attribute Values

Attribute	Values	Type/Comments
source	data_definition, file	Mandatory. Defines the location where the script is stored: data_definition–the script resides in the data definition file. The value of the element is the name of the script as defined in the value of the name attribute of the <SCRIPT> element. Make sure you use the exact value, including upper and lower case usage. For example: <SCRIPT_NAME source= "data_definition"> WhaleHandler </SCRIPT_NAME> file—the script resides in a separate file. The value of the element is the name of the file. The file extension is mandatory and must be either .js or .vbs. For example: <SCRIPT_NAME source="file"> Autosubmit.js</SCRIPT_NAME>

Child Elements

None.

[<APPLICATION>] > [<USAGE>] > [<USER_AGENT>]

<USER_AGENT>

Description

Defines the following:

• Method used for script injection in the form.

• Supported browser or browsers. That is, the browser or browsers where IAG supports the application for which you are configuring form authentication.

  Note

  For a list of the browsers on which IAG form authentication is fully supported, refer to Supported Browsers in System Requirements. Other browsers can be used, with limited support, as described in the same section.

Usage

• <USER_AGENT> elements can refer to single browsers or to groups of browsers, which are defined in the data definition file under <USER_AGENTS> and <USER_AGENT_GROUPS>.

• At least one <USER_AGENT> element must be nested under each <USAGE> element.

• Any number of <USER_AGENT> elements can be nested under each <USAGE> element. The number of <USER_AGENT> elements is determined as follows:

  • If only one browser-type is supported, use a single <USER_AGENT> element for that browser.

  • If more than one browser-type is supported, and the form’s behavior is identical for all browser-types, use either a single <USER_AGENT> element pointing to an appropriate browser group.

    Tip

    You can use one of the pre-defined groups, or create your own groups in the data definition file, as described in <USER_AGENT_GROUPS>.

  • If more than one browser-type is supported, and the form’s behavior differs between the browser-types. In this case, define multiple <USER AGENT> elements, one for each behavior.

Attributes & Attribute Values

None.

Child Elements

<USER_AGENT> must contain one of each of the following elements:

• <AGENT_TYPE>.

• <POLICY>.

• If the value of the <POLICY> element is “multiplatform”, the <USER_AGENT> element must also contain one <SCRIPT_NAME> element.

[<APPLICATION>] > [<USAGE>] > [<USER_AGENT>] > [<AGENT_TYPE>]

<AGENT_TYPE>

Description

Defines the browser or browser group for which form authentication is supported for this form.

Usage

• One, and only one, <AGENT_TYPE> element must be nested under each <USER_AGENT> element.

• <AGENT_TYPE> includes the name of a single browser or of a group of browsers, as defined in the data definition file, as follows:

  • For a single browser, the value of <AGENT_TYPE> is the value defined for the id attribute of the appropriate <USER_AGENT> element.

  • For a browser group, the value of <AGENT_TYPE> is the value defined for the name attribute of the appropriate <USER_AGENT_GROUP> element.

  Make sure you use the exact value, including upper and lower case usage.

Attributes & Attribute Values

Attribute	Values	Type/Comments
search	specific, group	Mandatory. Defines whether this <AGENT_TYPE> element refers to a single browser or to a group of browsers: specific–a single browser group–a browser group

Child Elements

None.

[<APPLICATION>] > [<USAGE>] > [<USER_AGENT>] > [<POLICY>]

<POLICY>

Description

Method by which the “autosubmit” and “onload” handler scripts are injected into the form, for the browser or browser groups determined by the <AGENT_TYPE> element or elements.

Usage

• One, and only one, <POLICY> element must be nested under each <USER_AGENT> element.

• <POLICY> values must be lower case.

• The value of <POLICY> can be one of the following:

Value	Description
limited	No “autosubmit” script is used. Login forms: use when the form should not be submitted automatically, but has to be presented on the endpoint browser for the user to complete. For example: when a token device such as SecurID or VASCO is used. This value is usually used for all Change Password forms.
multiplatform	Used for all forms, except for forms that are limited.
standard, extended	These policies are intended for internal IAG use only, and should not be used in the custom configuration file.

Attributes & Attribute Values

None.

Child Elements

None.

[<APPLICATION>] > [<USAGE>] > [<USER_AGENT>] > [<SCRIPT_NAME>]

<SCRIPT_NAME>

Description

Use if the value of the <POLICY> element is “multiplatform”. Defines the onload handler script to be injected. For more information on the multiplatform policy, see <POLICY>.

Usage

• One <SCRIPT_NAME> element must be nested under each <USER_AGENT> element where the value of the <POLICY> element is “multiplatform”.

• You can create a custom script, or use the default script provided with IAG inside the data definition file, under the element <SCRIPT name="WhaleHandler">

• The script can reside in a separate file, or as a <SCRIPT> element in the data definition file. The location of the script is indicated by the source attribute.

• <SCRIPT_NAME> includes the name the script, as follows:

  • If the script resides in the data definition file, the name of the script as defined in the value of the name attribute of the <SCRIPT> element. Make sure you use the exact value, including upper and lower case usage. For example: <SCRIPT_NAME source= "data_definition">WhaleHandler </SCRIPT_NAME>

  • If the script resides in a separate file, the name of the file, including the extension. The extension must be either .js or .vbs, and is mandatory. For example: <SCRIPT_NAME source="file"> Autosubmit.js</SCRIPT_NAME>

Attributes & Attribute Values

Attribute	Values	Type/Comments
source	data_definition file	Mandatory. Defines the location where the script is stored: data_definition–the script resides in the data definition file. file–the script resides in a separate file.

Child Elements

None.

[<APPLICATION>] > [<USAGE>] > [<USER_AGENT>] > [<FUNC_TO_INJECT>]

<FUNC_TO_INJECT>

Description

This element is intended for internal IAG use only, and should not be used in new <APPLICATION> elements in the configuration file.

[<APPLICATION>] > [<USAGE>] > [<MULTIPLE_LOGIN>]

<MULTIPLE_LOGIN>

Description

The <MULTIPLE_LOGIN> element defines whether the Form authentication engine is required to handle the form each time a user accesses it during a session, or only once in a session, at the initial access.

• Login forms: use the <MULTIPLE_LOGIN> element to define which method is used for multiple login attempts. When users open multiple instances of an application, the application can handle the multiple login attempts by one of two methods:

  • Using the same Login form for all the application login attempts. In this case, the Form authentication engine is required to handle the form each time the user logs into the application during the session.

  • Using one Login form for the initial login attempt, and a different Login form for all subsequent login attempts in a session. In this case, the Form authentication engine is required to handle the form only at the initial login attempt.

    For example: when accessing the Domino iNotes application, users are only required to authenticate during the initial login attempt. Subsequent attempts are automatically handled by the application, using a different form.

• Change Password forms: since the same form is used for all password change instances, use the <MULTIPLE_LOGIN> element to define the method whereby the Form authentication engine processes the form each time the user changes the password

Usage

• For Login forms, one <MULTIPLE_LOGIN> element can optionally be nested under each <USAGE> element.

• For Change Password forms, one <MULTIPLE_LOGIN> element must be nested under each <USAGE> element.

• <MULTIPLE_LOGIN> values must be lower case.

• The value of <MULTIPLE_LOGIN> can be one of the following:

Value	Description
true	The Form authentication engine processes the form at all login or password change attempts during the session. Use this value for all Change Password forms, and for Login forms where the application uses the same form for all login attempts.
false	Default behavior when a <MULTIPLE_LOGIN> element is not defined under the <USAGE> element. The Form authentication engine processes the form only once in a session, the first time the form in accessed. Use this value only for Login forms where the application uses a different form for subsequent login attempts.

Attributes & Attribute Values

None.

Child Elements

None.

[<APPLICATION>] > [<USAGE>] > [<LOGIN_FORM>]

<LOGIN_FORM>

Description

Defines the form that the Form authentication engine processes, for both Login and Change Password forms.

Usage

One, and only one, <LOGIN_FORM> element must be nested under each <USAGE> element.

Attributes & Attribute Values

None.

Child Elements

• <LOGIN_FORM> must contain one of the following elements:

  • <NAME>.

  Or,

  • <ID>.

• <LOGIN_FORM> must contain one, and one only, <METHOD> element.

• <LOGIN_FORM> must contain at least one <CONTROL> element. Define <CONTROL> elements for all the controls on the form that are affected by or used by the Form authentication engine .

  Warning

  Do not define <CONTROL> elements for controls that are not affected by or used by the Form authentication engine .

For example:

• For Login forms, define the fields that the Form authentication engine automatically fills in.

• For Change Password forms, define the fields where the Form authentication engine retrieves the value entered by the user in order to update the internal credentials database, such as the password.

• <LOGIN_FORM> can contain <LOGIN_EVALUATOR> elements as follows:

  • For Login forms, the <LOGIN_EVALUATOR> is optional.

  • For Change Password forms, at least one <LOGIN_EVALUATOR> must be defined.

  • For both form-types, a maximum of two <LOGIN_EVALUATOR> can reside under <LOGIN_FORM>, one for a positive evaluation and one for a negative evaluation.

[<APPLICATION>] > [<USAGE>] > [<LOGIN_FORM>] > [<NAME>]

<NAME>

Description

Name of the form.

Usage

Either a <NAME or an <ID> element must be nested under the <LOGIN_FORM> element.

Attributes & Attribute Values

None

Child Elements

None.

[<APPLICATION>] > [<USAGE>] > [<LOGIN_FORM>] > [<ID>]

<ID>

Description

The ID of the form.

Usage

Either an <ID or a <NAME> element must be nested under the <LOGIN_FORM> element.

Attributes & Attribute Values

None

Child Elements

None.

[<APPLICATION>] > [<USAGE>] > [<LOGIN_FORM>] > [<METHOD>]

<METHOD>

Description

HTTP method used to send the form.

Usage

• One, and only one, <METHOD> element must be nested under the <LOGIN_FORM> element.

• <METHOD> values must be lower case.

• The value of <METHOD> can be either “GET” or “POST”.

Attributes & Attribute Values

None.

Child Elements

None.

[<APPLICATION>] > [<USAGE>] > [<LOGIN_FORM>] > [<CONTROL>]

<CONTROL>

Description

Each <CONTROL> element defines a form “control”, such as a form field or a drop-down list. This control is handled by the Form authentication engine before the form is submitted to the end-user. The Engine supports all HTML control types.

Usage

• At least one <CONTROL> element must be nested under <LOGIN_FORM>.

• An unlimited number of <CONTROL> elements can be nested under <LOGIN_FORM>.

• Child-element definitions must be unique for each of the <CONTROL> elements nested under the same <LOGIN_FORM> element.

• Define <CONTROL> elements for all the controls on the form that are affected by or used by the Form authentication engine .

  For example:

  • For Login forms, define the fields that the Form authentication engine automatically fills in.

  • For Change Password forms, define the fields where the Form authentication engine retrieves the value entered by the user in order to update the internal credentials database, such as the password.

• If you are defining a multi-value control, such as a multiple checkbox, you must define a separate <CONTROL> element for each value. For details, see Multi-Value Variables.

  Warning

  Do not define <CONTROL> elements for controls that are not affected by or used by the Form authentication engine .

Attributes & Attribute Values

Mandatory handling attribute defines how the control is handled, as follows:

Attribute Value	Description
dummy_value	Normally used for Login forms only. The Form authentication engine sends a dummy, read-only value to the browser, and replaces it with the real value when the browser returns the form to the application server. The value itself is defined in the <DEF_VALUE> child-element. Note We recommend that you use this value in all cases where the real values should not be exposed on the endpoint browser. In most cases, we recommend that you do not use this value for User Name fields, since users might find it confusing. Use it only in cases where exposing the user name may cause a security problem.
app_default	Normally used for Login forms only. The Form authentication engine does not change control’s default value, and sets it to read-only. For example: use this value when the application uses a cookie to automatically set the control’s value. This type of behavior is typical for applications that automatically fill in the User Name field, such as email applications.
real_value	The Form authentication engine retrieves the real value from IAG’s internal credentials database and sends it to the browser, set as a read-only value. Tip Use this value for Change Password forms, for controls where the value of the <TYPE> child element is “USER_NAME”.
conf_default	Normally used for Login forms only. The Form authentication engine attempts to retrieve a value from IAG’s internal credentials database. If no value is available, the Form authentication engine sets the value to the dummy value defined in the <DEF_VALUE> child-element.
user_input	The Form authentication engine leaves the control blank when it sends it to the browser, and the value is provided by the enduser. In this case, set the value of the <POLICY> element to “limited”. Tip Use this value for Change Password forms, for controls where the value of the <TYPE> child element is “PASSWORD”.

Child Elements

<CONTROL> must contain one each of the following elements:

• <TYPE>.

• When the <TYPE> is “DOMAIN_USER”, the <CONTROL> element must also contain one <SEPARATOR> element.

• <NAME>.

• <DEF_VALUE>.

• <PROCESSING_SIDE>.

• When the <PROCESSING_SIDE> is “client”, the <CONTROL> element must also contain one <VARIABLE_NAME> element.

[<APPLICATION>] > [<USAGE>] > [<LOGIN_FORM>] > [<CONTROL>] > [<TYPE>]

<TYPE>

Description

Logical control-type; defines the usage of the data. For example: if the type is “PASSWORD”, the Form authentication engine treats the control value as a password.

Usage

• At least one <TYPE> element must be nested under each <CONTROL> element.

• The number of <TYPE> elements that can be nested under each <CONTROL> element depends on the value of <TYPE>:

  • If the value is any value other than “USER_PROVIDED”, only one <TYPE> element can be nested under each <CONTROL> element.

  • If the value is “USER_PROVIDED”, an unlimited number of <TYPE> elements can be nested under each <CONTROL> element.

• <TYPE> values must be upper case.

• The value of <TYPE> can be one of the following:

Value	Description
USER_NAME	The control contains the user name.
PASSWORD	The control contains the password.
DOMAIN	The control contains the domain name.
DOMAIN_USER	The control contains both the domain name and the user name. For this control-type, the <CONTROL> element must also include a <SEPARATOR> element. The control should be in this format: DOMAIN separator USER where separator is the character defined in the <SEPARATOR> element, for example: MyDomain\MyUserName
NEW_PASSWORD	Used in Change Password forms only. The control contains the new password. For this control-type, the value of the handling attribute of the <CONTROL> element must be “user_input”.
USER_PROVIDED	This control-type should be used only in one of these cases: • If the user must fill in a field, for example a token such as VASCO or SecurID, or a multi-value field. • For a value that exists in the internal credentials database, for example the department name or region. The value of the control is retrieved from IAG’s internal credentials database, which is the IAG Session Manager. In this case, the value must be defined in the IAG Session Manager, as a Session Resource parameter. You do this by adding the relevant code in one of the authentication hooks, for example in the file PostPostValidate.asp, using the following format: SetSessionResourceParam g_cookie, "<ApplicationID>", "<PARAMETER>", "<PARAMETER VALUE>" For example: SetSessionResourceParam g_cookie, "9786CBF4BA0743416C219DB", "mailbox", "name@company.com" For more information about authentication hooks, see Adding Functionality to the Default Pages. Note The identical value must be used in the Session Manager and in the USER_PROVIDED control If the value cannot be retrieved from IAG’s internal credentials database, the policy is downgraded to “limited”, the “autosubmit” script is not used, and the form is submitted to the endpoint browser for the end-user to fill. For detailed information about the limited policy, see <POLICY>.

Attributes & Attribute Values

None.

Child Elements

None.

[<APPLICATION>] > [<USAGE>] > [<LOGIN_FORM>] > [<CONTROL>] > [<SEPARATOR>]

<SEPARATOR>

Description

Used when the value of the <TYPE> element is “DOMAIN_USER”, to define the separator between the domain and the user.

Usage

When the value of <TYPE> is “DOMAIN_USER”, one <SEPARATOR> element must be nested under <CONTROL>.

The separator must be a single character, and can only be one of these three characters: \ / @

Attributes & Attribute Values

None.

Child Elements

None.

[<APPLICATION>] > [<USAGE>] > [<LOGIN_FORM>] > [<CONTROL>] > [<NAME>]

<NAME>

Description

Name of the control, as it appears in the form.

Usage

One, and only one, <NAME> element must be nested under each <CONTROL> element.

Attributes & Attribute Values

None.

Child Elements

None.

[<APPLICATION>] > [<USAGE>] > [<LOGIN_FORM>] > [<CONTROL>] > [<DEF_VALUE>]

<DEF_VALUE>

Description

Used as the control’s default value, which is sent to the endpoint browser, for the following controls:

• When the handling attribute of the <CONTROL> element is defined as “dummy_value”.

• When the handling attribute of the <CONTROL> element is defined as “conf_default”, and the Form authentication engine cannot retrieve a value from IAG’s internal credentials database.

  Note

  Although the default value is not used for controls where the handling attribute value is “real_value” or “app_default”, for compatibility reasons, a <DEF_VALUE> element must be defined for all controls.

Usage

• One, and only one, <DEF_VALUE> element must be nested under each <CONTROL> element.

• <DEF_VALUE> should comply with the application requirements. For example, the application might require that the password include a certain number of characters, or that it must be a combination of letters and numerals.

• When the value of <TYPE> is “DOMAIN_USER”:

  • The value of <DEF_VALUE> must be in the following format:

    DOMAIN separator USER

    where separator is the character defined in the <SEPARATOR> element, as described in <SEPARATOR>, for example: whldomain/whluser

  • The <CONTROL> element must contain a <SEPARATOR> child element.

Attributes & Attribute Values

None.

Child Elements

None.

[<APPLICATION>] > [<USAGE>] > [<LOGIN_FORM>] > [<CONTROL>] > [<PROCESSING_SIDE>]

<PROCESSING_SIDE>

Description

Defines whether this control is processed on the client-side, or on the server-side (IAG).

Usage

• One <PROCESSING_SIDE> element can be nested under each <CONTROL> element, as follows:

  • If client-side processing is required, <PROCESSING_SIDE> must be nested under each <CONTROL> element.

  • If client-side processing is not required, <PROCESSING_SIDE> is not required.

• When client-side processing is required, the <CONTROL> element must also include a <VARIABLE_NAME> element.

• The value of <PROCESSING_SIDE> can be one of the following:

Value	Description
client	Client-side processing is required, in order for the “autosubmit” script to retrieve data from the client before the form is submitted. For example: in cases where the authentication process has to query an external user database, and the query result should be submitted to the application server. For a full description of how you configure client-side processing refer to Client-Side Processing.
server	All processing is done at the server side. This is the default behavior, and if the <PROCESSING_SIDE> element is not used, all processing is done on the server-side. When defining server-side processing, you can use any of the available <POLICY> values.

Attributes & Attribute Values

None.

Child Elements

None.

[<APPLICATION>] > [<USAGE>] > [<LOGIN_FORM>] > [<CONTROL>] > [<VARIABLE_NAME>]

<VARIABLE_NAME>

Description

Used when client-side processing of the control is required, that is, the value of the <PROCESSING_SIDE> element is “client”. Name of the variable that holds the value of the control, as defined in the “autosubmit” script, in WhaleSubmit function list.

For a full description of how you configure client-side processing for a control refer to Client-Side Processing.

Usage

When the value of the <PROCESSING_SIDE> element is “client”, one <VARIABLE_NAME> element must be nested under <CONTROL>.

Attributes & Attribute Values

None.

Child Elements

None.

[<APPLICATION>] > [<USAGE>] > [<LOGIN_FORM>] > [<LOGIN_EVALUATOR>]

<LOGIN_EVALUATOR>

Description

Examines the response sent by the application server after submission of the form. This is used for the following:

• Login forms: for diagnostic purposes, in order to define whether the authentication succeeded or failed.

  Note

  For Login forms that use both HTTP 401 requests and HTML forms in the same authentication flow, we recommend that you do not use the <LOGIN EVALUATOR> element.

• Change Password forms: evaluates whether the user changed the password successfully, and, accordingly, determines whether or not to complete the change password process and enable the user to access the application.

The examination can be either of the header or of the body of the response, depending on the child-elements you define.

Usage

• For Login forms, <LOGIN_EVALUATOR> is optional.

• For Change Password forms, at least one <LOGIN_EVALUATOR> element must be nested under <LOGIN_FORM>.

• For both form-types, a maximum of two <LOGIN_EVALUATOR> elements can be nested under each <LOGIN_FORM> element, one for positive evaluation and one for negative evaluation.

Attributes & Attribute Values

Attribute	Values	Type/Comments
indicate	success, failure	Mandatory. Defines how the Form authentication engine determines whether form-handling succeeded or failed, if the strings defined in the <HEADER> or <SEARCH> child-elements are found in the response: success–if the strings are found it indicates that the form was submitted to the application successfully. failure–if the strings are found it indicates a failure; the form was not submitted successfully.

Child Elements

<LOGIN_EVALUATOR> must contain one or both of the following child elements:

• One <HEADER> element (optional).

• One or more <SEARCH> elements.

[<APPLICATION>] > [<USAGE>] > [<LOGIN_FORM>] > [<LOGIN_EVALUATOR>] > [<HEADER>]

<HEADER>

Description

Response header sent by the application server after the submission of the form. Used to evaluate the success or failure of the authentication.

Usage

• <HEADER> is optional.

• Only one <HEADER> element can be nested under each <LOGIN_EVALUATOR> element.

Attributes & Attribute Values

None.

Child Elements

<HEADER> must contain the following elements:

• <NAME>.

• <VALUE>.

[<APPLICATION>] > [<USAGE>] > [<LOGIN_FORM>] > [<LOGIN_EVALUATOR>] > [<HEADER>] > [<NAME>]

<NAME>

Description

Name of the response header that is used to evaluate the results of the authentication.

Usage

One, and only one, <NAME> element must be nested under each <HEADER> element.

Attributes & Attribute Values

None.

Child Elements

None.

[<APPLICATION>] > [<USAGE>] > [<LOGIN_FORM>] > [<LOGIN_EVALUATOR>] > [<HEADER>] > [<VALUE>]

<VALUE>

Description

Value of the response header that is used to evaluate the results of the authentication.

Usage

• One, and only one, <VALUE> element must be nested under each <HEADER> element.

• Must be a regular expression

  Note

  If you want to check the existence of a header, and not the content, set the value to .*:

  <VALUE>.*</VALUE>

Attributes & Attribute Values

None.

Child Elements

None.

[<APPLICATION>] > [<USAGE>] > [<LOGIN_FORM>] > [<LOGIN_EVALUATOR>] > [<SEARCH>]

<SEARCH>

Description

String in the response that is used to evaluate the results of the authentication.

Usage

The <LOGIN_EVALUATOR> element can contain an unlimited number of <SEARCH> elements.

Attributes & Attribute Values

Attribute	Values	Type/Comments
encoding	base64	Optional. Tip   Use the Editor to view and edit encoded strings. For a description refer to Editor.

Child Elements

None.

Sample Login Form Configuration

The sample code in this section handles form authentication for the Outlook Web Access 2003 application, for Login and Change Password forms:

• Sample Login Form Code

• Sample Change Password Code

For the clarity of the examples, each code snippet is nested under a separate <APPLICATION> element. In the configuration file, however, you define the handling of all forms for one application, including both Login and Change Password forms, under one <APPLICATION> element, with one <APPLICATION_TYPE> element.

Sample Login Form Code

The code in this example is used to define the processing of a Login form for the Outlook Web Access 2003 application. Note the following:

• In the <USAGE> element, the value of the description attribute is “form_login”.

• No <SECONDARY_HOST_URL> is required.

• The default “autosubmit” script is used to automatically submit the form from the client to the application server. In this case, the script referred to is a stand-alone script, indicated by the source attribute with the value “file”.

• The <POLICY> element uses the “multiplatform” policy. The subsequent <SCRIPT_NAME> element identifies the WhaleHandler script located inside the data definition file by using the attribute source with the value “data_definition”.

• The value of <MULTIPLE_LOGIN> is “true”, so that the Form authentication engine processes the form each time a user accesses it during a session, since the application uses the same form for all login attempts.

• The Form authentication engine automatically fills in the Password field. This is defined by a <CONTROL> element where the value of the attribute handling is “dummy_value”.

• The evaluation method is defined to identify failed login attempts by searching for the string “You could not be logged” in the response.

<APPLICATION >

<APPLICATION_TYPE>OWA2003</APPLICATION_TYPE>

<USAGE description="form_login">

<PRIMARY_HOST_URL><![CDATA[/exchweb/bin/auth/owalogon\.asp\

?url=https://[^/]+/exchange/?&reason=(0|3)]]>

</PRIMARY_HOST_URL>

<SCRIPT_NAME source="file">Autosubmit.js</SCRIPT_NAME>

<USER_AGENT>

<AGENT_TYPE search="group">any</AGENT_TYPE>

<POLICY>multiplatform</POLICY>

<SCRIPT_NAME source="data_definition">WhaleHandler

</SCRIPT_NAME>

</USER_AGENT>

<MULTIPLE_LOGIN>true</MULTIPLE_LOGIN>

<LOGIN_FORM>

<NAME>logonForm</NAME>

<METHOD>POST</METHOD>

<CONTROL handling="dummy_value">

<TYPE>DOMAIN_USER</TYPE>

<NAME>username</NAME>

<DEF_VALUE>whldomain/whluser</DEF_VALUE>

<SEPARATOR>/</SEPARATOR>

</CONTROL>

<CONTROL handling="dummy_value">

<TYPE>PASSWORD</TYPE>

<NAME>password</NAME>

<DEF_VALUE>whlpass</DEF_VALUE>

</CONTROL>

<LOGIN_EVALUATOR indicate="failure">

<SEARCH encoding="">You could not be logged</SEARCH>

</LOGIN_EVALUATOR>

</LOGIN_FORM>

</USAGE>

</APPLICATION>

Sample Change Password Code

The code in this example is used to define the processing of a Change Password form for the Outlook Web Access 2003 application. Note the following:

• In the <USAGE> element, the value of the attribute description is “change_password”.

• The <SCRIPT_NAME> element identifies the WhaleSubmitStandard script located inside the data definition file by using the attribute source with the value “data_definition”.

• The method used to inject the “autosubmit” script is identical for all browsers. Therefore, the <USER_AGENT> element is defined to use the browser group “all_supported” defined in the data definition file.

• The value of the <POLICY> element is “limited”, since the end-user is required to provide the new password.

• The Form authentication engine automatically fills in two controls, with the user-defined values stored in IAG’s internal credentials database. This is handled by two <CONTROL> elements, where the value of the attribute handling is “real_value”:

  • For the User Name field, the definition of the control-type is:

    <TYPE>USER</TYPE>.

  • For the Domain field, the definition of the control-type is:

    <TYPE>DOMAIN</TYPE>.

• For the New Password field that requires user input, the following is defined:

  • A <CONTROL> element where the value of the attribute handling is “user_input”.

  • Control type: <TYPE>NEW_PASSWORD</TYPE>.

• The evaluation method is defined to identify failed login attempts by searching for the string “You could not be logged”.

• The evaluation method is defined to identify the success of the password-change by searching for the string “successfully” in the response.

<APPLICATION >

<APPLICATION_TYPE>OWA2003</APPLICATION_TYPE>

<USAGE description="change_password">

<PRIMARY_HOST_URL>/iisadmpwd/aexp2b\.htr\?htt(ps|p)://[^/]+/

exchange/[^/]+/\?Cmd=close </PRIMARY_HOST_URL>

<SCRIPT_NAME source="data_definition">WhaleSubmitStandard

</SCRIPT_NAME>

<USER_AGENT>

<AGENT_TYPE search="group">all_supported</AGENT_TYPE>

<POLICY>limited</POLICY>

</USER_AGENT>

<MULTIPLE_LOGIN>true</MULTIPLE_LOGIN>

<LOGIN_FORM>

<NAME>logform</NAME>

<METHOD>POST</METHOD>

<CONTROL handling="real_value">

<TYPE>USER</TYPE>

<NAME>acct</NAME>

<DEF_VALUE>whluser</DEF_VALUE>

</CONTROL>

<CONTROL handling="real_value">

<TYPE>DOMAIN</TYPE>

<NAME>domain</NAME>

<DEF_VALUE>whldomain</DEF_VALUE>

</CONTROL>

<CONTROL handling="user_input">

<TYPE>NEW_PASSWORD</TYPE>

<NAME>new</NAME>

<DEF_VALUE>new</DEF_VALUE>

</CONTROL>

<LOGIN_EVALUATOR indicate="success">

<SEARCH encoding="">successfully</SEARCH>

</LOGIN_EVALUATOR>

</LOGIN_FORM>

</USAGE>

</APPLICATION>

Autosubmit Script

When the Form authentication engine processes a Login form, it injects an “autosubmit” script into the form. This script causes the form to be returned to the Form authentication engine without user intervention.

The “autosubmit” script can be used for:

• Automatic form submission.

• If required, client-side processing prior to submission, such as inserting a value that is stored on the endpoint computer into a control.

  Tip

  For a description of client-side processing, refer to Client-Side Processing.

In the Form authentication engine ’s configuration file, the “autosubmit” script that is used for the form is defined in the <SCRIPT_NAME> element. The JavaScript function that is defined in the script is injected into the HTML page that contains the form, immediately after the <HEAD> tag.

IAG provides a default script that handles automatic form submission, but does not handle any client-side processing. This script is located in the data definition file, under the element <SCRIPT name="WhaleSubmitStandard">.

For each form that you configure in the configuration file, you can select to use this default script, or to create and use a custom script, depending on the requirements of the application. You can use the same script for multiple forms and applications, or create different scripts for different forms or applications, in order to perform form- or application-specific operations. In all cases, you must refer to the script in the configuration file, in the <SCRIPT_NAME> element.

It is recommended that you contain custom “autosubmit” scripts inside the Form authentication engine ’s data definition file, under the element <SCRIPTS>. Alternatively, such scripts can be held in a stand-alone file. This section provides you with:

• Instructions on how to configure the “autosubmit” script if you do not use the default script provided with IAG, in “Configuring a Custom Autosubmit Script.

• A sample script, in Sample Autosubmit Script. This sample code is used for automatic form submission, with no clientside processing; for a description of how you configure client-side processing, including changes to the “autosubmit” script, refer to Client-Side Processing.

Configuring a Custom Autosubmit Script

This section describes how you configure a custom “autosubmit” script if you do not use the default script provided with IAG, and includes instructions for creating the script:

• Inside the Form authentication engine data definition file, as described in Creating a Custom “autosubmit” Script in the Data Definition File.

• As a stand-alone file, as described in Creating a Stand-Alone Custom “autosubmit” Script.

Note that the function you define in the script is injected into the form as is; the Form authentication engine does not examine the content of the file. A sample “autosubmit” script is provided in Sample Autosubmit Script.

Creating a Custom “autosubmit” Script in the Data Definition File

This is the recommended method for creating custom scripts.

Please note the following:

• You can use the default <SCRIPT name="WhaleSubmitStandard"> element located in the data definition file as an example of how to insert an “autosubmit” script in the data definition file, but take care not to make any modifications in this element.

• Do not use the names WhaleSubmit or WhaleOnload for custom <SCRIPT> elements, as these are reserved for use by IAG.

To create an “autosubmit” script in the data definition file

1. Create a custom data definition file, as described in Creating a Custom Form authentication engine Data Definition File. If a custom data definition file already exists, use the existing file.

2. Under the <SCRIPTS> element, create a new <SCRIPT> element, as described in <SCRIPTS>.

   Make sure to adhere to the following guidelines:

   • The “autosubmit” script must be self contained and should not require external parameters.

   • Give your script a unique name.

3. Refer to the custom script in the relevant section or sections of the configuration file, in the element <SCRIPT_NAME>.

   For example: if you named your script Customscript, in the definition of all the forms where you wish to use this script, refer to it as follows:

   <SCRIPT_NAME source=”data_definition”>Customscript</SCRIPT_NAME>

   For a description of this element, refer to <SCRIPT_NAME>.

4. If required, repeat steps 3–4 to create additional custom scripts.

Creating a Stand-Alone Custom “autosubmit” Script

This section describes how you create a stand-alone custom “autosubmit” file. Please note the following:

• You can use the default Autosubmit.js file as an example of an “autosubmit” file, but take care not to make any modifications in this file.

• When you name your custom file, do not use any of the file names already in use in the FormLogin folder, for example Autosubmit.js.

To configure a stand-alone “autosubmit” script

1. Access the following location on IAG:

   …\Whale-Com\e-Gap\Von\Conf\WizardDefaults\FormLogin

2. Under the FormLogin folder, create the following subfolder:

   CustomUpdate. If such a folder already exists, use the existing folder.

3. Create a JavaScript file, containing the “autosubmit” script, and place it in CustomUpdate the folder.

   Make sure to adhere to the following guidelines:

   • Give your file a unique name.

   • The function name in the script must always be WhaleSubmit().

   • The “autosubmit” script must be self contained and should not require external parameters.

4. Refer to the file containing the custom script in the relevant section or sections of the configuration file, in the element <SCRIPT_NAME>.

   For example: if you named your file Customsubmit.js, in the definition of all the forms where you wish to use this script, refer to it as follows:

   <SCRIPT_NAME source=”file”>Customsubmit.js</SCRIPT_NAME>

   For a description of this element, refer to <SCRIPT_NAME>.

5. If required, repeat steps 3–4 to create additional custom files.

6. When you finish creating the files, at the Configuration program, click the Activate icon to activate the configuration, select the option “Apply changes made to external configuration settings”, and click Activate>.

Sample Autosubmit Script

The script in this example is used for automatic form submission without client-side processing.

function WhaleSubmit()

{

formsCol = document.forms;

if (formsCol.length == 1)

{

document.forms[0].submit();

}

else

{

alert("more than one form");

}

return false;

}

Client-Side Processing

This section describes how you configure the automatic processing of a form on the client side, if required. For example: in cases where the authentication process has to query an external user database, and the query result should be submitted to the application server.

The configuration involves both the configuration file and the “autosubmit” script, and refers only to the configuration settings relevant for the clientside processing option. For a full description of the files refer to:

• Form authentication engine Custom Configuration File.

• Autosubmit Script.

  Warning

  Do not make any changes in the default pages and scripts supplied with IAG.

To configure client-side processing for a form

1. Create a custom configuration file, as described in Creating a Custom Form authentication engine Configuration File. If a custom file already exists, use the existing file.

2. In the configuration file, set the value of the <POLICY> element to either “extended” or “standard”.

3. Still in the configuration file, configure the relevant <CONTROL> element, where the client-side input is required, as follows:

   • Set the value of the handling attribute to one of the following, as applicable: “real_value”, “conf_default”, or “dummy_value”.

     Note

     Do not set the value of the handling attribute to “user_input” or “app_default”.

   • Add a <PROCESSING_SIDE> child-element, with the value “client”.

   • Add a <VARIABLE_NAME> element, containing the variable that holds the value of the control.

   The following sample code shows a <CONTROL> element that is configured for client-side processing, with a whlDomain variable:

   <CONTROL handling="real_value">

   <TYPE>DOMAIN</TYPE>

   <NAME>domain</NAME>

   <DEF_VALUE>whale domain</DEF_VALUE>

   <PROCESSING_SIDE>client</PROCESSING_SIDE>

   <VARIABLE_NAME>whlDomain</VARIABLE_NAME>

   </CONTROL>

4. Create a custom “autosubmit” script, as described in Autosubmit Script. If a custom script already exists, use the existing script.

5. In the custom “autosubmit” script, add the body of the WhaleSubmit function list, using the following format:

   function WhaleSubmit ()

   {

   // <FunctionBody>

   }

   Tip

   Inside the function body, you can reference variables such as the whlDomain variable cited in the example in step 3.

6. When you finish the configuration process, at the Configuration program, click the Activate icon to activate the configuration, select the option “Apply changes made to external configuration settings”, and click Activate>.

Multi-Value Variables

This section describes how you enable the use of multi-value variables, such as checkboxes, in a form.

The configuration involves both the configuration file and the “autosubmit” script, and refers only to the configuration settings relevant for the multi-value variables option. For a full description of the files refer to:

• Form authentication engine Custom Configuration File.

• Autosubmit Script.

  Warning

  Do not make any changes in the default pages and scripts supplied with IAG.

To configure multi-value variables for a form

1. Create a custom configuration file, as described in Creating a Custom Form authentication engine Configuration File. If a custom file already exists, use the existing file.

2. In the configuration file, configure a <CONTROL> element for each value within the multi-value variable, with the following definitions:

   • Set the value of the handling attribute to “conf_default”.

   • Set the value of the <TYPE> child-element to “USER_PROVIDED”.

   • The <NAME> child-element must be identical for all values within the multi-value variable.

   • The <DEF_VALUE> child-element must be unique for each value within the multi-value variable.

   • The <PROCESSING_SIDE> child-element must be identical for all values within the multi-value variable.

   • The <VARIABLE_NAME> child-element, if used, must be identical for all values within the multi-value variable.

   The following sample code shows a <CONTROL> element that is configured to handle a multi-value variable:

   <CONTROL handling="conf_default">

   <TYPE>USER_PROVIDED</TYPE>

   <NAME>Check</NAME>

   <DEF_VALUE>Two</DEF_VALUE>

   <PROCESSING_SIDE>client</PROCESSING_SIDE>

   <VARIABLE_NAME>whlCheck</VARIABLE_NAME>

   </CONTROL>

3. Create a custom “autosubmit” script, as described in Autosubmit Script. If a custom script already exists, use the existing script.

4. In the custom “autosubmit” script, add body of the function to the WhaleSubmit function list.

   In this example, if the value of the whlDomain variable is “whalecom”, and you configured two <CONTROL> elements with default values of “two” and “three”, the function is injected as the following carry:

   WhaleSubmit()

   {

   var whlCheck=['TypeTwo', 'TypeThree'];

   // <FunctionBody>

   }

5. When you finish the configuration process, at the Configuration program, click the Activate icon to activate the configuration, select the option “Apply changes made to external configuration settings”, and click Activate>.