Simple Policy
This section discusses the format and functionality of the iChain Form Fill Policy file, which controls which forms are identified and filled. The Form Fill file contains any number of URL policies encoded in XML. The iChain proxy user (specified in the Access Control page on the Web GUI) must have capability to add and modify attributes on all user objects in order for Form Fill to work.
The following is an example of what a simple policy looks like:
Figure 19
Simple Policy
The bounds of a policy are delimited by the start tag <urlPolicy> and the end tag </urlPolicy>. This sample has a <name> of Test, which can be anything the user chooses, as long as it is unique within the policy file. The <name> is optional, except in a few cases, which will be discussed later in this section. The policy's <url> value of www.test.com/login.htm matches an exact page so that whenever this URL is requested by a browser, it will match this policy.
NOTE: If you cut and paste from the browser, remember to remove the scheme portion of the URL. For example, using http://www.test.com/login.htm wouldn't match. In this case, you would use only www.test.com/login.htm. Also, you cannot use a space in the rule name.
When a policy matches on a given page, certain actions are performed. These actions are specified by the <actions> tag. The example above designates two actions: <fill> and <post>.
The <fill> action identifies the page as a form that needs to be filled, and the <input> tags that follow describe the fields in the form that have values to insert. The first <input> tag has a name of userid and a value of ~dn, which instructs the policy to find the <input> tag in the form that has the name of userid and insert the user's dn (LDAP distinguished name) as the value of the field. The "~" in ~dn is a flag to the parser that this input field has a value that needs to be filled in.
Note that the name that follows the ~ is the name of the attribute in LDAP, not in eDirectory.
The second <input> tag is a special case because password is not an LDAP attribute. It instructs iChain to use the same password that the user gave when he or she logged in to iChain.
Since it is possible to have more than one <input> field in a form by the same name (or <input> fields without a name, the <input> tags given in the <fill> action are order-dependent. They must be specified in the order they will be seen in the form. Only those <input> fields that need to be filled in need to be specified.
The second action, <post/>, instructs iChain to process the form and to send it back to the browser. the browser then submits/posts the form automatically without the user's confirmation. This logs the user in automatically and gives the illusion of single sign-on. Care should be taken when using this action so that all login failures are handled properly. Handling failures is explained later in this section.
The following is an example of what a more complex policy looks like:
Figure 20
Complex Policy
In the above example, the <url> value, www.test.com/abc/*, does not match a single URL, but rather all URLs below abc in the tree. There are some Web applications that don't have a specific login page; they simply return a login form from any of their URLs anytime they determine the user is not logged in.
In this case, there is no specific URL to match; any one of a set of URLs may be (or may not be) a login form. The only way to know is to look in the HTML being returned.
The action field of the <form> tag in the login form should use a relative URL.
When deciding on a policy, iChain first matches the URL of the page with the <url> value or pattern. If that matches, iChain then searches for whatever is placed between the form criteria on and off tags. If more than one line of text is given as criteria, iChain searches for each line individually. Criteria must match exactly, so it is a good idea to cut and paste a line directly from the login form. It should also be unique to the form, and as small as possible, because the larger the criteria, the more time-consuming the searches will be.
NOTE: By defining <formCriteria>, performance may be increased, as it specifically looks for the string that you specified rather than parsing every packet that matches the URL. Not defining <formCriteria> may cause Form Fill to not work properly with certain applications when the <url> that you specified is not specific enough. It is recommended that you define both the <url> and <formCriteria> tags as specifically as possible.
Figure 20 shows some new uses of <input> tags.
Notice the values of "~". This instructs iChain to remember this value the first time the user enters it and to supply it automatically thereafter. The last <input> tag refers to a check box. Since check boxes and radio buttons behave differently than ordinary input fields, their types must be explicitly specified.
This policy also specifies the <post/> action so each user will be prompted once for a user ID, password, and with a check box titled useJava. Once the user has supplied these values, the values will be remembered and single sign-on will be simulated from then on (or until the login fails).
Currently a Java class (usually a servlet) in the Web server generates some login and logout forms that only have a difference in the CGI parameter-value pair(s).
For example, a login is:
webaccess.provo.novell.com/servlet/webacc?action=User.Login&.....
and a logout is:
webaccess.provo.novell.com/servlet/webacc?action=User.Logout&.....
In order to distinguish between the login and the logout, the Form Fill Policy includes a <cgiCriteria> tag beside the <url>. The lines between the tags will be used for the string comparison (case-sensitive).
Figure 21
<cgiCriteria> Tag
The <cgiCriteria> tag is a complementing tag for <url>. A policy should have <url>, but <cgiCriteria> is an additional option for <url>. When the URL is matched, Form Fill will try to match the <cgiCriteria> tag if there is one. Users can put <cgiCriteria> before <url> but it is recommended that the <cgiCriteria> tag follow the <url> tag.
Because Form Fill uses a sequential search to match a policy, the most specific policy should always be placed before the generic one. For example, the URL of login and logout forms are the same, but the specific one includes the <cgiCriteria> tag (the generic one does not). Otherwise, the specific one will never be triggered (see Figure 22 and Figure 23).
Figure 22
Specific Example
Figure 23
Generic Example
If a single login page contains multiple forms (having many pairs of <form> and </form> tags), you can use the <formnum> tag to specify which form instance to fill. Usually there is only one form in a login page.
To use the <formnum> tag, enter <formnum>N</formnum>, where N is the form number of the form to be filled. The first form is number 1, the second is number 2, and so on.
For example, your <formnum> tag might look like the following:
<urlPolicy>
<name>test</name>
<url>www.novell.com/signon_welcome.screen</url>
<formnum>2</formnum>
<formCriteria>
..................
</formCriteria>
...................
Form Fill supports the list box. The syntax for list box in the policy is:
<select name="list box name" type="listbox" value="~"
The tag name is "select". The type must be "listbox" and value must be "~".
Form Fill only supports a single selection list box.
For example:
<select name="MyChoice">
<option>Apple<option selected>Banana<option>Pear</select>
is a portion of the origin server's login page.
The corresponding Form Fill Policy should be:
<select name="MyChoice" type="listbox" value="~">
The following is an example of a simple login failure policy:
Figure 24
Simple Login Failure Policy
The <redirect> action takes a URL that instructs iChain where to redirect the user's browser. Usually this is the original login page where the user will have the chance to try logging in again.
Most applications will present a logout or exit link to allow the user to exit the application. In most cases, an HTML page is returned, indicating the session status and also offering the user the chance to log in again via a link to the original login page. In some rare cases, a page is sent back, redirecting the user's browser to retrieve the original login page. Both scenarios would cause confusion to the user when automatic Form Fill is enabled. A false sense of security is implied in the first case: anybody who takes over the workstation can hit the re-login button and log in (automatically done by Form Fill) as the previous user because the browser session is still valid.
The second case would create the impression that the user will be re-logged in (automatically done by Form Fill) again when the logout/exit button is selected.
A logout mechanism resolves the above issues. A Form Fill policy needs to be configured to intercept the logout/exit page and redirect the user to a customized page which allows him or her to log out of iChain.
The following is an example of a policy with a logout mechanism in place:
Figure 25
Policy without Logout Mechanism
The page (ilogout.htm) and its associated image files that the logout/exit action is redirected to should be deposited in the SYS:\ETC\PROXY\DATA directory on the iChain proxy server. Remember to use the IP address of the iChain proxy server to complete the path to the page.
A sample page for the above policy might look like the following:
Figure 26
Sample Page
The key to the actual iChain Proxy Server logout action lies on the reference link associated with the logout button: http://accelar.provo.novell.com/cmd/BM-Logout, replacing the URL with the proper domain name associated with the link (accelar.provo.novell.com in this case).
The following sections are enhancements specific to the iChain 2.2 release:
In addition to the POST method for submitting user credentials, Form Fill now supports the GET method. Users can use the GET command to send the form to iChain instead of the POST command.
Form Fill reduces the possibilities of exposing sensitive data during the auto posting by adding the tag <maskedPost/>. Form Fill replaces text fields (for example, user name, password, etc.) with some fixed values and sends them to the browser. When Form Fill receives the data by auto posting from the browser, it replaces back the user's credentials and then forwards them to the Web application. To use this feature, you need to change the <post/> tag to <maskedPost/> in the rule. If users use SSL between iChain and the browser, they do not need to enable this feature because the data is already secured by SSL.
NOTE: If users can see the form on the browser (for example, during the first usage, or if there is an error), the users will see the real data (without fixed masked values).
More and more customers need a way to inject static values to the data of a POST packet or to the URL of a GET packet. Moreover, injecting static values may also be a way to work around some JavaScript issues in the auto-post mode (for example, the image.x and image.y values which currently are provided by the customer rewriter).
You can add a new <InjectStaticValue> tag in the policy rule. The portion of the policy rule would look like:
<formCriteria>
</formCriteria>
<injectStaticValue>
A=b&C=def&city=Provo
</injectStaticValue>
OR
<formCriteria>
</formCriteria>
<injectStaticValue>
A=b
&C=def
&city=Provo
</injectStaticValue>
If the original post data (for the POST method) is my_name=john&password=doe&city=Boston, the final data should be: my_name=john&password=doe&city=Provo&A=b&C=def
If the original URL (for the GET) method is
/mypage.html?my_name=john&password=doe&city=Boston, the final URL should be: /mypage.html?my_name=john&password=doe city=Provo&A=b&c=def.
NOTE: The following should be taken into consideration: When there are duplicated fields, the injection fields should take precedence (the static fields will replace the data submitted by the user and keep the original sequence). Also, the values will be appended at the end.
This feature may be used to work around some JavaScript issues in the auto-post mode (for example, the image.x and image.y values).
Using JavaScript inside HTML is a popular method of login form since java makes the login form dynamic; however, Form Fill may not work for some cases. If this is the case, Form Fill may need its own solution for using JavaScript.
Form Fill currently has two categories. One is interactive (without <post/> or <maskedPost/> in the policy. (We will consider <maskedPost/> as <post/> to explain this feature.) The other is a silent (auto-post) mode. For the silent (with <post/> in the policy) mode, only the fields of the form are kept (all Java scripts are removed), and added to the end is "document.form[0].submit()" to automatically submit user credentials (not the form itself). In the interactive mode Form Fill fills the values for the fields which are specified in the policy.
NOTE: A policy with <post/> tag can become interactive mode when users need to input the credentials (on the first time or if a login fails).
This feature enables the auto-post mode. If the login form does not work in interactive mode, this feature will not resolve that issue.
Consider the following in your use of the JavaScript: Form Fill should not strip the JavaScript. Form Fill also needs to resolve the onsubmit function for the "document.form[0].submit()" which will never trigger the onsubmit event. For example, if in the login form there is a form tag:
<form onsubmit="do_function()" method="post" >
then the do_function() will never be executed. For information about this issue, see the JavaScript in forms site.
Form Fill provides two tags, <javaScript> and <scriptForPost> in the policy to solve the problems.
NOTE: These two tags will be ignored (that is, they will not function) in interactive mode.
If there is nothing between starting and ending tags, Form Fill will keep all Java scripts. Otherwise, Form Fill will keep them selectively. See the following examples:
Example 1: Keeping all Java scripts:
<javaScript>
</javaScript>
Example 2: Keeping Java scripts only for functions of abc and def:
<javaScript>
function abc()
function def()
</javaScript>
If there is nothing between the starting and ending tags, Form Fill will copy the onsubmit function. Otherwise, it copies whatever (should be statements of JavaScript) and puts it before document.forms[0].submit(). See the following examples:
Example 1: Copying the onsubmit function:
<scriptForPost>
</scriptForPost>
In this example, the portion of the login form (on the browser side) will be:
<script language="javaScript">
<!-
do_function();
document.forms[0].submit();
//-->
</script>
Example 2: Copying customized scripts (ignoring the onsubmit function):
<scriptForPost>
var d = new Date();
document.login.timezone.value =
d.getTimezoneOffset();
</scriptForPost>
In this example, the portion of the login form (on the browser side) will be:
<script language="javaScript">
<!-
var d = new Date();
document.login.timezone.value =
d.getTimezoneOffset();
document.forms[0].submit();
//-->
</script>
The LDAP value of a user's attribute (for example, cn) can be mixed case (for example, jack, JACK, or Jack). Some Web applications require all upper or lower case. Because it is difficult for users to change the Web application, Form Fill provides the ff_lower_upper option for input fields (see example after this paragraph). If this option is missing or the field value is neither upper or lower case, Form Fill will not perform a conversion (it will maintain the value's original case).
<input name="UserName" value="~cn" ff_lower_upper="lower">
OR
<input name="UserName" value="~cn" ff_lower_upper="upper">
Because there are many character sets used in HTML form for log in, Form Fill only supports ISO-8859-1 and UTF-8. The ISO-8859-1 is mainly for single-byte characters, and UTF-8 is for double-byte characters.
NOTE: The ASCII character codes in UTF-8 are the same as in ISO-8859-1.
The HEAD element in the HTML form should be similar to the following two examples:
Example 1: ISO-8859 character set (charset):
<head>
<title>Untitled for ASCII</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
Example 2: UTF-8 character set (charset):
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html;CHARSET=utf-8">
<TITLE>Untitled for UTF-8</TITLE>
</HEAD>
When using charsets other than those in the above examples (for example, shift_jis, ISO-2022-jp, etc.) with Form Fill, you need to do the following tasks in order for Form Fill to work properly:
Verify that the back-end Web application (which handles the login credential) supports the UTF-8 format. Otherwise, Form Fill will not work properly. (Do not set the Form Fill policy and skip Step 2).
Change the charset to UTF-8 and save the form in the UTF-8 format.
NOTE: If the content of the title is in Japanese, it should be added after the META declaration. (See Example Two above.)
User-entered data in form fields will be stored in the user object's ichainFormFillCrib attribute by default. To make the storage of these credentials more secure, you can use Novell SecretStoreTM.
SecretStore is a service in eDirectory that allows applications to store sensitive data securely. This service guarantees protection for integrity and confidentiality of application data in storage and during transmission between client and SecretStore.
In order to use SecretStore, you must upgrade to NICI version 2.4, install SecretStore, then enable SecretStore. (These procedures are explained in the following sections.)
NOTE: Verify that all the LDAP servers listed in the Access Control tab have SecretStore installed on them or Form Fill will not work properly.
Insert the iChain Authorization Server CD.
Run NICI/WCNICIU0.EXE.
Follow the screen prompts to complete the install.
Run SSO/NT.SETUP.EXE.
During the SecretStore install, you will need to log in to your tree as Administrator in order for the schema to be modified.
Start the NDS Services Console.
Configure each of the following services to start up automatically:
Continue with Enabling SecretStore.
Insert the iChain Authorization Server CD into the CD drive on the server.
From a remote console prompt, enter CDROM to mount the iChain Authorization Server CD.
The server mounts the CD as ICHAIN_AUTH_SR.
To upgrade NICI, enter NWCONFIG.
To install SecretStore, enter NWCONFIG. Choose Product Options, Install a Product Not Listed.
Press Esc and then F3, then enter the path to the SecretStore installation:
ICHAIN_AUTH_SR:/SSO/NETWARE.
Press enter to complete the SecretStore installation.
Run \SSO\UTILS\SSINIT.EXE from the Novell iChain Authorization Server CD, using the NetWare server as the default server. (This is done from the client.)
Continue with Enabling SecretStore.
After SecretStore has been installed, you must enable it to work with Form Fill as explained in the following procedure.
Log on to the LDAP server.
Export your trusted root for the LDAP server.
View the properties of the ISO object.
From ConsoleOne, select the Form Fill Policy tab > mark Use Novell Secret Store for Form Fill > click OK.
From the iChain Proxy Services Admin GUI, import the trusted root.
Select Configure (this icon is in the bottom left corner) > select the Access Control tab > mark Enable Secure Access to LDAP Server.
Select Import Trusted Root and enter a name for the imported file.
The file name must adhere to 8.3 naming conventions.
Using a text editor, open the file that was exported from the LDAP server to a local drive > copy all the contents of the file to the text field in the Trusted Root dialog > click OK.
Mark Enable Form Fill Authentication and click Apply.
NOTE: If you already had Form Fill enabled, you need to refresh Form Fill from the Access Control tab.
More Web service applications are using single sign-on or are sharing some application information. Administrators might want to preconfigure user credentials so the user never sees what his/her credentials are for various applications. Novell products including Novell Portal Services, Novell Secure Login, and iChain Form Fill might share login credentials (user name and password).
The Form Fill Shared Secrets feature can be used to register user credentials for Form Fill and other applications using Shared Secrets. Using Shared Secrets, the administrator can only overwrite credentials and cannot read or retrieve the users' credentials.
IMPORTANT: In order to use Shared Secrets, the administrator must install the SecretStore version 3.x on the iChain Authorization Server.
The following are important things to know about Shared Secrets:
Shared Secrets uses a secret ID as a key/index to retrieve information. The format is <type>:<name>. There are only two types; either "SS_App" (for application) or "SS_CredSet" (for login). Currently, Form Fill and OLAC only support "SS_CredSet" type. The <name> is the rule name in the Form Fill Policy. The Shared Secret data is made up of "<name><delimiter><value>" pairs in which the name and value are the same as in the <fill> section of the Form Fill Policy.
Form Fill uses the following tags for Shared Secrets. Form Fill adds the following tags for sharing users' credentials with other applications:
<sharedSecret> and </sharedSecret> tags
Inside these tags there is a sub-tag, <migration/>. This tag means the original credentials will be migrated to Shared Secrets. The original credentials are stored in Novell eDirectory or in Novell SecretStore, which is defined by the "Use Novell SecretStore for Form Fill" check box in the Form Fill Policy tab (under the ISO object).
The following are two examples for using these tags:
<url>www.novell.com/formfill/test/*</url>
.
<sharedSecret>
</sharedSecret>
<actions>
<sharedSecret>
<migration/>
</sharedSecret>
NOTE: After migration, the original credential is transferred to Shared Secrets and is removed from the old storage (eDirectory or SecretStore).
Form Fill only supports two scenarios of Shared Secrets. The following two scenarios are supported:
If the <sharedSecret> tag is used, Form Fill will use Shared Secrets. If there is no <sharedSecret> tag, it will read the Use Novell SecretStore for Form Fill check box in the Form Fill Policy tag (under the ISO object) to make a decision whether to use the old SecretStore (when the check box is checked) or eDirectory (when the check box is unchecked). Subsequently, currently there are two combinations: "Old SecretStore/Shared Secrets" or "eDirectory/Shared Secrets." In addition, the two former scenarios are still supported:
New reserved field name in the policy rule for Shared Secrets: There is a new reserved field name, ff_shared_name, in the policy rule for Shared Secrets. Some Shared Secrets applications may use a common name to store the value. This field name is applied to input and select tags in the <fill> section of a policy rule.
The policy rule, for example, could be:
<input name="User.id" value="~">,but in the Shared Secrets, the field name is not User.id, but rather, is Username.
In this case the policy rule should be:<input name="User.id" value="~" ff_shared_name="Username">.
NOTE: The value of ff_shared_name is meaningful for reading/writing to and/or from Shared Secrets. It has nothing to do with the HTML form, itself. For example, the name in name=value pair of the POST packet is still User.id, not Username, but the name in the name=value pair in Shared Secrets is Username, not User.id. If ff_shared_name is missing, Form Fill will use the value of name (User.id) as a default value for it.
The following are Form Fill tips when using Shared Secrets:
NOTE: For information on how an administrator registers all users' credentials, contact a Novell consultant.
Form Fill can share a user's credentials with OLAC. For information on how to set up this configuration, see OLAC Supports Shared Secrets.
The following are known limitations of using Form Fill with Shared Secrets:
Using Form Fill, you can add a <secretName> tag inside the <sharedSecret> to make <name> field more logical and transparent to the secretID. If there is no <secretName>, the default secret name is taken from the <name> field.
Some applications use the secret name, which is a portion of secretID (shared among Web applications), and contain a question mark (?) character. This character causes Form Fill to act abnormally if it is found inside of the <name> field.
For example:
Example 1:
<name>FormFillSharedWithNSL</name>
<url>www.novell.com/formfill/test/*</url>
<sharedSecret>
<secretName>https\://novell.com/nps/servlet/
webacc?task\=abc&merge\=def</secretName>
</sharedSecret>
<actions>
NOTE: If in the <secretName> field there is a colon (:), equal sign (=), and/or a backslash (\) character (which are reserved for the secretID), they must be preceded with a backslash (\) character.
Example 2:
<name>FormFillOwnSharedRule</name>
<url>www.novell.com/formfill/test/*</url>
<sharedSecret>
</sharedSecret>
<actions>
In Example 2 above, since there is no <secretName>, the secret name will be same as <name> field (for example, FormFillOwnSharedRule). It is same if there is a line of:
<secretName> FormFillOwnSharedRule</secretName>