Third-Party Hosted AP Captive Portal

These steps describe the work flow for guest user authentication to a portal using an external web server with sign-in/click-through:

1. Wi-Fi user connects to the guest SSID and opens a URL from any web browser using the HTTP protocol.
2. AP intercepts this request and redirects the browser to the configured external portal page, including the request parameters as the GET parameters of the redirected URL. For example:

https://webserver.example.com/guest-login.php?res=notyet&challenge=b22bc0c9da62277a4138b5d0d686bf2c&service_id=&login_url=http://172.17.30.54:5282/logon&logoff_url=http://172.17.30.54:5282/logoff&ap_id=00:11:74:96:57:BF&uamip=172.17.30.54&uamport=5282&ap_ssid=Guest-Wi-Fi&client_mac=8C:FA:BA:89:07:8C&blackout_time=0&userurl=http://www.watchguard.com/&failure_count=0

• Challenge (challenge) — A random sequence of bytes in the hexadecimal format provided to the portal for encoding the plain text password.
• Login URL (login_url) — Portal redirects the web browser to this URL after accepting the username and password from the user.
• AP MAC address (ap_id) — MAC address of the AP.
• AP IP address (uamip) — IP address of the AP.
• AP Port Number (uamport) — Port number on which the HTTP service is available on the AP.
• Failure Count (failure_count) — Number of previous failed attempts by the client.
• Requested URL (userurl) — Original URL requested by the browser that was intercepted by the AP.
• Logoff URL (logoff_url) — URL to which the client needs to be redirected for the purpose of logging off from the AP.
• Blackout Time (blackout_time) — Remaining blackout time.
• Request Type (res) — Type of request to the portal. This is provided if the portal supports more than one kind of work flow.
• Client MAC (client_mac) — MAC address of the Wi-Fi client.

3. The client web browser accesses the redirected external splash page and the user provides the requested details in the external captive portal splash page.
4. The captive portal on the external Web server takes the challenge parameter from the redirected URL. It then generates an HMAC digest using the shared secret for the portal that is configured in the SSID profile and the challenge parameter. For more information, see How the HMAC Digest is Generated.
5. The Web server uses the login_url parameter mentioned in step 2 and appends these GET parameters to the URL. The portal then redirects the client web browser to this newly generated URL (new login URL). For example:

http://172.17.30.54:5282/logon?res=sucess&challenge=1234567890&digest=abcdeabcdeabcdeabcdeabcdeabcdeabcdeabcde

• Challenge (challenge) — A random sequence of bytes provided by the AP.
• HMAC Digest (digest) — HMAC digest of the GET parameters generated the algorithm. For more information, see How the HMAC Digest is Generated.
• Response Type (res) — Sets the value of this parameter to success or failure based on the authentication result.
• Login Time (session_timeout) — Optionally, the portal can append the time (in seconds) for which the Wi-Fi client can access the guest network. After this timeout, the client is redirected to the portal again. If not appended, the client session is timed-out after the default login timeout configured in the SSID profile.
• Redirect URL (redirect) — Optionally, the portal can append the URL to which the web browser will be redirected to after successful authentication. If not appended, the client will be redirected to the redirect URL configured in the SSID profile or the original requested URL If you append an URL, the URL must be encoded. For more information, see Sample Code for URL Encoding.

6. The client requests access to the new login URL (redirected from the portal) to the AP.
7. The AP decodes the HMAC digest using the shared secret for the portal configured in the SSID profile and the challenge that it originally sent in Step 2.
8. If successful, the AP allows the client to access the Internet. The AP redirects the client web browser to the URL sent by the portal (redirect parameter). If the portal did not include the redirect parameter in the login URL in Step 5, then the client browser is redirected to the URL configured in the Redirect URL field in the Captive Portal settings of the SSID profile. If the redirect URL is not configured in the SSID profile, the client web browser is redirected to the original URL accessed from the client in Step 1.

How the HMAC Digest is Generated

After the user enters the requested information on the captive portal splash page and submits it for login, the captive portal must perform these tasks:

1. Fetch the challenge and login_url parameters from the redirected URL.
2. Generate an HMAC digest using the shared secret for the portal configured in the SSID Profile applied on the AP and the challenge parameter.
3. Regenerate a login URL using the login_url parameter received in the request, and append the challenge received from the AP and the generated HMAC digest to the URL.
4. Redirect the client to this new login URL.

These steps describe how the HMAC digest is generated:

1. Generate the HMAC key as the 20 byte SHA1 hash of the portal secret

hmac_key=SHA1(portal_secret)

The hmac_key is 20 byte binary output and not 40 byte hexadecimal.

2. Generate the parameter string.

params="res=success&challenge=<value from AP>"

3. Generate HMAC Digest

digest=HMAC-SHA1(params, hmac_key)

When the HMAC digest is generated, the redirection URL is prepared for forwarding the digest to the AP using the digest parameter and the challenge and login_url parameters provided by the AP. The client is redirected to this URL after successful authentication to the portal.

<login_url>?res=success&challenge=<value from AP>&digest=<digest>

This code snippet shows how to generate the HMAC digest with PHP:

<?php

class ExternalPortal {

	/* These must be initialized from the get parameters provided by AP

	while redirecting to the portal URL. */

	public $logonURL = '';

	public $challenge = '';

	/* The configured shared secret value must be assigned here (same as

	that in the SSID profile portal settings). */

	public $sharedSecret = null;

	/* Get logon Url. Redirect to this URL from caller.

	@return string */

	public function getApLogonUrl() {

		if($this->sharedSecret == null || $this->challenge == null ||

	$this->logonURL == null)

	return null;

	/* Response parameters like session_timeout and blackout_time can

	be included here */

	$responseParams = sprintf('res=success&challenge=%s',

	$this->challenge);

	$digest = $this->generateDigest($responseParams,

	$this->sharedSecret);

	/* digest must be in hex (40byte) format */

	return sprintf('%s?%s&digest=%s', $this->logonURL, $responseParams,

	$digest);

	}

	/* Generate the HMAC digest for the response parameters using shared

	secret

	* @param type $returnParam

	* @param type $sharedSecret

	* @return string

	*/

	protected function generateDigest($returnParam, $sharedSecret) {

		$key = sha1($sharedSecret);

		$key = substr($key, 0, 40);

		/* Convert the key from HEX (40bytes) to binary(20bytes) */

		$asciiKey = pack("H*", $key);

		$digest = hash_hmac("sha1", $logonParams, $asciiKey);

		return $digest;

		}

	}

?>

Sample Code for URL Encoding

You can use this example code to encode a URL.

public function getApLogonUrl() {

	$redirect_url=urlencode($_GET['redirect']);

	$responseParams = sprintf('res=success&challenge=%s&redirect=%s',

		$_GET['challenge'], $redirect_url);

	$digest = $this->generateDigest($responseParams,$this->sharedSecret);

	return sprintf('%s?%s&digest=%s', $_GET['login_url'], $responseParams,

		$digest);

}