The purpose of a Form Fill policy is to tell iChain what data to use when filling in the form. The following sections discuss the components you use to create a Form Fill policy:
For information about the advanced features and tags not described in this section, see Section 14.4, Using Additional Form Fill Policy Options.
Form Fill policies follow standard XML document structure. Unless otherwise specified, each tag requires that an ending tag also be present. The ending tag is simply </tag>, where “tag” is the name of the tag. For example, the ending tag for <urlPolicy> is </urlPolicy>. If no ending tag is required (because the tag requires no data), the tag name ends with a slash (/). For example, <post/> or <debugPost/>.
When defining a basic Form Fill policy, you need to decide the following:
Determine how many <urlPolicy> elements are needed. See <urlPolicy> Element.
Identify which form uses the policy. See Header.
Determine which elements to use for filling in the fields. See Input Actions.
Provide commands for posting the information. See Post Actions.
Determine how the data should be saved and provide commands for saving it. See Storing Form Fill Data.
Specify a redirection policy if values are saved. See Handling Login Failures.
The <urlPolicy> is the main element in a Form Fill policy. You can have multiple <urlPolicy> sections in a Form Fill policy, each representing a separate set of criteria or actions to perform. If you are doing Form Fill for multiple URLs or HTML pages, you can have multiple <urlPolicy> sections in your Form Fill policy. You can also have multiple <urlPolicy> sections if you need to handle conditions such as login failures or error messages for the same URL.
The header tags identify the policy and the form that uses it.
The following tags are used to distinguish among multiple forms that use the same URL. For best performance, use as few of these tags as possible to distinguish one form from another.
The input tags identify which fields are to be filled and where the information can be obtained.
|
Tag or Attribute |
Purpose |
|---|---|
|
<injectStaticValue> |
Specifies information that you want to inject into the form instead of having the user enter this information. The <injectStaticValue> tag overrides any information the user enters in the field. For example: <injectStaticValue>city=Provo</injectStaticValue> For more information about injecting static values, see Section 14.4.2, Injecting Static Values. |
|
<actions> |
Specifies various actions for iChain to perform for this policy. The <actions> tag can contain <fill>, <post/>, <debugPost/>, <maskedPost/>, <redirect>, <errorRedirect> and <deleteRemembered> elements. |
|
<fill> |
Delimits a section of the form that requires input. It is a subordinate element of <actions> and must contain either an <input> element, a <select> element, or both. For example:
<actions>
<fill>
<input name="role" type="radio" value="~title">
</fill>
<post/>
</actions>
This example fills in one field. |
|
<input> |
Specifies the form fields that need information and specifies how that information is to be obtained. The fill section of the policy can have multiple <input> fields. The <input> fields you place within the <fill> element must be specified in the order they appear on the form. The <input> element has three required attributes (name, type, and value) and one optional case modifier attribute (ff_lower_upper). For example:
<fill>
<input name="username" type="text" value="~cn">
</fill>
|
|
name |
Specifies the name of the field. This must match the name specified in the form. |
|
type |
Specifies the type of field. This must match the type specified in the form and can be radio, checkbox, or text. The <select> element is used for list boxes. |
|
value |
Specifies how the information is to be obtained. The tilde operator allows you to determine whether the user must enter the information or whether an eDirectory™ attribute can be used to obtain the information. For more information on how to use this operator, see The Tilde (~) Operator. |
|
ff_lower_upper |
Converts the resulting value to either all uppercase or all lowercase. Valid values for this attribute are “lower” or “upper.” For example, to force lowercase conversion:
<fill>
<input name="username" type="text" value="~cn" ff_lower_upper="lower">
</fill>
To force uppercase conversion:
<fill>
<input name="username" type="text" value="~cn" ff_lower_upper="upper">
</fill>
If the attribute value is not specified as either “lower” or “upper”, no case conversion is performed on this field. |
|
<select> |
Sets up a list box field and specifies how that information is to be obtained. The fill section of the policy can have multiple <select> fields. The <select> fields you place within the <fill> element must be specified in the order they appear on the form. The <select> element has three required attributes (name, type, and value) and one optional case modifier attribute (ff_lower_upper). For example: <fill> <select name="webserv" type="listbox" value="~"> </fill> |
|
name |
Specifies the name of the select field. This must match the name specified in the form. |
|
type |
Specifies the type of field, and for a <select> element, it must be set to listbox. |
|
value |
Specifies how the information is to be obtained. The tilde operator allows you to determine whether the user must enter the information or whether an eDirectory attribute can be used to obtain the information. For more information on how to use this operator, see The Tilde (~) Operator. |
|
ff_lower_upper |
Converts the resulting value to either all uppercase or all lowercase. Valid values for this attribute are “lower” or “upper”. For example, to force lowercase conversion: <select> <input name="username" type="listbox" value="~cn" ff_lower_upper="lower"> </select> To force uppercase conversion: <select> <input name="username" type="listbox" value="~cn" ff_lower_upper="upper"> </select> If the attribute value is not specified as either “lower” or “upper,” no case conversion is performed on this field. |
The tilde (~) operator is used to designate how the value for the given form element is obtained. It specifies whether the user is prompted for the information, or if it is provided automatically by iChain. The tilde operator can be used in the following three ways:
~: A tilde with no trailing text indicates a user-supplied value.
The first time users access the form, they are presented with the original page and are allowed to enter values for each of the fields. For the users, the page behaves as though they are accessing the origin server directly or as if Form Fill is not active for the page.
After the users submit the form, iChain stores (via LDAP) the values they entered for each of the fields in either the ichainFormFillCrib attribute or SecretStore, depending on how you have configured your system. When the users access this page again, iChain retrieves (via LDAP) the previously stored values for each of these elements.
Suppose your form requests a user’s Social Security Number (<input type="text" name="SSN">, and no SSN attribute exists in eDirectory. You can use the ~ operator to have iChain store the user-entered value. For this example, the corresponding Form Fill tag would be:
<input type="text" name="SSN" value="~">
The ~ operator can be used with all supported form element types including text, password, checkbox, radio, and select. Using this operator is especially useful in situations where the username or password for an application differs from the eDirectory username and password, or when the required value for an element is not already stored in the directory, such as in the SSN example above.
~LDAP Attribute: A tilde followed by the name of an LDAP attribute instructs iChain to obtain the value for this field from the named LDAP attribute on the user object.
When the value for a particular form element is already stored in eDirectory, you can use this value type to obtain the information and use it for the value of that element. For example, if a login form requests the user’s email address (<input type="text" name="EmailAddress">), and every user’s email address is stored in the Internet Email Address attribute in eDirectory, then the administrator can use "~mail" as the value for that input field as follows:
<input type="text" name="EmailAddress" value="~mail">
This causes iChain to do an LDAP query for the mail attribute on the user object, then use the resulting value for the EmailAddress form element.
The tilde operator requires the LDAP name for the attribute. In eDirectory, the attribute must be mapped to the LDAP attribute. In this example, the mail attribute of LDAP is mapped to the Internet Email Address attribute of eDirectory. To view or change your current LDAP attribute mappings, see the LDAP Group object for your LDAP server.
~password: A tilde followed by the word “password” instructs iChain to use the password the user supplied to authenticate to iChain as the value for this field.
When iChain encounters this in a Form Fill policy, it uses the user’s iChain password as the value for this field. The user’s password is not pulled from eDirectory, and no LDAP traffic is generated. For example:
<input type="password" name="password" value="~password">
NOTE:If you are using mutual authentication (certificate based), iChain does not have a password for the user, so this method might not work as expected.
If the user's password contains a double quote character ("), the form fill fails. Other special characters are allowed in the password. You'll need to instruct your users not to use the double quote character in their passwords.
The tilde operator is one method of adding values to fields. If you want to supply hard-coded values for fields in the form, you can use the <injectStaticValue> tag to do so. See Section 14.4.2, Injecting Static Values.
If you want the form to be submitted automatically, you need to use one or more of the following post tags. The <actions> tag only requires the post tags when filling a form. Other actions such as <redirect> and <deleteRemembered> do not require them.
If you are not using SSL, you can increase your data security during a Form Fill operation by using the <maskedPost/> tag in the policy. When the actual posting of the data is done by the browser, a regular <post/> tag transmits the values for these fields across the wire from iChain to the browser. The data is then transmitted from the browser back to iChain as part of the POST request. This can be a security risk, especially if you are not using SSL for your site.
To use this feature, simply replace the <post/> tag with <maskedPost/> in the policy. A Form Fill policy should not have both of these tags in the same <urlPolicy> section.
NOTE:If your users can see the form on the browser (for example, during the first usage, or if there is an error), iChain displays the actual data without masked values.
For more information about the methods of submitting forms, see Section 14.4.3, Submitting Form Data to the Server.
You can choose one of three ways to store Form Fill data:
In iChain, the ichainFormFillCrib is the default attribute that stores the user-entered data. For more secure storage of credentials, use Novell® SecretStore®. If you use SecretStore, you need to first install it. For instructions on installing SecretStore, see Section 14.6.1, Installing SecretStore.
The ichainFormFillCrib attribute is a user attribute in eDirectory that stores Form Fill credential information for the user in an encrypted format. It is created only when the Form Fill policy is configured to save the values associated with one of the login page's input fields. For example, if the Form Fill policy is configured with a <input type="text" name="userID" value="~"> statement, it saves the value of the userID field in the ichainFormFillCrib attribute for that user.
This attribute is created only when the following occurs:
iChain is not using Novell Shared Secret (NSSO).
The value type is defined as ~ with no attributes.
If you use this storage method, no other applications can access and use the data.
The default setting is to use the ichainFormFillCrib attribute. It works with both LDAP and Secure LDAP.
To register user credentials for Form Fill and other applications, you can use the Form Fill Shared Secrets feature as long as the other applications also use Shared Secrets.
Some Web service applications use single sign-on or share application information. For some applications, you might want to preconfigure user credentials so your users never see them. Some Novell products, including Novell exteNd™ Director™, Novell SecureLogin, and iChain Form Fill need to share login credentials (usename and password).
You need to use the SecretStore interface to set the naming convention for your secret name for iChain. To function properly, the iChain naming convention must match the naming convention of the other applications. For example, the naming convention for Novell exteNd Director is //novell.com/nps/servlet. When you change this information in one application, such as Novell Secure Login, the change appears in all the other applications.
Novell SecretStore lets you overwrite credentials, but not read or retrieve the users' credentials.
IMPORTANT:Before you use Shared Secrets, you must install SecretStore version 3.x on the iChain Authorization Server. For installation instructions, see Installing SecretStore On NetWare or Installing SecretStore on Windows.
If you are using SecretStore, use the following tags to specify how the data is stored.
When doing form fill, you need to account for login failure behaviors. For example, you might be storing credential data for a user whose password was changed on the back-end server. When such a user authenticates through iChain, their old credential data is still used. Or you might be passing the user’s iChain password to a back-end server, but the user’s eDirectory password was changed recently. In this case, the user’s password on the back-end server might not match the iChain password any longer. When login fails, the user is presented with an error page, redirected back to the login page, or some other behavior. If this is not accounted for with a login failure policy, the login process appears to hang or loop, never taking the user to the desired application or giving any other indication of a problem with the login.
To prevent this from happening, you should create a login failure policy. The Login Failure policy can be designed to recognize the URL of an error page or can utilize <formCriteria> or <cgiCriteria> to differentiate when the error page is displayed on the same URL as the login page. You can use any of the tags in Header to identity the page the user receives on login failure.
The following Form Fill tags, which are subcomponents of the <actions> element, are useful in designing a Login Failure policy:
If a Login Failure policy references the same URL as a Login policy, the Login Failure policy should appear first in the Form Fill policy. iChain Form Fill processing is from the top of the policy down, and the first matching policy is used.
For a sample Login Failure policy, see the iChainTestFailure policy in Section 14.2.2, Sample Form Fill Policy.
This sample policy can be used for the form displayed in Figure 14-1. The actions section follows the order of the fields in the form and uses the names and types defined in the HTML source.
This policy is designed so the user must enter the data once, but after the data has been entered, iChain stores the data and automatically logs the user in. If the data on the back-end server has changed and the stored data needs to be updated, the second <urlPolicy> element defines a Login Failure policy that deletes the stored data and allows the user to fill in the form again.
<urlPolicy>
<name>iChainTest</name>
<url>iChainTestserver.com/FullTest.html</url>
<injectStaticValue>
city=Provo
</injectStaticValue>
<sharedSecret>
</sharedSecret>
<formCriteria>iChain Form Test Page</formCriteria>
<actions>
<fill>
<input name="username" value="~" ff_lower_upper="upper">
<input name="password" value="~">
<select name="webserv" type="listbox" value="~">
<input name="role" type="radio" value="~">
<input name="mail" type="checkbox" value="~">
<input name="payroll" type="checkbox" value="~">
<input name="selfservice" type="checkbox" value="~">
</fill>
<post/>
</actions>
</urlPolicy>
<name>iChainTestFailure</name>
<url>iChainTestserver.com/FullTestFailure.html</url>
<actions>
<deleteRemembered>iChainTest</deleteRemembered>
<redirect>iChainTestserver.com/FullTest.html</redirect>
</actions>
</urlPolicy>