RADIUS-based Authentication
The following documentation is aimed at splash page services that want to use the RADIUS protocol for captive portal authentication, a more advanced and very established protocol compared to the HTTP-based authentication protocol.
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 RADIUS requests.
Next, you need to specify RADIUS as type of authentication service via the Provisioning API. Make sure to also configure the RADIUS server URL with secret and port for authentication. Please note that you can provide up to two sets of server information (i.e., a primary and a secondary server).
After covering these key steps, let’s take a look at the RADIUS functions in detail.
RADIUS Protocol Requests
The RADIUS protocol comprises three types of requests:
- Pre-Login;
- Login;
- Accounting;
- Logout.
With an active captive portal, a user needs to pass a splash page based authentication to connect to a network. Basically, the user attempting to connect gets intercepted by the Access Point and is then redirected to the splash page. Here, one or more authentication steps are required. After completion, the WiFi client is redirected back to the Access Point.
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 Attributes
| Attribute | Value |
|---|---|
Service-Type | Set to “Login”. |
User-name | Authentication username. If the username is not available, the client MAC address will be sent instead. Format: six hex bytes separated by hyphen (“-”). |
User-Password | The Ethernet MAC address of the WiFi client. Format: six hex bytes separated by hyphen (“-”). |
Calling-Station-Id | The Ethernet MAC address of the WiFi client. Format: six hex bytes separated by hyphen (“-”). |
Called-Station-Id | The primary MAC address of the AP to which the WiFi client is attempting to connect to. Format: six hex bytes separated by hyphen (“-”). |
NAS-Identifier | The unique string classifying SSIDs in different groups, allowing the RADIUS server to send a customized authentication response. |
Pre-Login Response Attributes
The RADIUS authentication server can respond to a Pre-Login Request either with an Access-Accept packet or an Access-Reject packet.
The Access-Accept packet signals the AP to grant network access to the WiFi client. It includes the following attribute value pairs:
| Attribute | Value |
|---|---|
WISPr_Bandwidth-Max-UP | The maximum throughput from the WiFi client to the AP in bits per second (optional). |
WISPr_Bandwidth-Max-DOWN | The maximum throughput from the AP to the WiFi client in bits per second (optional). |
Session-Timeout | The number of seconds the session remains valid for. |
Acct-Interim-Interval | The number of seconds between RADIUS accounting updates (default: 300) |
On the other hand, the Access-Reject packet signals the AP to deny network access to the WiFi client.
Login
The Access Point initiates the login process 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 allowed to use the network, or rejecting the login with an optional message indicating the reason. In case of authentication success, the Access Point grants network access to the WiFi client and redirects it to the service landing page, if configured, or to the URL the user originally requested.
The following attributes will be exchanged:
Login Request Attributes
| Attribute | Value |
|---|---|
Service-Type | Set to “Login”. |
User-name | The name of the user provided by the splash page to the AP on redirect. |
User-Password | The encrypted password of the user provided by the splash page to the AP on redirect. |
Calling-Station-Id | The Ethernet MAC address of the WiFi client. Format: six hex bytes separated by hyphen (“-”). |
Called-Station-Id | The primary MAC address of the AP to which the WiFi client is attempting to connect to. Format: six hex bytes separated by hyphen (“-”). |
NAS-Identifier | The unique string classifying SSIDs in different groups, allowing the RADIUS server to send a customized authentication response. |
Login Response Attributes
The RADIUS authentication server can respond to a Login Request either with an Access-Accept packet or an Access-Reject packet.
The Access-Accept packet signals the AP to grant network access to the WiFi client. It includes the following attribute value pairs:
| Attribute | Value |
|---|---|
WISPr_Bandwidth-Max-UP | The maximum throughput from the WiFi client to the AP in bits per second (optional). |
WISPr_Bandwidth-Max-DOWN | The maximum throughput from the AP to the WiFi client in bits per second (optional). |
Session-Timeout | The number of seconds the session remains valid for. |
Acct-Interim-Interval | The number of seconds between RADIUS accounting updates (default: 300) |
On the other hand, the Access-Reject packet signals the AP to deny network access to the WiFi client.
Accounting
Accounting requests are used to deliver information from the Access Point to the authentication server about the status of an ongoing session. It includes data such as a user’s current bandwidth usage.
The following attributes will be exchanged:
Accounting Request Attributes
| Attribute | Value |
|---|---|
Acct-Status-Type | After “Access-Accept” is returned by the authentication server, the captive portal on the AP will send this attribute in all subsequent accounting requests. The value can either be “Start”, “Interim-Update” or “Stop”. The first accounting update will be sent immediately from the service provider to the accounting server after successful login, and contains the value “Start”. For all following accounting updates, the value is set to “Interim-Update”, except for the final update which is set to “Stop” to signal the session logout. |
User-Name | Authentication username. If the client username is not available, the client MAC address will be sent instead. Format: six hex bytes separated by hyphen (“-”). |
Framed-IP-Address | The client IP address. |
Acct-Session-Id | The unique string identifying the session. This ID shall be used during all requests within the same session. |
Calling-Station-Id | The Ethernet MAC address of the WiFi client. Format: six hex bytes separated by hyphen (“-”). |
Called-Station-Id | The primary MAC address of the Access Point which issued the request. Format: six hex bytes separated by hyphen (“-”). |
Acct-Session-Time | The number of seconds this session has been active for. |
Acct-Input-Octets | The number of bytes uploaded by the WiFi client since the last accounting update. |
Acct-Input-Gigawords | This attribute is an extension of the Acct-Input-Octets field. Every time the number contained in Acct-Input-Octets reaches 2^32 (the highest number that can be represented in 4 bytes), the value of this attribute is increased by 1. |
Acct-Output-Octets | The number of bytes downloaded by the WiFi client since the last accounting update. |
Acct-Output-Gigawords | This attribute is an extension of the Acct-Output-Octets field. Every time the number contained in Acct-Output-Octets reaches 2^32 (the highest number that can be represented in 4 bytes), the value of this attribute is increased by 1. |
When the accounting server acknowledges the incoming request, an accounting response packet is sent back to the Access Point.
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 expiration or manual user logout and contains the final accounting information.
The following parameters will be exchanged:
Logout Request Attributes
| Attribute | Value |
|---|---|
User-name | Authentication user name. If the user name is not available, the client MAC address will be sent instead. Format: six hex bytes separated by hyphen (“-”). |
Acct-Status-Type | The final accounting update with Acct-Status-Type set to “Stop” to signal session logout. |
Acct-Session-Id | The unique string identifying the session. This ID shall be used during all the requests within the same session. |
Framed-IP-Address | The client IP address. |
Calling-Station-Id | The Ethernet MAC address of the WiFi client. Format: six hex bytes separated by hyphen (“-”). |
Called-Station-Id | The primary MAC address of the Access Point which issued the request. Format: six hex bytes separated by hyphen (“-”). |
Acct-Session-Time | The number of seconds this session has been active for. |
Acct-Input-Octets | The number of bytes uploaded by the WiFi client since the last accounting update. |
Acct-Input-Gigawords | This attribute is an extension of the Acct-Input-Octets field. Every time the number contained in Acct-Input-Octets reaches 2^32 (the highest number that can be represented in 4 bytes), the value of this attribute is increased by 1. |
Acct-Output-Octets | The number of bytes downloaded by the WiFi client since the last accounting update. |
Acct-Output-Gigawords | This attribute is an extension of the Acct-Output-Octets field. Every time the number contained in Acct-Output-Octets reaches 2^32 (the highest number that can be represented in 4 bytes), the value of this attribute is increased by 1. |
When the accounting server acknowledges the incoming request, a logout response packet is sent back to the authentication server.