Fortinet black logo

Administration Guide

Customizing error and authentication pages (replacement messages)

Customizing error and authentication pages (replacement messages)

You can customize the following FortiWeb HTML pages:

  • Pages that FortiWeb presents to clients when it authenticates users.

    FortiWeb uses these pages when the client authentication method in a site publishing configuration is HTML Form Authentication. For details, see Site Publishing (Single sign-on).

  • The error page FortiWeb uses to respond to a HTTP request that violates a policy and the configured action is Alert & Deny or Period Block.
  • The error page FortiWeb uses to respond to a AJAX request that violates a policy and the configured action is Alert & Deny or Period Block.
  • The "Server Unavailable!" page that FortiWeb returns to the client when none of the server pool members are available either because their status is Disable or Maintenance or they have failed the configured health check.

FortiWeb uses each page for specific server policy.

Configuring an error or authentication page

Follow steps below to configure an error or authentication page:

  1. Go to System > Config > Replacement Message.
  2. Select Replacement Message.
  3. Select the message you want to edit in the list of messages or click Create New to create a new message.
    You can also select the predefined one to take it as a template, or select a message and click Clone to clone this message.
  4. You can enable Replacement Message for AJAX requests to respond to a AJAX request, and configure the AJAX block page message. You must enable it by going to System > Config > Feature Visibility first.
  5. If you have selected Attack block page and want to change the HTTP response code it displays, click Edit HTTP Response Code. Enter a new value for the code, and then click Apply. For details, see Attack block page HTTP response codes.
  6. In the bottom-right pane, edit the HTML code as required.
    The results of any changes you make are displayed immediately in the bottom-left pane.
  7. Click Save to save your changes or Restore Defaults to revert to the preset version of the page.
  8. Select the replacement message when you edit a policy.
  9. For details about using macros in the code, see Macros in custom error and authentication pages.

Pre-login disclaimer message

Go to System > Config > Replacement Message, and select Disclaimer tab. You can edit the disclaimer message. Click Save to save your changes or click Restore Defaults to revert to the preset version.

Attack block page HTTP response codes

You can specify the HTTP response code that the attack block message page displays. If the error status code allows an attacker to fingerprint a vulnerable application, you can customize it to display a more vague reply. (For all other pages, you cannot change the default response code.)

The following codes are examples of HTTP response codes:

  • 200—OK. Typically indicates success, and accompanies resource requested by the client.
  • 400—Bad Request. Typically indicates wrong syntax.
  • 403—Forbidden. Typically indicates inaccessible files.
  • 404—File Not Found. Typically indicates missing files.
  • 500—Internal Server Error. Typically indicates one of many possible conditions such as a servlet runtime error.
  • 501—Not Implemented. Typically indicates a non-existent function on the web application.

Macros in custom error and authentication pages

When it generates error and authentication messages, FortiWeb generates some of the message content using macros. It uses two type of macros: label macros and image macros.

Although you can add the predefined macros to your custom messages, you cannot create macros and you cannot modify the label macros. You can modify an image macro to reference a predefined image or one that you have uploaded.

Label macros

You can use the following label macros anywhere in the HTML code for Attack Block Page and Server Unavailable Message messages:

%%URL%%

Inserts one of the following URLs:

  • The URL of a web page blocked by either the web filtering or URL blocking feature.
  • The URL of a web page that contains a blocked file that a client has tried to download.
%%SOURCE_IP%% The source IP address of the client that attempted to access the web service.
%%DEST_IP%% The IP address of the web server.
%%VSERVER_IP%% The IP address of the virtual server.
%%EVENT_ID%% An ID number that identifies the attack type. Use this number to help you locate the log for the event in the FortiWeb attack log.

You can use the following label macros anywhere in the HTML code for the Site Publish Authentication messages:

All the macros and parameters in the HTML code can't be removed or edited except %%REPLY_TAG%% and %%DISPLAY_OR_HIDE%%. The text that shows in the Web GUI is allowed to be modified.

For example, in the following code, the macros (e.g. %%TOKEN_POST_URL%%) and parameters (e.g. sph_org_location) can't be removed or edited, but the Web GUI text "Authentication Required" can be replaced with any text as you desire.

<form action="%%TOKEN_POST_URL%%" method="post">

<input type="hidden" name="sph_org_location" value="%%ORG_LOCATION_VAL%%">

<h1 style="background:#eee center 25px ;">

Authentication Required

</h1>

%%ORG_LOCATION_VAL%% The original URL that the client tried to access.
%%REPLY_TAG%% The authentication server reply message. For an example of how you can customize the message by replacing this macro with JavaScript, see Customizing the message returned for LDAP errors (%%REPLY_TAG%% macro).

%%DISPLAY_OR_HIDE%%

Display or hide the checkbox "I want to change my password after logging in". It's by default displayed. For how to hide this checkbox, see Hiding the checkbox "I want to change my password after logging in".

%%LOGIN_POST_URL%% The login URL where users post their credentials.
%%TOKEN_POST_URL%% The login URL where users insert their token code.
%%RSA_LOGIN_POST_URL%% The login URL where users post their RSA SecurID credentials.
%%RSAC_POST_URL%% The login URL where users post their RSA SecurID credentials.
%%ACCOUNT%% The username credential of a user who exceeded the maximum number of login attempts.
%%PERIOD_TIME%% The length of time that FortiWeb prevents a user from attempting to log in again, after the user has exceeded the allowed number of login attempts. The site publishing policy specifies the value.

%%MSG_ID%%

The message ID number idenfities the attack log message ID, and can be used to map the event to the log in the FortiWeb attack log.

Image macros

Use the following format to add an image macro anywhere in a custom error or authentication message:

%%IMAGE:<image_name>%%

where <image_name> is the name of either a predefined image or one you have uploaded. To view or upload images, go to System > Config > Replacement Message, and then select Manage Images tab. For details, see Adding images in error or authentication pages.

For example, in the default Attack Block Page message, the macro %%IMAGE%%:logo_v2_fnet%% adds the predefined image logo_v2_fnet. If you add the image test to the list of images, use %%IMAGE%%:test%% to add it to the HTML code.

Adding images in error or authentication pages

  1. Go to System > Config > Replacement Message.
  2. Click Manage Images tab, and then click Create New.
  3. Specify a name for the image file, select its content type, and then click Choose File to browse to the file and select it.
    Ensure the image is no larger than 24 kb and that its type matches the value you have selected for Content Type.
  4. Click OK, and then click Return to return to the list of customizable pages.

Customizing the message returned for LDAP errors (%%REPLY_TAG%% macro)

By default, the Login Page replacement message is formatted to simply display any reply message it receives from the authentication server.

However, you can use JavaScript to customize the message that is displayed.

For example, locate the following section of the replacement message:

<h2>
            %%REPLY_TAG%%
</h2>

Replace the macro and its formatting with the following script:

<h2>

< script type = "text/javascript" >

var r = "%%REPLY_TAG%%";

if (r == "Login Failed") {

document.write("Invalid Username or Password...");

} else if (r == "Username and password can't be null") {

document.write("Username or password empty");

} else if (r == "Invalid credentials") {

document.write("Invalid Username or Password");

} else if (r != "") {

document.write(r);

} < /script>

</h2>

Hiding the checkbox "I want to change my password after logging in"

By default, the checkbox "I want to change my password after logging in" is displayed. It's implemented by the following code:

<div class="fel" style="display: %%DISPLAY_OR_HIDE%%">

<table>

<tr>

<td width="75px" align="right">

<input type="checkbox" name="sph_cpw" autocomplete="off" />

</td>

<td style="padding-left: 15px">

<label style="font-size: 12px">

I want to change my password after logging in

</label>

</td>

</tr>

</table>

</div>

To hide this checkbox, you can replace the above code with the following one:

<div class="fel" style="display: %%DISPLAY_OR_HIDE%%">

<table style="display: none">

<tr>

<td width="75px" align="right">

<input type="checkbox" name="sph_cpw" autocomplete="off" />

</td>

</tr>

</table>

</div>

Customizing error and authentication pages (replacement messages)

You can customize the following FortiWeb HTML pages:

  • Pages that FortiWeb presents to clients when it authenticates users.

    FortiWeb uses these pages when the client authentication method in a site publishing configuration is HTML Form Authentication. For details, see Site Publishing (Single sign-on).

  • The error page FortiWeb uses to respond to a HTTP request that violates a policy and the configured action is Alert & Deny or Period Block.
  • The error page FortiWeb uses to respond to a AJAX request that violates a policy and the configured action is Alert & Deny or Period Block.
  • The "Server Unavailable!" page that FortiWeb returns to the client when none of the server pool members are available either because their status is Disable or Maintenance or they have failed the configured health check.

FortiWeb uses each page for specific server policy.

Configuring an error or authentication page

Follow steps below to configure an error or authentication page:

  1. Go to System > Config > Replacement Message.
  2. Select Replacement Message.
  3. Select the message you want to edit in the list of messages or click Create New to create a new message.
    You can also select the predefined one to take it as a template, or select a message and click Clone to clone this message.
  4. You can enable Replacement Message for AJAX requests to respond to a AJAX request, and configure the AJAX block page message. You must enable it by going to System > Config > Feature Visibility first.
  5. If you have selected Attack block page and want to change the HTTP response code it displays, click Edit HTTP Response Code. Enter a new value for the code, and then click Apply. For details, see Attack block page HTTP response codes.
  6. In the bottom-right pane, edit the HTML code as required.
    The results of any changes you make are displayed immediately in the bottom-left pane.
  7. Click Save to save your changes or Restore Defaults to revert to the preset version of the page.
  8. Select the replacement message when you edit a policy.
  9. For details about using macros in the code, see Macros in custom error and authentication pages.

Pre-login disclaimer message

Go to System > Config > Replacement Message, and select Disclaimer tab. You can edit the disclaimer message. Click Save to save your changes or click Restore Defaults to revert to the preset version.

Attack block page HTTP response codes

You can specify the HTTP response code that the attack block message page displays. If the error status code allows an attacker to fingerprint a vulnerable application, you can customize it to display a more vague reply. (For all other pages, you cannot change the default response code.)

The following codes are examples of HTTP response codes:

  • 200—OK. Typically indicates success, and accompanies resource requested by the client.
  • 400—Bad Request. Typically indicates wrong syntax.
  • 403—Forbidden. Typically indicates inaccessible files.
  • 404—File Not Found. Typically indicates missing files.
  • 500—Internal Server Error. Typically indicates one of many possible conditions such as a servlet runtime error.
  • 501—Not Implemented. Typically indicates a non-existent function on the web application.

Macros in custom error and authentication pages

When it generates error and authentication messages, FortiWeb generates some of the message content using macros. It uses two type of macros: label macros and image macros.

Although you can add the predefined macros to your custom messages, you cannot create macros and you cannot modify the label macros. You can modify an image macro to reference a predefined image or one that you have uploaded.

Label macros

You can use the following label macros anywhere in the HTML code for Attack Block Page and Server Unavailable Message messages:

%%URL%%

Inserts one of the following URLs:

  • The URL of a web page blocked by either the web filtering or URL blocking feature.
  • The URL of a web page that contains a blocked file that a client has tried to download.
%%SOURCE_IP%% The source IP address of the client that attempted to access the web service.
%%DEST_IP%% The IP address of the web server.
%%VSERVER_IP%% The IP address of the virtual server.
%%EVENT_ID%% An ID number that identifies the attack type. Use this number to help you locate the log for the event in the FortiWeb attack log.

You can use the following label macros anywhere in the HTML code for the Site Publish Authentication messages:

All the macros and parameters in the HTML code can't be removed or edited except %%REPLY_TAG%% and %%DISPLAY_OR_HIDE%%. The text that shows in the Web GUI is allowed to be modified.

For example, in the following code, the macros (e.g. %%TOKEN_POST_URL%%) and parameters (e.g. sph_org_location) can't be removed or edited, but the Web GUI text "Authentication Required" can be replaced with any text as you desire.

<form action="%%TOKEN_POST_URL%%" method="post">

<input type="hidden" name="sph_org_location" value="%%ORG_LOCATION_VAL%%">

<h1 style="background:#eee center 25px ;">

Authentication Required

</h1>

%%ORG_LOCATION_VAL%% The original URL that the client tried to access.
%%REPLY_TAG%% The authentication server reply message. For an example of how you can customize the message by replacing this macro with JavaScript, see Customizing the message returned for LDAP errors (%%REPLY_TAG%% macro).

%%DISPLAY_OR_HIDE%%

Display or hide the checkbox "I want to change my password after logging in". It's by default displayed. For how to hide this checkbox, see Hiding the checkbox "I want to change my password after logging in".

%%LOGIN_POST_URL%% The login URL where users post their credentials.
%%TOKEN_POST_URL%% The login URL where users insert their token code.
%%RSA_LOGIN_POST_URL%% The login URL where users post their RSA SecurID credentials.
%%RSAC_POST_URL%% The login URL where users post their RSA SecurID credentials.
%%ACCOUNT%% The username credential of a user who exceeded the maximum number of login attempts.
%%PERIOD_TIME%% The length of time that FortiWeb prevents a user from attempting to log in again, after the user has exceeded the allowed number of login attempts. The site publishing policy specifies the value.

%%MSG_ID%%

The message ID number idenfities the attack log message ID, and can be used to map the event to the log in the FortiWeb attack log.

Image macros

Use the following format to add an image macro anywhere in a custom error or authentication message:

%%IMAGE:<image_name>%%

where <image_name> is the name of either a predefined image or one you have uploaded. To view or upload images, go to System > Config > Replacement Message, and then select Manage Images tab. For details, see Adding images in error or authentication pages.

For example, in the default Attack Block Page message, the macro %%IMAGE%%:logo_v2_fnet%% adds the predefined image logo_v2_fnet. If you add the image test to the list of images, use %%IMAGE%%:test%% to add it to the HTML code.

Adding images in error or authentication pages

  1. Go to System > Config > Replacement Message.
  2. Click Manage Images tab, and then click Create New.
  3. Specify a name for the image file, select its content type, and then click Choose File to browse to the file and select it.
    Ensure the image is no larger than 24 kb and that its type matches the value you have selected for Content Type.
  4. Click OK, and then click Return to return to the list of customizable pages.

Customizing the message returned for LDAP errors (%%REPLY_TAG%% macro)

By default, the Login Page replacement message is formatted to simply display any reply message it receives from the authentication server.

However, you can use JavaScript to customize the message that is displayed.

For example, locate the following section of the replacement message:

<h2>
            %%REPLY_TAG%%
</h2>

Replace the macro and its formatting with the following script:

<h2>

< script type = "text/javascript" >

var r = "%%REPLY_TAG%%";

if (r == "Login Failed") {

document.write("Invalid Username or Password...");

} else if (r == "Username and password can't be null") {

document.write("Username or password empty");

} else if (r == "Invalid credentials") {

document.write("Invalid Username or Password");

} else if (r != "") {

document.write(r);

} < /script>

</h2>

Hiding the checkbox "I want to change my password after logging in"

By default, the checkbox "I want to change my password after logging in" is displayed. It's implemented by the following code:

<div class="fel" style="display: %%DISPLAY_OR_HIDE%%">

<table>

<tr>

<td width="75px" align="right">

<input type="checkbox" name="sph_cpw" autocomplete="off" />

</td>

<td style="padding-left: 15px">

<label style="font-size: 12px">

I want to change my password after logging in

</label>

</td>

</tr>

</table>

</div>

To hide this checkbox, you can replace the above code with the following one:

<div class="fel" style="display: %%DISPLAY_OR_HIDE%%">

<table style="display: none">

<tr>

<td width="75px" align="right">

<input type="checkbox" name="sph_cpw" autocomplete="off" />

</td>

</tr>

</table>

</div>