Follow these guidelines to configure a web server for hotspot external guest authentication. The web server can be located on any network connected to the Firebox. WatchGuard recommends that you install the web server in the same part of your network as your other public servers.
External Authentication Process
This diagram summarizes the main steps in the interaction between the client browser, the Firebox, and the external web server.
The steps in the external authentication process are:
- A hotspot user tries to browse to a web page.
- If this is a new hotspot user, the Firebox redirects the client browser to the Authentication URL on the external web server.
This URL includes a query string that contains the access request. - The browser sends the access request to the external web server.
- The external web server sends the Authentication page to the browser.
- The hotspot user types the requested authentication information and submits the form to the external web server.
- The external web server processes the authentication information and sends an HTML page that contains the decision URL to the browser.
- The browser sends the access decision to the Firebox.
The access decision URL contains the access decision, a checksum, and a redirect URL. - The Firebox reads the access decision, verifies the checksum, and sends the redirect URL to the client browser.
Based on the outcome of the external authentication process, the redirect URL can be:- The original URL the user browsed to, if the external web server sent the original redirect URL.
- A different redirect URL, if the external web server sent a different redirect URL.
- The authentication failure URL, if authentication failed or access was denied.
- The external web server sends a logoff URL to the Firebox to end the user hotspot session.
The main steps in this external authentication process are more fully described in the next sections.
Requirements
You can write the web program in Perl, Python, PHP, or any other language. For reference, we provide a code example written in Python. The code example is attached to the Knowledge Base article Hotspot External Guest Authentication Example.
On the web server, you must create three web pages to work with this feature:
- Authentication Page — Receives the authentication information from the hotspot user.
- Result Page — Returns the authentication result and redirects the client browser to send the access decision to the Firebox.
- Authentication Failure Page — Shows error information if there is an error, or if access is denied.
These pages are described in the next sections.
For the web server to successfully communicate with your Firebox, you must make sure that the web server can get access to the Firebox.
Authentication Page
The web server must send the authentication page to the hotspot client when it receives an access request URL from the Firebox.
The web program must save all the information that comes in the access request URL (Step 2 in the External Authentication process). The web program can use the timestamp and MAC address parameters as a key or can use a file name to save this data. After the client finishes authentication, the web program for the Result Page must retrieve this data from the saved request and use it together with the shared secret to calculate a hash checksum.
This example shows the format of an access request URL:
http://10.0.2.80:8080/auth.html?xtm=http://10.0.3.1:4106/wgcgi.cgi &action=hotspot_auth&ts=1344238620&sn=70AB02716F745&mac=9C:4E:36:30:2D:26 &redirect=http://www.google.com/
The access request URL includes these parameters:
xtm — The URL on the Firebox where the external web server must send the access decision.
action — The action type. The value is always hotspot_auth.
ts — The time stamp for the request.
sn — The serial number of the Firebox.
mac — The MAC address of the client.
redirect — The original URL the hotspot user tried to browse to.
You define the details of the authentication process. The Firebox must know only the access decision and other parameters required to verify the integrity of the interaction.
Result Page
After the hotspot user provides the requested authentication information, the web program must determine whether to allow access, based on the information provided by the hotspot user and any access criteria you specify. The web program must combine all the required parameters into one URL, and include it in a web page that it sends to the client browser, as described in Step 6 in the External Authentication process. This URL is called the access decision URL.
This example shows the format of the access decision URL:
http://10.0.3.1:4106/wgcgi.cgi?action=hotspot_auth&ts=1344238620&success=1& sess_timeout=1200&idle_timeout=600&&sig=a05d352951986e5fbf939920b260a6be3a9fffd3& redirect=http://www.google.com/
The access decision URL begins with the URL specified in the xtm parameter in the access request URL.
The access decision URL must include all of these parameters:
action
The action type. The value must be hotspot_auth.
success
The decision about hotspot access. Set the value to 1 to allow the user to get access the hotspot, or 0 to not allow access.
sess_timeout
The session timeout value for the user hotspot connection. Specify the amount of time in seconds that a user can be connected to the hotspot for each session. Set the value to 1 to use the Session Timeout setting configured on the Firebox. Set the value to 0 to disable the session timeout value. When you set the value to 0, the user connection to the hotspot does not timeout.
idle_timeout
The idle timeout value for the user hotspot connection. Specify the amount of time in seconds that a user session connection to the hotspot can be idle before the session is disconnected. Set the value to -1 to use the default Idle Timeout setting configured on the Firebox. Set the value to 0 to disable the idle timeout value. When you set the value to 0, the user connection to the hotspot does not expire when there is no traffic between the user client and the hotspot.
sig
A hex encoded string in lower case. It is a SHA1 checksum based on the values of ts, sn, mac, success, sess_timeout, idle_timeout, and the shared secret. The shared secret you use to calculate the hash checksum must match the shared secret configured in the hotspot settings on the Firebox.
The formula to calculate the checksum value is Hash = SHA1(ts + sn + mac + success + sess-timeout + idle_timeout + shared_secret). The Firebox uses the checksum to validate the integrity of the interaction between the client browser and the external web server.
redirect
The redirect URL you want the Firebox to send to the hotspot user after successful authentication. To redirect the browser to the original URL the user requested, use the value originally received in the access request URL. To redirect users to a different URL, specify that URL in this parameter.
In Step 6 of the External Authentication process, the web page sends the access decision URL to the Firebox. This page also causes the client browser to send the access decision to the Firebox in order to check the integrity of the interaction and create a hotspot session for the client on the Firebox hotspot.
This web page can use a hyperlink to send the whole decision URL or it can use a <form> to send a message that contains all the fields in the authentication decision URL.
Example of hyperlink:
<a href="http://10.0.3.1:4106/wgcgi.cgi?action=hotspot_auth &ts=1344238620&success=1&sess_timeout=1200&idle_timeout=600& sig=a05d352951986e5fbf939920b260a6be3a9fffd3&redirect=http://www.google.com/">Connect</a>
Example of form:
<form action="http://10.0.3.1:4106/wgcgi.cgi" method="post">
<fieldset>
<input type="submit" name="Connect" value="Connect" title="Connect" />
<input type="hidden" name="action" value="hotspot_auth" />
<input type="hidden" name="ts" value="1344238620" />
<input type="hidden" name="success" value="1" />
<input type="hidden" name="sess_timeout" value="1200" />
<input type="hidden" name="idle_timeout" value="600" />
<input type="hidden" name="sig" value="a05d352951986e5fbf939920b260a6be3a9fffd3" />
<input type="hidden" name="redirect" value="http://www.google.com/" />
</fieldset>
</form>
Authentication Failure Page
After Step 7 of the External Authentication process, if the Firebox detects any error in the authentication process, for example a URL parameter error, create session error, or invalid checksum, the Firebox redirects the client browser to the failure page of the external web server in Interaction Step 8.
The Firebox constructs the failure URL with an error code to indicate why authentication did not succeed. You can use these as the basis for messages to the user on the authentication failure page.
This example shows the format of the failure URL:
http://10.0.2.80:8080/failure.html?error=510&sn=70A70272B454E &mac=9C:4E:36:30:2D:28
The failure URL includes these parameters:
- error — The error number that indicates the reason for failure.
- sn — The serial number of the Firebox.
- mac — The MAC address of the client.
The Firebox can set the error parameter to one of these error numbers:
| Error | Reason for Failure |
|---|---|
| 510 | Invalid authentication result or signature |
| 511 | Invalid CGI parameter |
| 512 | Create hotspot session failed |
| 513 | Internal error |
| 514 | External authentication failed (success=0) |
You can configure the authentication failure page on the external web server to show different messages to the hotspot user based on the error code.
Logoff URL
If the external web server must log off a specified client, it sends a logoff URL to the Firebox that includes the MAC address of the client to log off. Each logoff URL can log off only one client at a time. For the Firebox to be able to successfully log off a client, the external web server must include these specific details in the logoff URL:
action
The action type. The value must always be hotspot_logoff.
mac
The MAC address of the client to log off. The web server can use the same MAC address used in the access request URL.
sig
A hex encoded string in lower case. It is a SHA1 checksum based on the macvalue and the shared secret. The shared secret you specify in the sig to calculate the hash checksum must match the shared secret configured in the hotspot settings on the Firebox.
The formula to calculate the checksum value is sig = SHA1(mac + secret). The Firebox uses the checksum value to identify the external web server. This enables the Firebox to only allow logoff requests from legitimate sources, and to make sure logoff requests from malicious sources are denied.
The external web server uses these parameters to generate the logoff URL in this format:
http://10.0.3.1:4106/wgcgi.cgi?action=hotspot_logoff&mac=9C:4E:36:30:2D:26 &sig=03349009b213b701871b936007cd92bc0eb94376
When the Firebox receives the logoff URL from the external web server, it sends one of these responses:
Success or failure of the user hotspot session log off
<?xml version="1.0"?>
<authentication>
<logoff_list>
<logoff>
<session_id>12</session_id>
<success>1</success>
</logoff>
</logoff_list>
</authentication>
A <success> value of 0 means the logoff attempt failed. A <success> value of 1 means the logoff attempt succeeded.
The user hotspot session was not found
<?xml version="1.0"?>
<authentication>
<logoff_list/>
</authentication>
This message appears if the session already timed out or was deleted.
An internal error occurred
<?xml version=\"1.0\"?>
<authentication>
<internal_error/>
</authentication>
You can review the error messages to see if there is a problem with the logoff URL settings and then make any necessary adjustments to the settings.