Use these guidelines to configure a web server for hotspot external guest authentication. The web server can be located on any network connected to the XTM device. We recommend that you install the web server in the same part of your network as your other public servers.
This diagram summarizes the main steps in the interaction between the client browser, the XTM device, and the external web server.
The steps in the external authentication process are:
The main steps in this external authentication process are more fully described in the subsequent sections.
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 Code Example for Wireless Hotspot External Authentication.
On the web server, you must create three web pages to work with this feature:
These pages are described in the subsequent sections.
For the web server to successfully communicate with your XTM device, you must make sure that the web server can get access to the XTM device.
The web server must send the authentication page to the hotspot client when it receives an access request URL from the XTM device.
The web program must save all the information that comes in the access request URL, described in Interaction Step 2. It 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 XTM device 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 XTM device.
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 XTM device must know only the access decision and other parameters required to verify the integrity of the interaction.
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 Interaction Step 6. 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:
The action type. The value must be hotspot_auth.
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.
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 XTM device. 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.
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 XTM device. 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.
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 XTM device.
The formula to calculate the checksum value is Hash = SHA1(ts + sn + mac + success + sess-timeout + idle_timeout + shared_secret). The XTM device uses the checksum to validate the integrity of the interaction between the client browser and the external web server.
The redirect URL you want the XTM device 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 Interaction Step 6, the web page sends the access decision URL to the XTM device. This page also causes the client browser to send the access decision to the XTM device in order to check the integrity of the interaction and create a hotspot session for the client on the XTM 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">
<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/" />
After Interaction Step 7, if the XTM device detects any error in the authentication process, for example a URL parameter error, create session error, or invalid checksum, the XTM device redirects the client browser to the failure page of the external web server in Interaction Step 8.
The XTM device constructs the failure URL with an error code to indicate why the 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:
The failure URL includes these parameters:
The XTM device 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|
|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.
If the external web server must log off a specified client, it sends a logoff URL to the XTM device 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 XTM device to be able to successfully log off a client, the external web server must include these specific details in the logoff URL:
The action type. The value must always be hotspot_logoff.
The MAC address of the client to log off. The web server can use the same MAC address used in the access request URL.
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 XTM device.
The formula to calculate the checksum value is sig = SHA1(mac + secret). The XTM device uses the checksum value to identify the external web server. This enables the XTM device 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:
When the XTM device 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
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
This message appears if the session already timed out or was deleted.
An internal error occurred
You can review the error messages to see if there is a problem with the logoff URL settings and adjust them as necessary.
Configure the Hotspot for External Guest Authentication
Troubleshoot Hotspot External Guest Authentication