Share via

Customizing HTML forms

  • Article

Applies To: Forefront Threat Management Gateway (TMG)

Forefront TMG provides a variety of authentication methods that you can apply to Web publishing rules for clients accessing published Web servers. When forms-based authentication is selected, users are directed to an HTML form to provide authentication credentials. Forefront TMG provides default form sets used for forms-based authentication. You can customize these form sets to provide a different look for the logon forms for different published Web sites.

This topic provides an overview of Forefront TMG form sets, and describes how to customize them.

Overview of HTML forms

The following sections describe the HTML form sets that are included with Forefront TMG, and the structure of the Forefront TMG form set directories:

  • Forefront TMG Form Sets

  • Form Set Directories

Forefront TMG Form Sets

Forefront TMG includes preconfigured form sets that reside in the following folders:

  • ISA—Includes all the HTML forms that may be required for forms-based authentication, as specified in the Web listener or Forefront TMG Web publishing rule.

  • Exchange—Includes all the HTML forms that may be required for Microsoft Exchange Web client access forms-based authentication.

Forefront TMG supports three classes of HTML forms, organized into form sets:

  • HTML—Intended for standard browsers.

  • cHTML—Intended for browsers that support cHTML, such as i-mode mobile devices.

  • xHTML—Intended for browsers that support xhtml-mp, such as Microsoft Windows Mobile® and other mobile devices.

Note

Forefront TMG determines the type of form to provide, based on the User-Agent header provided by the mobile client.

Each form set includes all the HTML forms that clients may need for forms-based authentication, such as a logon form, logoff form, and SecurID forms. By default, when you create a new Web listener with HTML forms-based authentication as the selected authentication method, a form set is selected automatically. Depending on the authentication validation method specified for the Web listener, Forefront TMG presents one of the following types of logon forms:

  • Password form—The user enters a user name and password on the form. These credentials are required for Active Directory, Lightweight Directory Access Protocol (LDAP), and Remote Authentication Dial-In User Service (RADIUS) credential validation.

  • Passcode form—The user enters a user name and passcode on the form. These credentials are required for SecurID and RADIUS one-time password validation.

  • Passcode/Password form—The user enters a user name and passcode, and a user name and password. The user name and passcode are used for authentication to Forefront TMG using SecurID or RADIUS one-time password authentication methods, and the user name and password are used for delegation. This form is used when the administrator chooses to collect additional credentials in the form.

After creating the Web listener and the Web publishing rule, you can specify that a different form set should be used. In addition, the HTML form properties of a Web publishing rule can override the form set of its Web listener. A form set is determined either by the:

  • Form set specified in the Web listener.

  • Form set specified in the Web publishing rule.

For information on how to create form sets, see Creating Custom Form Sets.

Form Set Directories

The \%Forefront TMG Installation Directory%\Templates\CookieAuthTemplates directory contains the ISA and Exchange forms directories that are included with Forefront TMG. The immediate subdirectories of these directories contain the various form set directories.

Each form set directory includes the entire set of HTML forms (.htm files). When Forefront TMG displays an HTML form, it replaces placeholders in the .htm files with the strings in the strings.txt file corresponding to the language settings of the user's browser, located in the language folder of the languages (nls) directory, as follows.

ISA directory

When a Web publishing or a Microsoft SharePoint publishing rule is created, a form set from the ISA directory is automatically used.

Exchange directory

When a Web client mail access publishing rule is created using the New Exchange Publishing Rule Wizard, the Exchange HTML form set is automatically selected for that rule. The Exchange folder contains only the HTML form set. To use either the cHTML or XHTML form sets for Exchange Web client access, you must create the directories Exchange\cHTML or Exchange\xHTML, and then copy the contents of Exchange\HTML to these directories.

Note

To use the Exchange Publishing Rule Wizard, in the console tree of Server Management, click Firewall Policy, then on the Tasks tab, click Publish Exchange Web Client Access.

Language directory

The language directory, nls, includes a single subdirectory with a strings.txt file for each supported language. When Forefront TMG displays an HTML form, it replaces the placeholders in the .htm files with the strings in the strings.txt file of the language matching the Accept-Language header sent by the client's browser.

When Forefront TMG cannot match the Accept-Language header sent by the client's browser, Forefront TMG uses the strings.txt file in the default form set directory. Note that strings.txt is the English language version of the file.

Form set directory permissions

When Forefront TMG is installed, the permissions on the forms directories are automatically set. These permissions should never be changed:

  • Full control—Applied to members of the local Administrators group.

  • Read only—Applied to the Network Service account so that Forefront TMG can read the content of this directory while running under the Network Service account.

To preserve the inheritance of permissions from the parent folder, it is recommended that you copy files to the form set directory, rather than move them to the directory.

Customizing Form Sets

In some cases, you may want to provide a different look for the forms of some published Web sites. Each such look is defined by a form set. You can either modify an existing form set, or create your own custom form set.

The following sections describe:

  • Customizing Text Strings

  • Using Custom Graphics

  • Creating Custom Form Sets

Note

  • When customizing the forms, you must keep all of the original form fields, and all of the placeholders that Forefront TMG replaces with hidden fields. All input tags <input …> and form tags <form…> must remain unchanged in the .htm files, or the forms will not work. Also, you cannot change the format of the strings.txt file.

  • The Exchange and ISA folders are overwritten during upgrade. If you customize the HTML forms, be sure to make a backup of the updated files before you apply any hotfix, service pack, or upgrade.

  • If you are running Forefront TMG Enterprise Edition, you should make any changes to the Forefront TMG form sets on each Forefront TMG array member.

  • For the changes to take effect, you must restart the Firewall service.

  • All the files found in the forms customization directory can be accessed by anonymous users; therefore, they should not contain any sensitive information.

Customizing Text Strings

When Forefront TMG displays an HTML form, it replaces the placeholders in the .htm files with the strings in the strings.txt file of the language specified in the language settings of the client's browser, or as specified in the Web listener. Text string customization is done by modifying the strings in the strings.txt file that correspond to the placeholders in the .htm files.

Note

  • Before customizing the content of the strings.txt file, it is recommended that you make a backup of the strings.txt file that you are modifying.

  • You must properly encode any strings that you modify or add, to comply with HTML syntax. The < character cannot be included in the string, and should be replaced with &lt;. In addition, to include a quotation mark, you must use the single quotation mark instead of the double quotation mark.

The following example describes how to change the text string for the user name input in the standard logon page from "Domain\user name:" to "Alias:".

To change the text for the user name input in the standard logon page

  1. Open the strings.txt file in the appropriate language folder in the nls directory.

  2. Find the string matching the placeholder @@L_username_ text. The string appears in the strings.txt file as: L_UserName_Text="Domain\User name:".

  3. Change the text string to L_UserName_Text="Alias:".

  4. Save the strings.txt file. When the HTML form is generated, the new value of @@L_username_text will be displayed in the form.

  5. Restart the Microsoft Firewall service for the changes to take effect.

In addition to modifying text strings, you can add new strings to a form. The following example shows how to add a string to a form.

To add a string to a form

  1. Open the .htm file.

  2. Add a placeholder for the string and save the file. The placeholder must be in the format of @@L_stringname. The placeholder cannot contain spaces.

  3. Save the .htm file.

  4. Add the corresponding string to the strings.txt file. The string must be written in the format L_stringname="string text".

  5. Save the strings.txt file.

  6. Restart the Firewall service for the changes to take effect. When the HTML form is generated, the value of @@L_stringname will be displayed in the form.

Security Considerations

If you provide the strings.txt file to a third party for modification, validate that non-text additions have not been made to the file, because these may provide a means of attack on your networks.

Using Custom Graphics

You can either replace a graphic in a specific form or replace a graphic globally in all the forms, so that the change appears in all .htm files that refer to that graphic.

The graphics that Forefront TMG uses in the HTML forms are all located in the default forms directories (ISA and Exchange). The URL used to reference graphics is written as follows, where <filename> is the name of the file including the extension: /cookieauth.dll?GetPic?formdir=@@FORMDIR&image=<filename>.

The following example describes how to replace the logo graphic <lgntop.gif> with your own company logo <logo.gif>; the example describes how to modify a form in the HTML directory.

To replace the logo graphic

  1. Copy logo.gif to the \%Forefront TMG Installation Directory%\Templates\CookieAuthTemplates\ISA\HTML form set directory.

  2. Open the .htm file that includes the graphic you are replacing.

  3. Modify the URL for the graphic, replacing the existing file name <lgntop.gif>. The modified URL is: /cookieauth.dll?GetPic?formdir=@@FORMDIR&image=logo.gif.

  4. Save the file.

  5. Restart the Firewall service for changes to take effect. When the form is generated, logo.gif will display in the form.

Alternately, to replace a graphic globally in all the forms, copy your graphic to the forms directory using the file name of the graphic you are replacing.

Creating Custom Form Sets

You can provide custom forms to specify a different directory for forms other than the default ISA or Exchange directories that are provided by Forefront TMG. For example, consider a scenario in which you are publishing Web client access for two different companies and would like each company to have their own logo in the page, as well as other custom text strings.

The following procedure describes how to provide custom forms for this example.

To provide custom forms

  1. Create a new folder in the \CookieAuthTemplates\ directory; for example, \%Forefront TMG Installation Directory%\Templates\CookieAuthTemplates\Company1.

  2. Copy the contents of the ISA or Exchange folders into the new folder that you created. If you only have standard browsers, you only need to copy the HTML folder.

  3. Customize the form in the copied directory. Make any text changes to the strings.txt file in the appropriate language folder, or replace any graphics files. Do not change any of the HTML form elements, such as <FORM> and <INPUT>.

  4. Restart the Firewall service for the changes to take effect.

  5. To apply the new form set to a Web listener, provide the directory name on the Forms tab of the Web listener. Provide only the name of the directory, such as Company1, and not its full path. Alternately, to apply the new form set to a Web publishing rule, in the Application Settings tab of the rule, enable the Use customized HTML forms check box, and provide the directory name.

  6. To ensure that the forms are displayed only in a specific language, in the Forms tab of the Web listener, under Display the HTML form in this language, select the language. For example, to ensure that a form is displayed in English only, regardless of the client browser setting, select English [en].

  7. Repeat the procedure for the second company (Company2).

  8. Click Apply in the Apply Changes bar to update the configuration.

Note

If you are running Forefront TMG Enterprise Edition, the forms directory must appear on all Forefront TMG array members.

Language Settings

By default, Forefront TMG builds the HTML forms using the strings.txt file from the language folder specified in the Languages option of Internet options of the client's browser. You can override the client language setting by specifying a language in the Web listener. In addition, if Forefront TMG does not locate the strings.txt file corresponding to the language settings, it uses the default strings.txt file.

Note

The language of the strings.txt file in the default directory is English. You can change the language of the default strings.txt file by replacing it with the strings.txt file from any one of the language folders.