6.5 Form Fill Policies

A Form Fill policy allows you to pre-populate fields in a form on first login and then save the information in the completed form to a secret store for subsequent logins. The user is prompted to reenter the information only when something changes such as when a password expires. Form Fill is one of the features of Access Manager that enable you to provide single sign-on for your users.

The HTML page determines the requirements for the Form Fill policy. This section describes the following:

6.5.1 Understanding an HTML Form

The following figure is an example of a Web page containing an HTML form:

Figure 6-26 Sample HTML Form

The information in this section uses this sample form to explain how to create a policy. This sample form deliberately contains a variety of field types:

  • Input items for Username and Password

  • Selection options for the Web server field

  • Radio buttons for the role

  • Check boxes for single sign-on

When you analyze a form, you need to decide if you want the policy to fill in all the fields or just some of them. You then need to look at the source HTML of the form to discover the names of the fields and their types.

An HTML form is created using a set of HTML tags. A form consists of elements such as fields, menus, check boxes, radio buttons, and push buttons that control how the form is completed and submitted. For more detailed information about forms, see the Forms section at www.w3.org.

The following HTML data corresponds to the sample form (see Figure 6-26). The lines that contain the information needed to create a Form Fill policy appear in bold type. Each line corresponds to a field in the form that requires information or allows the user to select information.

In the example, each bold line contains information about a field, its name, and type. You use this information in the policy to specify how the information in the field is filled.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 
   "http://www.w3.org/TR/html4/loose.dtd">
<html> 
<head> 
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 
  <title>Form Fill Test Page</title> 
</head> 
<body> 
  <form name="mylogin" action="validatepassword.php" method="post"
        id="mylogin"> 
    <table align="center" border="0" cellpadding="4" cellspacing="4"> 
      <tr align="center" valign="top"> 
        <td> 
          <p align="center"><font size="5">Novell Services Login
             </font></p> 
          <table align="center" border="0"> 
 
            <tr align="left"> 
              <td>Username:</td> 
              <td><input type="text" name="username" size="30"></td> 
            </tr> 
 
            <tr align="left"> 
              <td>Password:</td> 
              <td><input type="password" name="password" size="30">
              </td> 
            </tr> 
 
            <tr align="left"> 
              <td>City of<br>Employment:</td> 
              <td><input type="text" name="city" size="30"></td> 
            </tr> 
 
            <tr align="left"> 
              <td>Web server:</td> 
              <td> 
                <select name="webserv" size="1"> 
                  <option value="default" selected> 
                    --- Choose a server --- 
                  </option> 
                  <option value="Human Resources"> 
                    Human Resources 
                  </option> 
                  <option value="Development"> 
                    Development 
                  </option> 
                  <option value="Accounting"> 
                    Accounting 
                  </option> 
                  <option value="Sales"> 
                    Sales 
                  </option> 
                </select> 
              </td> 
            </tr> 
 
            <tr> 
              <td colspan="2" align="left" height="25" valign="top"> 
                <p></p> 
              </td> 
            </tr> 
 
            <tr align="left"> 
              <td>Please specify<br>your role:</td> 
              <td> 
                 <input name="role" value="admin" type="radio">
                        Admin<br> 
                 <input name="role" value="engineer" type="radio">
                       Engineer<br> 
                 <input name="role" value="manager" type="radio">
                       Manager<br> 
                 <input name="role" value="guest" type="radio">Guest 
              </td> 
            </tr> 
 
            <tr> 
              <td colspan="2" align="left" height="25" valign="top"
                  width="121"> 
                <p></p> 
              </td> 
            </tr> 
 
            <tr align="left"> 
              <td>Single Sign-on<br>to the following:</td> 
              <td> 
                <input name="mail" type="checkbox">Mail<br> 
                <input name="payroll" type="checkbox">Payroll<br> 
                <input name="selfservice" type="checkbox">
                             Self-service<br> 
              </td> 
            </tr> 
          </table> 
        </td> 
      </tr> 
 
      <tr> 
        <td colspan="2" align="center"> 
          <input value="Login" type="submit"> 
          <input type="reset"> 
        </td> 
      </tr> 
    </table> 
  </form> 
</body> 
</html>

6.5.2 Creating a Form Fill Policy for the Sample Form

The sample form has ten input fields and five selection options that need to be configured in the Form Fill policy. The following steps explain how to create a shared secret to store the values and use that shared secret to create a Form Fill policy for this sample form. For information about configuring the form fill policy for a complicated form with JavaScript, see Section 6.5.6, Configuring a Form Fill Policy for Forms With Scripts.

  1. In the Administration Console, click Policies > Policies.

  2. Select the policy container, then click New.

  3. Specify a display name for the policy and select Access Gateway: Form Fill for its type.

  4. (Optional) Specify a description for the Form Fill policy. This is useful if you plan to create multiple Form Fill policies.

    You might want to specify the name of the HTML page that contains the form this policy is designed to fill.

  5. In the Actions section, click New, then select Form Fill.

  6. In the Form Selection section, select Form Name and specify mylogin in the text box. The form name comes from the HTML page. See the following line in the source for the page:

    <form name="mylogin" action="validatepassword.php" method="post"         id="mylogin"> 
    
  7. In the Fill Options section, specify all the input fields and select options. For each new field, click New. Specify the fields in the order in which they appear on the form. For items that are not available in the other data types such as an LDAP or Liberty attribute, create shared secrets to store the value.

    The following table displays the Fill Options selected for each input field:

    Form Name

    Fill Options

    username

    Input Field Name: username

    Input Field Type: Text

    Input Field Value: Credential Profile: LDAP Credentials: LDAP User Name

    password

    Input Field Name: password

    Input Field Type: Password

    Input Field Value: Credential Profile: LDAP Credentials: LDAP Password

    webserv

    Input Field Name: webserv

    Input Field Type: Select

    Input Field Value: Shared Secret: sampleLogin: webserv

    To create this shared secret, click New Shared Secret, specify sampleLogin, then click OK. Select sampleLogin, click New Shared Secret Entry, specify webserv, then click OK.

    For more information, see Section 6.5.4, Creating and Managing Shared Secrets.

    To add more entries to the same secret store, such as role and mail, you need to manage the secrets from the Identity Server. Save your draft of the policy, then click Devices > Identity Servers > Shared Settings > Custom Attributes. Select the name of your secret store (in this example it is sampleLogin). Add the entries you need for role, mail, payroll, and selfservice. These names need to match the form name.

    role

    Input Field Name: role

    Input Field Type: Radio Button

    Input Field Value: Shared Secret: sampleLogin: role

    mail

    Input Field Name: mail

    Input Field Type: Checkbox

    Input Field Value: Shared Secret: sampleLogin: mail

    payroll

    Input Field Name: payroll

    Input Field Type: Checkbox

    Input Field Value: Shared Secret: sampleLogin: payroll

    selfservice

    Input Field Name: selfservice

    Input Field Type: Checkbox

    Input Field Value: Shared Secret: sampleLogin: selfservice

  8. In the Submit Options section, fill in the following fields:

    Auto Submit: Select this option to submit the form as soon as all the values are filled in. If this option is not selected, even though all the values are filled in for the user, the user must click the Submit button.

    Debug Mode: Select the Debug Mode option, which allows you to verify that the information is correct before submitting the form. If values must be filled in, you first see the form to add the values. When the form is submitted, you are presented with a JavaScript that contains all of the name/value pairs. To submit the form, you need to click the Submit button.

    Insert Text in Header: Select this option so you can add a static value. In the Text to Insert box, specify the city value.

    city = Provo
    
  9. To create a login failure policy, click New in the Actions section, then select Form Login Failure.

  10. In the Form Selection section, select Form Name and specify mylogin in the text box. The form name comes from the HTML page.

  11. In the Login Failure Processing section, fill in the following field:

    Clear Shared Secret Data Values from Policy: Select this option to clear the data stored in the Shared Secret object when login fails. Select the name you have given to this policy.

  12. Use the up-arrow button to move the Form Login Failure policy to the top of the policy list.

    You want the failure policy to execute first on login failure.

  13. To create an Inject JavaScript policy, click New in the Actions section, then select Inject JavaScript. This option adds the configured JavaScript to a HTML page and is available only in interactive mode. For more information about creating an Inject JavaScript policy, see Creating an Inject JavaScript Policy.

  14. In the Configure Javascripts section, select the option where you want the JavaScript inserted in the HTML page.

  15. Click OK.

  16. On the Policies page, click Apply Changes.

6.5.3 Implementing Form Fill Policies

Section 6.5.2, Creating a Form Fill Policy for the Sample Form section describes how to create a simple Form Fill policy for a few input fields. This section describes all available options and explains how to use them to create a Form Fill policy and a Login Failure policy.

Designing a Form Fill Policy

Besides analyzing the form and determining the data items that need to be filled (see Section 6.5.1, Understanding an HTML Form), you need to consider the following when designing the Form Fill policy:

Verifying the Content or Page Type of the Form

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

The 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, the Access Gateway Appliance skips the file.

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

Creating a Form Matching Rule

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. The Access Gateway uses the following rules, in the order listed, when determining whether a page contains the required form:

  1. Matches the protected resource path in the URL with the page. If they don’t match, the page is rejected. If they match, continues. For more information, see Using the URL of the Protected Resource.

  2. Checks for CGI criteria. If they don’t match, the page is rejected. If they match or no criteria is specified, continues. For more information, see Using CGI Matching Criteria.

  3. Checks for page matching criteria. If they don’t match, the page is rejected. If they match or no page matching criteria is specified, continues. For more information, see Using Page Matching Criteria.

  4. Checks the form name criteria (which can be the <FORM> name attribute, the <FORM> ID attribute, or a number). If it doesn’t match, the page is rejected. If it matches, the form is processed. For more information, see Using Form Name Criteria.

When the Access Gateway uses URL or CGI criteria, it can make a match early in the filling process. This allows the Access Gateway to fill the data from the Web server and send it, almost simultaneously, to the browser. However, if the Access Gateway is configured to use page matching criteria, the 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 the 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:

  • The URL does not contain any CGI data.

  • The URL displays generated pages that vary in content. For example, if your form fill login page and the login failure page share the same URL, you need to use page matching criteria.

Page matching criteria are the most processing-intense form of matching and should 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 the 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>Novell WebAccess</TITLE>

You would add this string as the value in the text box for the Page Matching Criteria option. Remember that white space is significant when white space is entered to the left of the value in the text box. To have the 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, you can use this string to identify the login failure page. You would add the following string as the value in the text box for the Page Matching Criteria option for the login failure Form Fill policy.

Please log in again.

To have the 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.

Using Form Name Criteria

After identifying the page, the Access Gateway needs to identify the form on the page. If there is only one form on the HTML page, the Access Gateway can easily identify 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 doesn’t have either of these attributes, you can use the Number option with a value of 1. The first form the Access Gateway finds on the page matches.

When multiple forms exist on the same HTML page, the easiest and fastest matching method is to give each form a unique name or unique ID on the HTML page. If the forms have the same name or ID, you need to 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 contains user information and another form contain user preferences. If both of these forms need to be filled in before the user can log in, then you can use the Number option set to 0, and the Fill Options section of the policy can contain fields for both forms, in the order in which they appear on the page.

Including JavaScript in a Form Fill Policy

The following figure illustrates a simple form:

Figure 6-27 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. Whether all the functions in the JavaScript need to be included in the policy is usually determined by trial and error. There are some clues you can use to determine the requirements:

  • If a function is called within the form, you should include it in the Form Fill policy. The above form calls two JavaScript functions, setCookie() and validate().

  • If a function is not called by the form, you probably do not need to include it. The above form has one JavaScript function that falls within this category, doCookie. You can probably leave out these types of functions, but only trial and error can determine whether that is true.

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.

Form Fill Character Sets (UTF-8)

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.

Creating a Form Fill Policy

  1. Examine the source code for the HTML form and determine what data the form requires and where that data is stored (LDAP attributes, Liberty User Profile attributes, shared secrets, credential profiles, etc.)

    Ideally, the form should be its own HTML page, and the page should be as small as possible. Form Fill must parse the entire file and assemble the body in contiguous memory before the first byte of the form is displayed to the user. For a large file, this can take enough time that your users might think the system has a problem.

    If it isn’t possible to have the form on its own HTML page, ensure that the form is easily identifiable on the page. For example, give the form a name or use CGI data (the text that the follows the question mark in the URL) to identify the page and form.

  2. In the Administration Console, click Policies > Policies.

  3. Select the policy container, then click New.

  4. Specify a name for the policy, select Access Gateway: Form Fill as its Type, then click OK.

  5. Fill in the following fields:

    Description: (Optional) Describe the purpose of this policy. Because Form Fill policies are customized to match the content of a specific HTML page, you might want to include the name of the page as part of the description.

    Priority: Determines the order in which a rule is applied in the policy, when the policy has multiple rules. Form Fill does not use this field.

  6. In the Actions section, click New and select Form Fill.

  7. In the Form Selection section, specify how the Access Gateway can identify the form on the page. Select one or more of the following methods. Be specific and use as few of the methods as possible. For information about how to use these options effectively, see Creating a Form Matching Rule.

    Form Name: Identities the form on the HTML page. Select one of the following:

    • Form Name: If the <form> element on your HTML page specifies a name attribute, select Form Name and specify the value of the name attribute in the text box. For example, suppose your form contains the following:

      <form name="mylogin" action="validatepassword.php" method="post" id="form1"> 
      

      For this form, you would specify mylogin in the text box.

    • Form Number: The Access Gateway numbers forms sequentially from the top of the HTML page. If your page has multiple forms, you can use Form Number option and specify the form’s sequential location in the text box.

    • Form ID: If the <form> element on your HTML page specifies an id attribute, select Form ID and specify the value of the id attribute in the text box.

      For example, if your form contains the following:

      <form name="mylogin" action="validatepassword.php" method="post" id="form1"> 
      

      For this form, you would specify form1 in the text box.

    For more information, see Using Form Name Criteria.

    CGI Matching Criteria: Allows the Access Gateway to evaluate the query string in the URL (the portion after the question mark) to differentiate pages that have the same URL. Consider the following URL:

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

    For this URL, enter the following string in the text box for CGI Matching Criteria:

    Action=User.login
    

    If possible, copy the text from the form and paste it into the CGI Matching Criteria text box.

    For more information, see Using CGI Matching Criteria.

    Page Matching Criteria: Causes the Access Gateway to search the HTML page for the specified text. If the specified text is found on the page, the page is a match for the policy. If it isn’t found, the page is not a match for the policy and the policy is not applied. For example, suppose your HTML page has the following string within the <FORM> element:

    <title>Form Fill Test Page</title>
    

    If you enter this string in the Page Matching Criteria box, the Access Gateway searches the form for this string. If it finds the string, it knows it has a match.

    White space is significant. If the text in the text box is left-justified, the text can be found anywhere on the HTML page. If the text contains leading white space, such as ten spaces, the text must be found with ten leading spaces. If possible, copy the text as it appears on the form and paste it into Page Matching Criteria text box.

    The more specific your information is, the faster Access Gateway can match the form. Parsing page matching criteria is a very intensive process. If possible, use the URL path specified for the protected resource or CGI Matching Criteria to identity the form.For more information, see Using Page Matching Criteria.

  8. In the Fill Options section, create an entry for all the input fields and select options in the form. For each input field or select option, you need to specify the following information:

    Input Field Name: Specifies the name of the field or option. This is the name attribute of the element on the form.

    Input Field Type: Specifies the type attribute for the input field or select option in the form. Select one of the following data types for the field:

    • Text: Indicates that the field is a text field on the form.

    • Password: Indicates that the field is a password field on the form.

    • Checkbox: Indicates that the field is a check box on the form.

    • Radio Button: Indicates that the field is a radio button on the form.

    • Select: Indicates that the field is a select option on the form.

    • Hidden: Indicates that the field is an input field, but that this field is hidden from the user.

    • Not Specified: Indicates that the field is an input field, but the data type is not specified in the form.

    Input Field Value: Specify the value for the field. You must specify the data type, then enter the value. Select one of the following data types:

    • Credential Profile: Specifies that the value should be retrieved from the credentials the user specified during authentication. If you have created a custom contract that uses credentials other than the ones listed below, do not use the Credential Profile as an input value.

      • LDAP Credentials: If you prompt the user for a username and password, select this option, then either LDAP User Name (the cn of the user) or LDAP User DN (the fully distinguished name of the user). Your Web server requirements determine which one you use.

        The default contracts assign the cn attribute to the Credential Profile. If your user store is an Active Directory server, the SAMAccountName attribute is used for the username and stored in the cn field of the LDAP Credential Profile.

      • X509 Credentials: If you prompt the user for a certificate, select this option, then select one of the following option depending on your Web server requirements.

        • X509 Public Certificate Subject: Specifies that the subject field from the certificate should be the value, which can match the DN of the user, depending upon who issued the certificate.

        • X509 Public Certificate Issuer: Specifies that the issuer field from the certificate should be the value, which is the name of the certificate authority (CA) that issued the certificate.

        • X509 Public Certificate: Specifies that the entire certificate should be the value.

        • X509 Serial Number: Specifies that the certificate serial number should be the value.

      • SAML Credential: Injects the SAML assertion as the value of the field when SAML is used for authentication. This value is usually used for the user’s password.

    • LDAP Attribute: Indicates that the value should be retrieved from the specified LDAP attribute. If the attribute you require does not appear in the list, click New LDAP Attribute to add the attribute.

      The Refresh Data Every option allows you to determine when to send a query to the LDAP server to verify the current value of the attribute. Because querying the LDAP server slows down the processing of a policy, LDAP attribute values are normally cached for the user session.

      Change the value of this option from session to a more frequent interval only on those attributes that are critical to the security of your system or to the design of your work flow. You can select to cache the value for the session, for the request, or for a time interval varying from 5 seconds to 60 minutes.

    • Liberty User Profile: Indicates that the input field contains a Liberty User Profile attribute. In the value field, select the attribute. The attribute you select must be mapped to an LDAP attribute, and the Access Gateway retrieves its value from the LDAP directory.

    • Shared Secret: Indicates that the input field contains a user-entered value that is to be stored in the specified shared secret store.

      You can create your own value. Click New Shared Secret, specify a display name for the store, and Access Manager creates the store. Select the store, click New Shared Secret Entry, specify a name for the attribute, then click OK. The store can contain one name/value pair or a collection of name/value pairs. For more information, see Section 6.5.4, Creating and Managing Shared Secrets.

      The Refresh Data Every option allows you to determine when to send a query to verify the current value of the secret. Because querying slows down the processing of a policy, secret values are normally cached for the user session.

      Change the value of this option from session to a more frequent interval only on those secrets that are critical to the security of your system or to the design of your work flow. You can select to cache the value for the session, for the request, or for a time interval varying from 5 seconds to 60 minutes.

    • String Constant: Indicates that the input field contains a static value. In the text box, specify the value for the string constant.

    • Data Extension: (Conditional) If you have installed a data extension for Form Fill policies, injects the value that the extension retrieves. For more information about creating a data extension, see NetIQ Access Manager Developer Tools and Examples.

      NOTE:To improve the policy's performance, configure the LDAP Attributes, Credential Profile, Liberty User Profile, and Shared Secret attributes to be sent with authentication. For more information, see Configuring the Attributes Sent with Authentication.

    Data Conversion: Specify whether the case of the value entered by the user should be converted. Select one of the following options:

    • None: Indicates that no conversion should be performed on the value.

    • To Upper Case: Indicates that the value should be converted to uppercase.

    • To Lower Case: Indicates that the value should be converted to lowercase.

    • LDAP DN to NDAP Partial Dot Notation: Converts the LDAP DN (which uses typed comma notation) to eDirectory™ typeless dot notation.

      cn=jsmith,ou=Sales,o=novell to jsmith.sales.novell
      
    • LDAP DN to NDAP Leading Partial Dot Notation: Converts the LDAP DN to eDirectory typeless leading dot notation.

      cn=jsmith,ou=Sales,o=novell to .jsmith.sales.novell
      
    • LDAP DN to NDAP Fully Qualified Partial Dot Notation: Converts the LDAP DN to eDirectory typed dot notation.

      cn=jsmith,ou=Sales,o=novell to cn=jsmith.ou=Sales.o=novell
      
    • NDAP Fully Qualified Leading Dot Notation: Indicates eDirectory typed leading dot notation.

      .cn=jsmith.ou=Sales.o=novell
      

    Shared Secret Type: This option allows you to choose how the value you specified in the HTML form should be stored in the shared secret store.

    • None: When you select this default option, the value that you specified in the HTML form will be stored and retrieved from the shared secret store on subsequent login.

    • Remember: This option allows you to only store the value that you specified in the HTML form to the shared secret store.

    • Fill: This option allows you to only retrieve the value from the shared secret store.

      Example 6-1 Configuring a Form Fill Policy to Change Password Using Different Shared Secret Types

      For example, if you want to change password on a HTML form, the form will have Old Password, New Password, and Confirm Password fields. While configuring the Form Fill policy, on the password change page, select the shared secret type as Fill for the Old Password field. For the New Password and Confirm Password fields select shared secret type as Remember. All the three input field names should point to the same shared secret entry.

      When you access the password change page, the old password will be auto filled. The New Password and Confirm Password fields will be blank. Enter the New Password and Confirm Password fields and submit the page. The Old Password will be replaced with the New Password in the shared secret entry.

  9. In the Submit Options section, specify how you want the information in the form submitted to the Web server. (The HTML form page determines whether the post method or the get method is used for the submission.) Select one or more of the following options:

    Auto Submit: Indicates that you want the form submitted to the Web server without having the user confirm the submission by clicking a Submit button. If this option is not selected, Form Fill can fill in the data, but the user must click the Submit button before the data is sent to the Web server. When the form is not auto submitted, all the JavaScript on the form is executed.

    If you select Auto Submit, you can select one or more of the following options:

    • Debug Mode: Allows you to verify that the information in the filled-in form is valid before it is posted to the Web server. You can right-click and view the source that is being submitted to the Web server. If it is correct, click Submit to send it to the Web server.

      This is a troubleshooting option. We recommend that you use it when creating a new Form Fill policy, and that you remove it when you have determined that the policy is behaving as expected.

    • Mask Data: Replaces text input field values (username, password, etc.) with nov-ss-ff-masked instead of the value specified by the value parameter when the form is sent to the browser. The Access Gateway replaces these masked values with the real values when the Access Gateway submits the form to the Web server. The user’s browser never sees the actual values for these fields.

    • Detect Loop: In some scenarios, Form Fill processor tries to auto submit the form and every time login fails, the form fill request goes into infinite loop. The Login Failure policy cannot handle the following scenarios:

      • When a Web server returns the same login page to the Access Gateway after login failure.

      • When a Web server uses URL redirection or forwarding method to redirect a user to the same login page after login failure.

      If you have selected Auto Submit, you can select the Detect Loop option. This option allows you to detect the loop and auto submit stops. Access Manager will now ask you to fill the form in an interactive mode.

      This is achieved by creating a cookie in the browser, which will calculate the number of times the same form is posted to the Access Gateway in a given period of time. These values are set to 3 submits in 6 seconds.

      Limitations:

      • Use these options only when the Login Failure policy cannot detect or handle looping.

      • When Web server returns a different login form depending on a query-string or CGI portion of the URL, these options may not work as expected.

    Insert Text in Header: If this option is selected, you can use the Text to Insert option to specify text to add to the header. Use this option to insert static values into the form.

    Enable JavaScript Handling: Retains JavaScript from the original page if you have also selected the Auto Submit option. For a new Form Fill policy, you should also select the Debug Mode option so you can verify that you have included all the functions and statements that need to be executed in the policy.

    Use the following fields to specify how you want the JavaScript handled:

    • Functions to Keep: Specifies the functions you want executed from the JavaScript on the original page. By default, no functions on the page are executed. In the text box, use the following format:

      function setCookie()
      

      where function is a key word, followed by a space, and then the name of the function. Each function should be entered on a separate line, but you need only one function per script block. Everything must match exactly (name, capitalization, white space.) If you include the parentheses after the function name (setCookie()), they must exactly match the white space in the JavaScript. If possible, copy the function from the HTML page.

    • Statements to Execute on Submit: Specifies the functions you want executed just before the form is posted. Copy the JavaScript statement from the HTML page or add a JavaScript statement that you want called that is not on the HTML page. This allows you to modify the behavior of the form when you can’t modify the form.

      If the text box is empty, the JavaScript function specified in the submit field of the HTML page executes before the form is posted.

    For more information, see Including JavaScript in a Form Fill Policy.

  10. In the Error Handling section, specify how you want errors handled.

    Redirect to URL: When an LDAP or NSS error occurs, the user is redirected to the URL you specify in the text box. This is optional and allows you to customize the error handling process. If you do not customize it, a standard error page is displayed.

  11. Click OK, then click Apply Changes.

  12. Continue with Creating a Login Failure Policy or Assigning a Form Fill Policy to a Protected Resource.

Creating a Login Failure Policy

The Login Failure policy can be part of the same policy as the Form Fill policy, if both share the same URL. In this case, the Form Login Failure policy should be the first action in the policy, and the Form Fill policy should be the second action in the policy. This causes a login failure to execute the policy that clears the stored data and the Form Fill policy to prompt the user for new data.

If the user is redirected to a different page when login fails, it is best to create a separate policy for that page, create a protected resource that includes just that page, and assign your Form Login Failure policy to that resource.

To create a Login Failure policy:

  1. In the Administration Console, click Policies > Policies.

  2. Select the policy container, then click New.

  3. Specify a name for the policy, select Access Gateway: Form Fill as its Type, then click OK.

  4. In the Actions section, click New > Form Login Failure.

  5. In the Form Selection section, identify the form. This section uses the same criteria for identifying a form as the Form Fill policy. For more information, see Step 7 and Creating a Form Matching Rule.

  6. In the Login Failure Processing section, define the actions you want executed when a user fails to log in. Fill in the following fields:

    Redirect to URL: When a user’s login attempt fails, use this option with its text box to specify the URL you want the user redirected to. This is optional and allows you to customize what happens on login failures.

    Clear Shared Secret Data Values From Policy: Select this field to delete the user’s stored data for a Form Fill policy. If the user has the ability (and perhaps the requirement) to periodically change his or her password or any other information about the form, you need to select this field. Otherwise, the wrong data can be stored for the user, and the Access Gateway has no way of updating the information.

    From the list of Form Fill policies, select the policy whose stored values should be cleared with this Login Failure policy.

  7. Click OK > Apply Changes.

  8. Continue with Assigning a Form Fill Policy to a Protected Resource.

Creating an Inject JavaScript Policy

The Inject JavaScript policy adds the configured JavaScript to a protected resource page, when used in the interactive mode. You can create a standalone Inject JavaScript policy. You can also use this policy with the Form Fill policy. When you use the Form Fill policy with this one, configure the actions in the following sequence:

  1. Form Login Failure policy

  2. Form Fill policy

  3. Inject JavaScript policy

When the Inject JavaScript policy is configured along with the Form Fill policy, ensure that Auto Submit is not enabled for the Form Fill policy. In the Configure Javascripts section, select the option where you want to insert JavaScript in the HTML page. The following are examples based on the option you have selected.

In the head block

Selecting this option inserts the following JavaScript in the header:

<html>
<head>
<script language="JavaScript">
alert("Head");
</script>

At the beginning of the body block

Selecting this option inserts the following JavaScript just after the <body> tag.

<title> Test Java Script</title>
</head>
<body>
<script language="JavaScript">
alert("Begin Body");
</script>

At the end of the body block

Selecting this option inserts the following JavaScript just before the </body> tag.

BODY starts. <br>
Inject Java Script. <br>
BODY ends. <br>
<script language="JavaScript">
alert("End Body");
</script>
</body>
</html>

To create an Inject JavaScript policy:

  1. In the Administration Console, click Policies > Policies.

  2. Select the policy container, then click New.

  3. Specify a name for the policy, select Access Gateway: Form Fill as its Type, then click OK.

  4. In the Actions section, click New > Inject JavaScript.

  5. In the Form Selection section, select the criteria. If you are creating a standalone Inject JavaScript policy, specify the criteria. For more information, see Using CGI Matching Criteria and Using Page Matching Criteria. When you use the Inject JavaScript policy with the Form Fill policy, it uses the same criteria as that of the Form Fill policy.

    NOTE:If you do not specify a criteria in the Form Selection section, the Inject JavaScript policy is applied to all protected resource pages.

  6. Click OK > Apply Changes.

  7. Continue with Assigning a Form Fill Policy to a Protected Resource.

Sample Inject JavaScript Policy

The script in this example assumes that the contract timeout is five minutes. After four minutes, the user gets a popup message (timeout.html) with an option to refresh the page. If the user clicks on the option, the session is extended. If the user closes the popup or does not respond to the message, the system executes AGLogout and the session gets terminated.

Perform the following steps:

  1. Configure a Form Fill policy to insert Java Script into the head block of an HTML page.

    1. Go to Policies > New.

    2. Specify a name for the policy and select the type as Access Gateway: Form Fill.

    3. In the Actions section, click New and then select Inject JavaScript.

    4. Define a CGI matching Criteria or Page Matching Criteria.

    5. Under the Configure Javascript section, select In Head Block.

    6. Click Configure JavaScript and copy the following script:

      <script language="JavaScript">
      var x; 
      var timerID ;
      
      function timeoutClock()
      {
      if(x==60) // 60 seconds is the session time left when the session expire warning message appears. 
      { 
      newwindow = window.open('timeout.html','toWindow','toolbar=no,menubar=no,resizable=no,scrollbars=no,status=no,location=no,width=300,height=200'); 
      }
      if(x==0)
      {
      window.location.href = 'https://www.ag1.com:443/AGLogout' // AGLogout link. 
      }
      x=x-1;
      
      var t=setTimeout(function() {timeoutClock()} ,1000);
      
      }
      function resetClock()
      {
      clearTimeout(timerID);
      x = 300; //5 Minutes. This is the contact timeout defined.
      timeoutClock();
      }
      </script>
      

      In this script, set the value of x inside the function resetClock() according to the contract time out. In the example, x is set 300 that is equivalent to five minutes. Also, modify the following link in the script based on your configuration. This is a simple AGLogout link.

      window.location.href = 'https://www.ag1.com:443/AGLogout'
      
    7. Click OK > Apply Changes.

  2. Assign the policy to a protected resource.

    For more information, see Assigning a Form Fill Policy to a Protected Resource.

  3. Ensure to call the resetClock() function in the body tag of the HTML page (<body onload=resetClock();>). This initializes the counter to 300 every time the page is loaded.

  4. Create a timeout.html page, which contains warning message for the user that the session is going to end soon. The content of timeout.html can be as follows:

    <script type="text/javascript">
    var howLong = 60000;
    function closeMe()
    {
    var t = setTimeout(function() {self.close()},howLong);
    }
    function closeCurrentWindow()
    {
      window.close();
    }
    </script>
    Click <a href="javascript:window.opener.location.href = window.opener.location.href;window.close()";>[here]</a>to refresh now.
    <br>Else you will be logged out in 60 seconds
    <body onload=closeMe();
    Timeout
    </body>
    

Troubleshooting a Form Fill Policy

When a new Form Fill policy is not behaving as expected, use the following tips to discover the cause:

  • Select the Debug Mode option. This option prepares the form for submission, but doesn’t submit the form until you click the Submit button. This allows you to view the source, and determine if the policy is generating the required data.

  • Ensure that all input fields have valid names, that the fields are being filled in the correct order, and that any JavaScript commands have been entered correctly.

  • Enable Form Fill logging. Form Fill is a function of both the proxy service and the Embedded Service Provider. The Embedded Service Provider logs the evaluation of the policy, and the proxy logs the process of gathering the data. To enable the Embedded Service Provider tracing, see Section 17.6, Turning on Logging for Policy Evaluation. To enable Access Gateway log entries for Form Fill policies, see Enabling Form Fill Logging.

Check for the following problems with the source content of the Form Fill page:

Valid HTML Structure

The Form Fill process aborts if the page does not contain valid HTML structure. The page must contain the <html></html> tags, and the form must contain the <form></form> tags. If these tags are missing, you should correct the source page on the Web server. If this is not possible, you can create a rewriter policy to add the tags.

  • To add the <html> tag, have the rewriter policy search for the <body> tag, and replace it with <html><body>.

  • To add the </html> tag, have the rewriter policy search for the </body> tag, and replace it with </body></html>.

  • Use similar entries to add the <form></form> tags. You’ll need to discover which tag or phrase starts and stops the form.

Configure your rewriter policy so that it runs before the default rewriter policy. For more information about rewriter policies, see Section 3.8.5, Configuring HTML Rewriting.

The Option Element Does Not Contain a Value Attribute

If an <option> element does not contain a value attribute, Form Fill cannot fill the value. For example:

<form action="select.htm">
   <select name="top2">
      <option>Bob</option>
      <option>Alice</option>
   </select>
</form>

If your form contains <option> elements similar to these, they need to rewritten to contain a value attribute. For example:

<form action="select.htm">
   <select name="top2">
      <option value="name1">Bob</option>
      <option value="name2">Alice</option>
   </select>
</form>

If possible, change the source page on the Web server to add the value attribute to the <option> elements. If this is not possible, you can use a rewriter policy to add the value attribute.

  • For the Bob option, have the rewriter policy search for <option>Bob and replace it with <option value="name1">Bob.

  • For the Alice option, have the rewriter policy search for <option>Alice and replace it with <option value="name1">Alice.

Configure your rewriter policy so that it runs before the default rewriter policy. For more information about rewriter policies, see Section 3.8.5, Configuring HTML Rewriting.

The Form Element Does Not Contain a Method Attribute

If the <form> element does not contain a method attribute, Form Fill does not run an Auto Post. For example, the following form cannot use an Auto Post.

<form name="loginForm">

To enable Form Fill so that it can run an Auto Post, you need to add a method attribute to the <form> element. For example:

<form method="get" action="index.htm" name="loginForm">

If possible, change the source page on the Web server to add the method attribute to the <form> element. If this is not possible, you can use a rewriter policy to add the method attribute.

  • Search for <form

  • Replace this string with <form method="get" action="index.htm"

Configure your rewriter policy so that it runs before the default rewriter policy. For more information about rewriter policies, see Section 3.8.5, Configuring HTML Rewriting.

6.5.4 Creating and Managing Shared Secrets

A shared secret is an object that holds name and value pairs for Form Fill and Identity Injection policies.

  • If your HTML form prompts the user for more than credential information, you need to create a shared secret to store the values.

  • If your Web server requires some name/value pairs to be injected and these are not available from the HTTP request, you need to create a shared secret to store these name/value pairs so that they can be injected into the header before it is sent to the Web server.

Access Manager supports the creation and use of secrets from the following locations:

  • In the local configuration store

  • In eDirectory user stores that are running Novell SecretStore

  • In a user store that has been configured with a custom attribute for secrets

NOTE:Before using Access Manager to store and encrypt secrets, ensure that you choose your Preferred Encryption Method and change the default Encryption Password Hash Key value. If either of these options is changed after any secrets are stored, Access Manager will not be able to retrieve the secrets.

For more information about configuring Access Manager to store secrets, see Configuring a User Store for Secrets.

This section describes the following topics:

Naming Conventions for Shared Secrets

The policy engine allows you to create shared secrets and name the attributes for the store as you are creating an Identity Injection or Form Fill policy. When you create the shared secret, we recommend that you name the shared secret after the application for which you are creating the policy. Each value requires a name, and we recommend that you use the same name for the value name as the Input Field Name on a Form Fill policy or for the header name on an Identity Injection policy. For example if your e-mail application requires the e-mail address for the name on the login form, you could set up the following Shared Secret values:

Input Field Name

Input Field Value

Shared Secret Name

Entry Name

emailaddress

Shared Secret

emailapp

emailaddress

Your applications, how you use them, and your personal preferences determine whether you create one shared secret and use it for all your applications or whether you create a shared secret for each application.

  • If the applications use some of the same secrets, you can use the same shared secret for these applications. In this case, give the shared secret a name that reflects all of the applications using it.

  • If an application does not use the same secrets as another application and you want the freedom to remove the application and its secrets without affecting other applications, you should create a separate shared secret for this application.

  • If you are using Novell SecretStore, the secret names specified in your Access Manager policies need to match the names you have already configured.

A local shared secret store does not contain any name/value pairs until you configure a Form Fill policy to add name/value pairs or enable the Allow End Users to See Credential Profile option. This option allows the username and password to be stored in the local secret store. To set this option, click Devices > Identity Servers > Edit > Liberty > Web Service Providers > Credential Profile.

NOTE:You can create/edit/delete the values of a shared secret in the following scenarios:

  • When you use a Form Fill policy.

  • When you login to Identity Server and use the default landing page. Click on Profile > My Profile > Credentials > Credential List. This will be allowed only after enabling the Allow End Users to See Credential Profile as mentioned above.

  • When you use other NetIQ products such as Identity Manager and Secure Login. This can be used if you are using external eDirectory secret store.

  • The Identity Injection policy can use the shared secrets, but will not allow to create/edit/delete the values of shared secrets.

Creating a Shared Secret Independent of a Policy

You can create a shared secret as part of the process of creating a Form Fill or Identity Injection policy. You can also create a shared secret independent of a policy:

  1. In the Administration Console, click Devices > Identity Servers, then click Shared Settings > Custom Attributes.

  2. To create a new shared secret, click New in the Shared Secret Names section, and fill in the following fields:

    Secret Name: Specify a display name for the shared secret.

    Secret Entry Name. Specify an attribute name for a value you want to store.

  3. Click OK.

    The Identity Server creates and encrypts the object.

  4. To create additional attributes to store values, click the secret name, click New, specify a name, then click OK.

  5. Click OK.

Modifying and Deleting a Shared Secret

Before deleting a shared secret, you need to delete the policies that are using the shared secret or modify the policies to use a different shared secret. For information about deleting policies, see Deleting Policies.

Both Form Fill and Identity Injection policies can use shared secrets. The following instructions explain how to modify an Identity Injection policy to use a new shared secret and then how to delete the old shared secret.

  1. In the Administration Console, click Policies > Policies > [Name of Policy] > [Rule].

  2. Select the Value field that uses the shared secret you want to delete. Click its name, then click New Shared Secret.

  3. Specify the name for a new shared secret, then click OK.

  4. Click the name of the shared secret, select the new shared secret store, then click New Shared Secret Entry.

  5. Specify the attribute name for this shared secret entry, then click OK.

  6. Modify any other Value fields to use the new shared secret. Create new attributes as needed.

  7. To save the modifications to the policy, click OK twice, then Apply Changes.

  8. To delete the old shared secret, click Identity Servers > Shared Settings > Custom Attributes.

  9. Select the name of the old shared secret and the attributes, then click Delete.

6.5.5 Importing and Exporting Form Fill Policies

You can import and export the Form Fill policies in order to run them in other Access Manager configurations and to analyze the policy. The policy is exported as a text file with XML tags. We do not recommend editing the exported file with a text editor. Any changes you want to make to a policy ought to be done through the Administration Console.

To export a Form Fill policy:

  1. In the Administration Console, click Policies > Policies.

  2. Select a Form Fill policy, then click Export.

  3. (Optional) Modify the name suggested for the file.

  4. Click OK.

  5. Using the features of your browser, specify where the file is be copied.

To import a policy:

  1. Ensure that any referenced shared secret stores have been created. See Section 6.5.4, Creating and Managing Shared Secrets.

  2. If the policy uses LDAP or Liberty Profile attributes, ensure that the Identity Server has been configured for these same attributes.

  3. In the Administration Console, click Policies > Policies.

  4. Click Import, then browse to the location of the file.

  5. Click OK.

  6. When the policy appears in the list, click Apply Changes.

6.5.6 Configuring a Form Fill Policy for Forms With Scripts

The Form Fill policy created for the Linux Access Gateway works well with forms that contain a Submit button whose onclick action submits the form data to the Web server without executing any JavaScript or VBScript. However, when HTML forms contain complicated JavaScript or VBScript, Form Fill for that form fails.

For example, single sign-on by using the Form Fill policy to fill and autosubmit a form fails if the Submit button or the login button requires execution of a JavaScript function before submitting the form data to the Web server.

The following sections explain why Form Fill fails with the Form Fill policy when the HTML form contains complicated JavaScript. This section also describes the procedure to configure a Form Fill policy for such forms.

Why Does Form Fill Fail with the Default Policy?

The following section explains the process that takes place when a client requests a form that is configured with the Form Fill policy as described in Section 6.5, Form Fill Policies.

Figure 6-28 Sample Login Form with JavaScript

When the Access Gateway is configured with the default Form Fill policy, it adds the following function to the Login page received from the Web server. The bold text indicates where JavaScript is called.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--Generated by Apache Software Foundation (Xalan XSLTC)-->
<html class="detail/detail">

<head>
     <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
          <script type="text/JavaScript">
             /*SET up global vars*/
            //all the variable declaration
         
          <script type="text/JavaScript">              function dvdRegisterSelect() {                     }           </script>

     <title>Login Page</title>

</head>

<body id="tpz_body" style="width:99%; "onload="tpzOnLoad('login.prompt.g'); window.status='login.prompt.g'; ContextMenu.setup({'showForms':true}); ContextMenu.attach('detail/detail', 'cwc_optionsMenu_detail')" onfocus="window.status='login.prompt.g'" >

       <script type="text/JavaScript">           var arReenable = new Array();           function enableAll() {return reenableControls(arReenable);}        </script>

      <script type="text/JavaScript">          //all the variable declaration          function verify( f, bSubmitToSelf ){ return verifyFields                                (bSubmitToSelf,"\n");}      </script>

   <div>
      <a title="Login" class="tabSelected">Login</a>
   </div> 
      <form name="topaz" id="topaz" method="post" action="detail.do"                                                                                                                                                onsubmit="enableAll();return verify(this,true);">
<input type="hidden" name="focus" id="focus" value="var/user.id">
<input type="hidden" name="focusContents" id="focusContents" VALUE="testuser1" >
<input type="hidden" name="focusId" id="focusId" VALUE="X2" >
<input type="hidden" name="formname" id="formname" VALUE="login.prompt.g">
<input type="hidden" id="clientWidth" name="clientWidth" VALUE="1473" >

     <script type="text/javascript">         function printThisView(){tpzPrintDetail();}      </script>

<input type="text" id="X2" name="var/user.id" dvdVar="" onclick="handleOnClick(this,event);"  VALUE="testuser1" scripttype="text">
<input type="password" id="X5" name="var/old.password" dvdVar="" onclick="handleOnClick(this,
event);" " VALUE="novell081" >

<input type="button" name="0" id="X8" ButtonID="0" title="Login Page" value="Login" onclick="tpzDrillTable('', 'Login', '0','listdetail')" >
<input type="button" name="3" id="X9" ButtonID="3" title="Exit Login Page" value="Cancel" onclick="tpzDrillTable('', 'Cancel', '3','listdetail')" >
</form>

       <script language="JavaScript">           <!--              function LAGSubmitForm()                   {             document.forms[0].submit();                   }             LAGSubmitForm();           //-->        </script>
</body>
</html>

In the above code, the LAGSubmitForm() function calls the default submit action of the form, which uses a POST request to send the data to the Web server. But the submit action for the sample login form requires a JavaScript function to be executed. This function in turn submits the form data to the Web server. However, because the JavaScript is not executed by the default Form Fill policy, posting of the form data fails:

row=&__x=&thread=0&event=0&transaction=0&type=detail&focus=var%2Fuser.id&focusContents=testuser1&focusId=X2&focusReadOnly=&start=&count=&more=&tablename=&window=&close=&_blankFields=&_uncheckedBoxes=&formchanged=&formname=login.prompt.g&_multiSelection=&_multiSelection_tableId=&clientWidth=1473&var%2Fuser.id=testuser1&var%2Fold.password=novell081&var%2FL.language=en&0=Login&3=Cancel

Meanwhile, the browser expects to receive the following POST request and does not autosubmit the form:

row=&__x=&thread=0&event=0&transaction=0&type=detail&focus=var%2Fuser.id&focusContents=testuser1&focusId=X2&focusReadOnly=null&start=&count=&more=&tablename=&window=&close=&_blankFields=&_uncheckedBoxes=&formchanged=&formname=login.prompt.g&_multiSelection=&_multiSelection_tableId=&clientWidth=1217&var%2Fuser.id=testuser1&var%2Fold.password=novell081&var%2FL.language=en

Note the difference in POST requests sent to the browser. The first POST request has &0=Login&3=Cancel appended, which causes the login to fail.

For the browser to send the proper POST data, the Linux Access Gateway must add the following JavaScript statement to the Statements to execute section:

tpzDrillTable('','Login','0','listdetail');

Understanding How a Form Is Submitted

For the Access Gateway Appliance, you can configure the Form Fill policy to submit the form in the following ways:

  • Manual Submit: When a form is configured for manual submission, all the fields configured in the Form Fill policy are automatically filled by the Linux Access Gateway for the user. The user must then manually click the Submit button in the form to submit the form to the Web server protected by Linux Access Gateway.

  • Autosubmit: When Autosubmit is configured, the actual form is processed in such a way that all additional scripts not required to submit the form data to the Web server are removed. A temporary form is created on runtime with necessary form data in hidden format and with an additional LAGSubmitForm() function as follows:

    function LAGSubmitForm()
    {
    executeJavaScript();
    }
    LAGSubmitForm();
    

    In this example, executeJavaScript() is the function that executes the JavaScript or the VBScript statements configured in the Statements to execute section. If statements to be executed are present, you can also find the function definition for executeJavaScript() as follows:

    executeJavaScript()
    {
    document.forms[0].submit();
    }
    

    In this example, form[0] is the single form in the HTML page and submit is the default action associated with the submit or login button of the form that automatically submits the form to the Web server. This approach works for forms where the default action of the Submit button is to submit a POST request for the form data.

  • Autosubmit with Masking: When Autosubmit with masking is enabled for a form, the form data is submitted automatically to the Web server, but the data sent to the Web browser over the network is masked for additional security.

  • Submitting with the help of advanced options: If your form requires the execution of JavaScript when the form is submitted, you cannot use the Autosubmit options.This also means that single sign-on is disabled.

    To create a policy that allows autosubmitting for this type of form, you need to create the policy as described in Creating a Form Fill Policy for Autosubmission and create two advanced options as described in Configuring the Advanced Options for Autosubmission.

Creating a Form Fill Policy for Autosubmission

  1. In the Administration Console, click Policies > Policies.

  2. Select the policy container, then click New.

  3. Specify a display name for the policy and select Access Gateway: Form Fill for its type.

  4. (Optional) Specify a description for the Form Fill policy.

  5. In the Actions section, click New, then select Form Fill.

  6. In the Form Selection section, select Form Name and specify topaz in the text box.

  7. In the Fill Options section, specify all the input fields and select the options that you want.

  8. In the Submit Options section, select Auto Submit.

  9. Select Enable JavaScript Handling.

  10. Select Functions to Keep, then specify the JavaScript functions that need to be retained when the form is being automatically submitted. For the example form, specify the following functions:

    function dvdRegisterSelect()
    function enableAll()
    function verify(f, bSubmitToSelf)
    function printThisView()
    function tpzDrillTable(a,b,c,d)()
    
  11. Click OK.

  12. Select Statements to Execute and specify the form action that needs to be performed when the form is submitted. For the sample form, specify the following statement:

    function executeJavaScript()
    {
        tpzDrillTable('','Login','0','listdetail');
    }
    executeJavaScript();
    

    You must perform this step in order to execute the functions configured in the Functions to keep section because the Linux Access Gateway does not process HTML to include the LAGSubmitForm() function.

  13. Click OK.

  14. On the Policies page, click Apply Changes.

Configuring the Advanced Options for Autosubmission

When HTML forms contain complex JavaScript or VBScript, you must enable the following two advanced options:

  • #NAGGlobalOptions InPlaceSilent=on: This enables single sign-on to certain Web sites that require the login page to remain as is without any modifications to its structure. This option is equivalent to .enableInPlaceSilentFill in the 3.1 SP4 Access Gateway Appliance.

  • #NAGGlobalOptions InPlaceSilentPolicyDoesSubmit=on: This option enables form fill in HTML pages with complex JavaScript or VBScripts. This option is equivalent to .enableInPlaceSilentFillNew in the 3.1 SP4 Access Gateway Appliance.

To enable these options:

  1. In the Administration Console, click Access Gateways > Edit > Advanced Options.

  2. Add the following in the Advanced Options list:

    NAGGlobalOptions InPlaceSilent=on
    
    NAGGlobalOptions InPlaceSilentPolicyDoesSubmit=on
    
  3. Click OK.