HTTP-based Authentication
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
In order to use this protocol, you need 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 via the Provisioning API. Make sure to configure your HTTP server URL and HTTP secret.
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:
- Pre-Login
- Login
- Accounting
- 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 you provided via the 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:
- Convert received Request Authenticator from hexadecimal to binary form
- Concatenate response code (ACCEPT/REJECT/OK), binary Request Authenticator and HTTP secret into single string
- 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 name | parameter value |
|---|---|
type | Type is called “status”. |
ra | The sequence of random characters passed as hexadecimal string. |
session | A unique string identifying the session. This ID shall be used during all subsequent requests within the same session. |
mac | The 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%3A66Pre-Login response parameters
| parameter name | parameter 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 name | parameter value |
|---|---|
type | Type must be set to “login” |
ra | The sequence of random characters passed as hexadecimal string. |
session | A unique string identifying the session. This ID shall be used during all subsequent requests within the same session. |
mac | The Ethernet MAC address of the WiFi client requesting authentication. Format: six hex bytes separated by colons (“:”). |
node | The primary MAC address of the AP to which the WiFi client is attempting to connect Format: six hex bytes separated by colons (“:”). |
username | The name of the user provided by the splash page to the AP on redirect. |
password | The sequence of hexadecimal characters requiring decryption. |
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=6E13364322A961F17AFF1B8DF7E8577C38F6C63C19281DF2D1FBAAECDC845A70995A56B65C753D6F15E150A31D43832ELogin response parameters
| parameter name | parameter 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 name | parameter value |
|---|---|
type | Type must be set to “acct” |
ra | The Request Authenticator generated by the AP. |
session | A unique string identifying the session. This ID shall be used during all subsequent requests within the same session. |
mac | The MAC address of the WiFi client. Format: six hex bytes separated by colons (“:”). |
node | The primary MAC address of the Access Point which issued this request. Format: six hex bytes separated by colons (“:”). |
download | The number of bytes downloaded by the WiFi client since the last accounting update. |
upload | The 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 name | parameter value |
|---|---|
"CODE" | The response is “OK”. |
"RA" | The updated Request Authenticator sent to AP to confirm validity of the response. |
"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 name | parameter value |
|---|---|
type | Type must be set to “logout”. |
ra | The Request Authenticator generated by the AP. |
session | A unique string identifying the session. This ID shall be used during all subsequent requests within the same session. |
mac | The MAC address of the WiFi client. Format: six hex bytes separated by colons (“:”). |
node | The primary MAC address of the Access Point which issued this request. Format: six hex bytes separated by colons (“:”). |
download | The number of bytes downloaded by the WiFi client since the last accounting update. |
upload | The 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 name | parameter value |
|---|---|
"CODE" | The response is “OK”. |
"RA" | The updated Request Authenticator sent to AP to confirm validity of the response. |
"CODE" "OK"
"RA" "3aabead5afd7eaaeae41b48fb9f62fed"