HTTP-based Authentication

HTTP-based Authentication

You are here:

The following documentation is aimed at Splash page services who would like to use the Open Mesh HTTP protocol for Captive Portal authentication. It is a relatively simple process compared to other authentication protocols such as RADIUS.

Initial Configuration

Should you choose this protocol, it is necessary for you to develop a splash page solution and run it on a server that can respond to HTTP requests. Please see to the following example code for reference: http_example_code.php

Next, please specify HTTP as the type of authentication service you are using on the Kaiwoo console or via the Provisioning API. Make sure to configure the URL of your HTTP server along with its secret. This too can be done on the Kaiwoo console or via the Provisioning API.

After covering these key steps, let’s take a look at the HTTP functions in detail.

HTTP Protocol Requests

The Open Mesh HTTP protocol comprises four types of requests:

  1. Pre-Login
  2. Login
  3. Accounting
  4. Logout

The request query-string structure follows a defined pattern as shown below. The root includes your HTTP Server URL, followed by the type of request with its specific parameters.

Example:

http://exampleauthserver.com/auth.php?type=login
&ra=B83DB5D253017788463892C5D45C035B&session=5e13015
&mac=65%3A76%3ABA%3A8A%3AD3%3A58
Request Authenticator

RA stands for Request Authenticator and can be understood as an encrypted password helping to protect against so-called Man-in-the-Middle attacks. It is used to verify that both the sender and receiver of an HTTP request are in possession of the HTTP secret without exchanging the password in the clear. This can be achieved by hashing the HTTP secret via the MD5 algorithm and then exchanging a unique 128-bit fingerprint known as MD5 hash. In other words, the RA appears as a sequence of random characters passed as hexadecimal string.

The RA of the Response packet comes in form of a hexadecimal string and includes the md5 hash, the Authentication Response’s CODE value, followed by the original RA and finally the HTTP secret, which was provided via the Kaiwoo Console or Provisioning API during initial configuration. Keep in mind the RA must be decoded from the hex string into a binary format.

Computing RA sent in HTTP response:

  1. Convert received Request Authenticator from hexadecimal to binary form
  2. Concatenate response code (ACCEPT/REJECT/OK), binary Request Authenticator and HTTP secret into single string
  3. Compute md5 checksum of concatenated string

In Pseudocode it would look like this:

code = 'ACCEPT'
request_ra_bin = hex_to_binary(HTTP_GET['RA'])
response_ra = md5(code, request_ra_bin, http_secret)

1. Pre-Login

The Pre-Login is used to recognize clients with ongoing sessions or clients who are allowed to by-pass the Splash page authentication for various reasons.

The following parameters will be exchanged:

Pre-Login request parameters
parameter nameparameter value
typeType is called “status”.
raThe sequence of random characters passed as hexadecimal string.
sessionA unique string identifying the session. This ID shall be used during all subsequent requests within the same session.
macThe Ethernet MAC address of the WiFi client. Format: six hex bytes separated by colons (“:”).

Example:

GET http://exampleauthserver.com/accept.php?
type=status
&ra=4123F4A168A22CD9125C10B630EA4195
&session=48FAF4CE2AC7D93CC1FAA1759E6FF64C
&mac=11%3A22%3A33%3A44%3A55%3A66
Pre-Login response parameters
parameter nameparameter value
"CODE"“ACCEPT” signals the AP to allow a WiFi client to by-pass the splash page authentication;
“REJECT” signals the AP to proceed with normal splash page authentication (Login process).
"RA"The updated Request Authenticator sent to AP to confirm validity of the response.
"SECONDS"If the WiFi client is allowed to by-pass the splash page authentication (“CODE” “ACCEPT”), provide number of seconds this login will remain valid for.
"DOWNLOAD"If the WiFi client is allowed to by-pass the splash page authentication (“CODE” “ACCEPT”), provide maximum throughput in kbits/sec from AP to WiFi client.
"UPLOAD"If the WiFi client is allowed to by-pass the splash page authentication (“CODE” “ACCEPT”), provide maximum throughput in kbits/sec from WiFi client to AP.
"BLOCKED_MSG"If the WiFi client is not allowed to by-pass the splash page authentication (“CODE” “REJECT”), provide a human-readable message why the Pre-Login request was rejected. Mostly used for debugging purposes.

Example:

    "CODE" "REJECT"
    "RA" "7b40dfe92d85298b11c32d9a4e4d79c8"
    "BLOCKED_MSG" "Unknown Client"

2. Login

After Splash page authentication, the WiFi client is redirected back to the Access Point. The Access Point initiates the Login process in order to verify whether the WiFi client was successfully authenticated by the Splash page authentication server.

The Authentication Server responds to the Login Request by either informing Kaiwoo that the user’s credentials are correct and they are authenticated to use the network, or rejecting the login with an optional message indicating why. In case of authentication success, the Access Point grants network access to the user and redirects it to the service landing page, if configured, or alternatively to the URL the user originally requested. Detailed information about the Splash page redirect process can be found here.

The password retrieved from the splash page’s login form is encrypted by the AP before being transmitted. To learn more about the password encryption and decryption algorithm, please see the following link.

The following parameters will be exchanged:

Login request parameters
parameter nameparameter value
typeType must be set to “login”
raThe sequence of random characters passed as hexadecimal string.
sessionA unique string identifying the session. This ID shall be used during all subsequent requests within the same session.
macThe Ethernet MAC address of the WiFi client requesting authentication. Format: six hex bytes separated by colons (“:”).
nodeThe primary MAC address of the AP to which the WiFi client is attempting to connect Format: six hex bytes separated by colons (“:”).
usernameThe name of the user provided by the splash page to the AP on redirect.
passwordThe sequence of hexadecimal characters requiring decryption.

Example:

GET http://exampleauthserver.com/accept.php?
type=login
&ra=FC85056CE9DDF76EBAE620B56D63031D
&session=A96066ED08848890EE67F13342489B61
&mac=11%3A22%3A33%3A44%3A55%3A66
&node=66%3A55%3A44%3A33%3A22%3A11
&username=splashpage-username
&password=6E13364322A961F17AFF1B8DF7E8577C38F6C63C19281DF2D1FBAAECDC845A70995A56B65C753D6F15E150A31D43832E
Login response parameters
parameter nameparameter value
"CODE"“ACCEPT” signals the AP to allow a WiFi client to access the network;
“REJECT” signals the AP not to grant network access.
"RA"The updated Request Authenticator sent to AP to confirm validity of the response.
"SECONDS"If the WiFi client is allowed to by-pass the splash page authentication (“CODE” “ACCEPT”), provide number of seconds this login will remain valid for.
"DOWNLOAD"If the WiFi client is allowed to by-pass the splash page authentication (“CODE” “ACCEPT”), provide maximum throughput in kbits/sec from AP to WiFi client.
"UPLOAD"If the WiFi client is allowed to by-pass the splash page authentication (“CODE” “ACCEPT”), provide maximum throughput in kbits/sec from WiFi client to AP.
"BLOCKED_MSG"If the WiFi client is not allowed to access the network (“CODE” “REJECTED”), provide a human-readable message why the Login request was rejected.

Example:

"CODE" "ACCEPT"
"RA" "07b782dd0e1962794315942a39011bf9"
"SECONDS" "3600"
"DOWNLOAD" "2000"
"UPLOAD" "800"

3. Accounting

Accounting requests are used to deliver information about the status of an ongoing session from the Access Point to the Authentication Server. It includes data such as a user’s current bandwidth usage.

The following parameters will be exchanged:

Accounting request parameters
parameter nameparameter value
typeType must be set to “acct”
raThe Request Authenticator generated by the AP.
sessionA unique string identifying the session. This ID shall be used during all subsequent requests within the same session.
macThe MAC address of the WiFi client. Format: six hex bytes separated by colons (“:”).
nodeThe primary MAC address of the Access Point which issued this request. Format: six hex bytes separated by colons (“:”).
downloadThe number of bytes downloaded by the WiFi client since the last accounting update.
uploadThe number of bytes uploaded by the WiFi client since the last accounting update.

Example:

GET http://exampleauthserver.com/accept.php?
type=acct
&ra=F8E0113B436D8E95AED0E196648A9E3A
&session=A96066ED08848890EE67F13342489B61
&mac=11%3A22%3A33%3A44%3A55%3A66
&node=66%3A55%3A44%3A33%3A22%3A11
&download=27161
&upload=41759
Accounting Response Parameters
parameter nameparameter value
"CODE"The response is “OK”.
"RA"The updated Request Authenticator sent to AP to confirm validity of the response.

Example:

"CODE" "OK"
"RA" "1f2fd5293006ceeab1bc24d58e6891b8"

4. Logout

The Logout Request is used to inform the Authentication server that a session has ended. It is sent by the Access Point upon session expiry or manual user logout and contains final accounting information. The captive portal service may then redirect the user to its Logout page as shown in this article.

The following parameters will be exchanged:

Logout request parameters
parameter nameparameter value
typeType must be set to “logout”.
raThe Request Authenticator generated by the AP.
sessionA unique string identifying the session. This ID shall be used during all subsequent requests within the same session.
macThe MAC address of the WiFi client. Format: six hex bytes separated by colons (“:”).
nodeThe primary MAC address of the Access Point which issued this request. Format: six hex bytes separated by colons (“:”).
downloadThe number of bytes downloaded by the WiFi client since the last accounting update.
uploadThe number of bytes uploaded by the WiFi client since the last accounting update.
Example:
GET http://exampleauthserver.com/accept.php?
type=logout
&ra=8645E1DBF202C726618A65A3BCC29ED5
&session=A96066ED08848890EE67F13342489B61
&mac=11%3A22%3A33%3A44%3A55%3A66
&node=66%3A55%3A44%3A33%3A22%3A11
&download=6837
&upload=11116
Logout response parameters
parameter nameparameter value
"CODE"The response is “OK”.
"RA"The updated Request Authenticator sent to AP to confirm validity of the response.

Example:

"CODE" "OK"
"RA" "3aabead5afd7eaaeae41b48fb9f62fed"
Next HTTP-based Authentication: Password Decryption
Table of Contents