10.3. Customizing Authentication HTML

Home Prev	cOS Core 15.00.01 Administration Guide	Next

User Authentication makes use of a set of HTML files to present information to the user during the authentication process. The options available for HTTP authentication processing are as follows:

When a user attempts to use a browser to open a web page they are directed to a login page (the FormLogin page). After successful login, the user is taken to the originally requested page.
After successful login, instead the user can be taken to a specified web page.
After successful login, the user is taken to a particular web page (the LoginSuccess page) before being automatically redirected to the originally requested page.

HTTP Banner Files

The web page files, also referred to as HTTP banner files, are stored within cOS Core and already exist by default at initial cOS Core startup. These files can be customized to suit a particular installation's needs either by direct editing in Web Interface or InControl or by downloading and re-uploading through an SCP client.

Banner files in cOS Core are of two types:

Banner files for authentication rules using Web Auth (HTTP and HTTPS login). These are discussed below.
Banner files for the HTTP ALG. These are discussed in Section 6.2.4, Customizing WCF HTML Pages.

Banner Files for Web Authentication

The web authentication files available for editing have the following names:

FormLogin
LoginSuccess
LoginFailure
LoginAlreadyDone
LoginChallenge
LoginChallengeTimeout
LogoutSuccess
LogoutSuccessBasicAuth
LogoutFailure
FileNotFound

Customizing Banner Files

The Web Interface provides a simple way to download and edit the files and then upload the edited HTML back to cOS Core.

To perform customization it is necessary to first create a new Auth Banner Files object with a new name. This new object automatically contains a copy of all the files in the Default Auth Banner Files object. These new files can then be edited and uploaded back to cOS Core. The original Default object cannot be edited. The example given below goes through the customization steps.

HTML Page Parameters

The HTML pages for WebAuth can contain a number of parameters which are used as needed. These are:

%CHALLENGE_MESSAGE% - The question text asked.
%ERRORMSG% - The reason that access was denied.
%USER% - The username entered.
%REDIRHOST% - The IP of the host that was requested.
%REDIRURL% - The path of the host that was requested.
%REDIRURLENC% - The URL encoded path.
%IPADDR% - The IP address of the client.
%DEVICENAME% - The name of the authenticating firewall.

The LoginFailure Page with ARP Authentication

If authentication fails with ARP authentication (also referred to as MAC authentication), the %USER% parameter will contain the MAC address of the requesting client (or the MAC address of the intervening router nearest the firewall).

A typical set of values for the LoginFailure page when ARP authentication is used might be the following:

	USER:        00-0c-19-f9-14-6f
	REDIRHOST:   10.234.56.71
	REDIRURL:    /testing?user=user&pass=pass
	REDIRURLENC: %2ftesting%3fuser%3duser%26pass%3dpass
	IPADDR:      10.1.6.1
	DEVICENAME:  MyGateway

The %REDIRURL% Parameter Should Not Be Removed

In certain banner web pages, the parameter %REDIRURL% appears. This is a placeholder for the original URL which was requested before the user login screen appeared for an unauthenticated user. Following successful authentication, the user becomes redirected to the URL held by this parameter.

Since %REDIRURL% only has this internal purpose, it should not be removed from web pages and should appear in the FormLogin page if that is used.

Example 10.6. Editing Content Filtering HTTP Banner Files

This example shows how to modify the contents of the URL forbidden HTML page.

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

Go to: System > Advanced Settings > HTTP Banner files > Add > ALG Banner Files
Enter a name such as new_forbidden and press OK
The dialog for the new set of ALG banner files will appear
Click the Edit & Preview tab
Select FormLogin from the Page list
Now edit the HTML source that appears in the text box for the Forbidden URL page
Use Preview to check the layout if required
Press Save to save the changes
Click OK to exit editing
Go to: Objects > ALG and select the relevant HTML ALG
Select new_forbidden as the HTML Banner
Click OK
Go to: Configuration > Save & Activate to activate the new file

	Tip: HTML file changes need to be saved
	In the above example, more than one HTML file can be edited in a session but the Save button should be pressed to save any edits before beginning editing on another file.

Uploading with SCP

It is possible to upload new HTTP Banner files using SCP. The steps to do this are:

Since SCP cannot be used to download the original default HTML, the source code must be first copied from the Web Interface and pasted into a local text file which is then edited using an appropriate editor.
A new Auth Banner Files object must exist which the edited file(s) is uploaded to. If the object is called ua_html, the CLI command to create this object is:
```
Device:/> add HTTPAuthBanners ua_html
```
This creates an object which contains a copy of all the Default user auth banner files.
The modified file is then uploaded using SCP. It is uploaded to the object type HTTPAuthBanners with the name ua_html and property type FormLogin. If the edited Formlogin local file is called my.html then using the Open SSH SCP client, the upload command would be:
```
pscp my.html admin@10.5.62.11:HTTPAuthBanners/ua_html/FormLogin
```
The usage of SCP clients is explained further in Section 2.1.8, Using SCP.
Using the CLI, the relevant user authentication rule should now be set to use the ua_html object. If the rule is called my_auth_rule, the command would be:
```
set UserAuthRule my_auth_rule HTTPBanners=ua_html
```
As usual, use the activate followed by the commit CLI commands to activate the changes on the firewall.