Designing a Form Fill Policy

When configuring the protected resource that uses a Form Fill policy, the URL in the URL Path List must include the filename of the page that contains the form. Sometimes this is not possible. If the URL references a directory, Access Gateway has to parse the files that match the URL and determine which one contains the form.

Access Gateway Appliance checks the files for the following content types:

text/html
text/xml
text/css
text/javascript
application/javascript
application/x-javascript

If a file has no content type or has a type other than one in the above list, Access Gateway Appliance skips the file.

Access Gateway Service does not check for content type; it just parses the files that match the URL.

To create a successful Form Fill policy, you need to create a matching rule that matches the policy to the HTML page that contains the form, and then matches the form on the page. Access Gateway uses the following rules, in the order listed, when determining whether a page contains the required form:

When Access Gateway uses URL or CGI criteria, it can make a match early in the filling process. This allows Access Gateway to fill the data from the web server and send it, almost simultaneously, to the browser. However, if Access Gateway is configured to use page matching criteria, Access Gateway must retrieve the entire page from the web server, process it, and then determine whether the page needs to fill a form. All this processing must be completed before Access Gateway can send any data to the browser. Unless the page is quite small, users will clearly perceive the delay.

The form name matching criteria are not used for page matching. They are used to determine which form on the page is selected.

Use the following methods to match the page and the form:

Using the URL of the Protected Resource

When you assign a Form Fill policy to a protected resource, we recommend that the URL specified in the URL Path List contain the filename of the page. Usually, such a URL is enough to match the HTML page for the form. However, when pages are dynamically generated, the same filename is sometimes used to display different pages. Sometimes you can’t specify the filename in the URL. When this is the case, you need to use either the CGI Matching Criteria or the Page Matching Criteria to create an accurate page matching rule.

Using CGI Matching Criteria

If the page for the URL changes with the CGI portion of the URL (the portion that follows the question mark (?) and also called the query string), you can enter the CGI value. For example, consider the following URL:

http://webaccess.novell.com/servlet/webacc?Action=User.logout

If this is your URL, you can enter Action=User.logout as the value in the text box for the CGI Matching Criteria option. If the page generated from this URL always contains the page you want to match, you do not need to add any additional page matching criteria.

Using Page Matching Criteria

If your URL of your protected resource has the following characteristics, you need to use page matching criteria:

Page matching criteria are the most processing-intense form of matching and must be avoided if possible, but sometimes they are the only method available to identify the page with the correct form. For example, suppose you have a login failure page and login page that use the same URL, with no CGI data. You can use page matching criteria to ensure that Access Gateway matches the Form Fill policies for login and for login failure to the correct pages. You need to examine the source code for each page, and identify a string at the top of the page that uniquely identifies the page.

For example, the login page might contain a <TITLE> element that names the application the user is logging in to. If the login failure page does not contain the same <TITLE> element, you can use the <TITLE> element to identity the login page. Suppose that this is true and the login page contains the following string:

<TITLE>Micro Focus WebAccess</TITLE>

Add this string as the value in Page Matching Criteria. Remember that white space is significant when white space is entered to the left of the value in the text box. To have Access Gateway ignore white space, left-justify the value in the text box, or to ensure the correct amount of white space, copy and paste the HTML text directly from the source code of the web page.

Now you need to uniquely identify the login failure page. If this page does not have a <TITLE> element, look at the strings near the top of the page. Suppose the page contains the following string:

"Please log in again. You might have typed your name or password incorrectly."

Because the login page does not contain this string, use this string to identify the login failure page. Add the following string as the value in Page Matching Criteria for the login failure Form Fill policy.

Please log in again.

To ignore the white space, left-justify the value in the text box. To ensure the correct amount of white space, copy the HTML text directly from the source code of the web page.

Using Form Name Criteria

After identifying the page, Access Gateway needs to identify the form on the page. If only one form is available on the HTML page, Access Gateway easily identifies the form. If the form has a name or an ID attribute, you can use the value of the attribute to identify the form. If the form does not have either of these attributes, use the Number option with a value of 1. The first form Access Gateway finds on the page matches.

When multiple forms exist on the same HTML page, give each form a unique name or unique ID on the HTML page. If the forms have the same name or ID, use the Number option, and the order in which they appear on the page determines their number.

The value 0 for the Number option has special meaning. You use this value when you want the Form Fill policy to fill in values for all forms on the page. Sometimes a page has multiple forms, but all forms on the page must be filled in before the page can be submitted. For example, one form might contain user information and another form contain user preferences. If both forms need to be filled in before the user can log in, use the Number option set to 0. The Fill Options section of the policy can contain fields for both forms, in the order in which they appear on the page.

Figure 6-8 Form Login Page

The source code for this simple form reveals that it includes JavaScript functions:

<html><head><title>Login Page</title></head><body>
<h1 align="center">Login Page</h1>
<script language="JavaScript">
  function setCookie(){
    document.cookie="myCookieName=myCookieValue";
  }
  function validate(){
  if(document.mylogin.title.ldap.length == 0){
    alert("You must provide the title for the user!");
    return false;
  }
  return true;
}
</script>
<form name="jscript" action="viewInfo.php" method="post" onload="setCookie()">
<center>
<table border="1" cellpadding="4" cellspacing="4">
  <tbody><tr>
  <td>Username:</td>
  <td><input name="username" size="30" type="text"></td>
  </tr>
  <tr>
  <td>Title:</td>
   <td><input name="title" size="30" type="text"></td>
  </tr>
  <tr>
   <td>Password:</td>
  <td><input name="password" size="30" type="text"></td>
  </tr>
  <tr>
    <td>LDAP SERVER:</td>
  <td><input name="ldap" size="30" type="text"></td>
  </tr>
  <tr>
  <td colspan="2" align="center">
  <input value="Login" onclick="return validate();" type="submit">
  </td> 
</tr>
</tbody></table>
</center>
</form>

<script language="JavaScript">
function doCookie(){
document.cookie="myCookieName=myCookieValue";
}
return true;
}
</script>
</body></html>

The significant code snippets for determining whether to include JavaScript commands in the Form Fill policy are displayed in bold. The <script> elements are in bold because you need to be aware of all the JavaScript on the HTML page. Functions in the JavaScript that need to be included in the policy is determined by trial and error. The following are guidelines to determine the requirements:

For this form, select the Auto Submit option and the Enable JavaScript Handling option. If you wanted to test whether the doCookie() function was needed, you would specify the following in the Functions to Keep text box:

function setCookie()
function validate()

Each function needs to be placed on a separate line. This feature does a string compare, so the string after the function key word must match exactly a string in the JavaScript.

Access Manager supports only UTF-8 encoding (UCS Transformation Format 8) and ISO 8859-1. Otherwise, Form Fill translations to the secret data store cannot be guaranteed.