Creating a Form Fill Policy - NetIQ Access Manager 5.0 Administration Guide

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

The form must be its own HTML page, and the page must 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 longer time.

If it is not 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 follows the question mark in the URL) to identify the page and form.

Click Policies > Policies.

Select the policy container, then click New.

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

Specify the following details:

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.

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

In the Form Selection section, specify how 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, 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, specify mylogin in the text box.
Form Number: Access Gateway numbers forms sequentially from the top of the HTML page. If your page has multiple forms, use Form Number option and specify the form’s sequential location.
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, specify form1 in the text box.

For more information, see Using Form Name Criteria.

CGI Matching Criteria: Allows 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, specify Action=User.login in CGI Matching Criteria. If possible, copy the text from the form into CGI Matching Criteria. For more information, see Using CGI Matching Criteria.

Page Matching Criteria: Causes 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 Page Matching Criteria, 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 into Page Matching Criteria.

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.

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 or the ID attribute of the element on the form.

NOTE:If both name and ID attributes are available, specify the name attribute in Input Field Name. If you specify the ID attribute, form fill does not work.

If only the ID attribute is available, the form gets filled with values, but auto submit does not work.

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 must 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 must 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 must be the value, which is the name of the certificate authority (CA) that issued the certificate.
  - X509 Public Certificate: Specifies that the entire certificate must be the value.
  - X509 Serial Number: Specifies that the certificate serial number must 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 must 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 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.

NOTE:To store user-entered value in Shared Secret, ensure that you have specified the name attribute in Input Field Name. The ID attribute does not work with Shared Secret.

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.
Virtual Attribute: Indicates that the value must be retrieved from the specified virtual attribute.

The Refresh Data Every option allows you to determine when to send a query to verify the current value of the virtual attribute. Because querying slows down the processing of a policy, the virtual 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. See Using the Refresh Data Option.
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 Resources.

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 must be converted. Select one of the following options:

None: Indicates that no conversion must be performed on the value.
To Upper Case: Indicates that the value must be converted to uppercase.
To Lower Case: Indicates that the value must 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 must 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

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 must 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.

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. Access Gateway replaces these masked values with the real values when 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 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 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 must 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 must 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.

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.

Click OK > Apply Changes.

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