RADIUS-based Authentication

How Can We Help?

RADIUS-based Authentication

You are here:

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:

  1. Pre-Login;
  2. Login;
  3. Accounting;
  4. 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
AttributeValue
Service-TypeSet to “Login”.
User-nameAuthentication username. If the username is not available, the client MAC address will be sent instead.
Format: six hex bytes separated by hyphen (“-”).
User-PasswordThe Ethernet MAC address of the WiFi client.
Format: six hex bytes separated by hyphen (“-”).
Calling-Station-IdThe Ethernet MAC address of the WiFi client.
Format: six hex bytes separated by hyphen (“-”).
Called-Station-IdThe primary MAC address of the AP to which the WiFi client is attempting to connect to.
Format: six hex bytes separated by hyphen (“-”).
NAS-IdentifierThe unique string classifying SSIDs in different groups, allowing the RADIUS server to send a customized authentication response.
NAS-Port-TypeNAS-Port-Type is sent to provide details about the client connection type:
15: Ethernet Client
19: Wireless Client
NAS-PortIf NAS-Port-Type is set Wireless (19), Nas-Port carries the SSID ID.
If NAS-Port-Type is set Ethernet (15), Nas-Port carries the Ethernet port ID.
NAS-Port-IDIf NAS-Port-Type is set Wireless (19), Nas-Port-Id carries the WiFi band as string.
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:

AttributeValue
User-nameThe authentication username. Overrides splash page username in client report to Console (optional).
WISPr_Bandwidth-Max-UPThe maximum throughput from the WiFi client to the AP in bits per second (optional).
WISPr_Bandwidth-Max-DOWNThe maximum throughput from the AP to the WiFi client in bits per second (optional).
Session-TimeoutThe number of seconds the session remains valid for.
Idle-TimeoutThe number of seconds after which the session is ended should the client be inactive.
Acct-Interim-IntervalThe 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
AttributeValue
Service-TypeSet to “Login”.
User-nameThe name of the user provided by the splash page to the AP on redirect.
User-PasswordThe encrypted password of the user provided by the splash page to the AP on redirect.
Calling-Station-IdThe Ethernet MAC address of the WiFi client.
Format: six hex bytes separated by hyphen (“-”).
Called-Station-IdThe primary MAC address of the AP to which the WiFi client is attempting to connect to.
Format: six hex bytes separated by hyphen (“-”).
NAS-IdentifierThe unique string classifying SSIDs in different groups, allowing the RADIUS server to send a customized authentication response.
NAS-Port-TypeNAS-Port-Type is sent to provide details about the client connection type:
15: Ethernet Client
19: Wireless Client
NAS-PortIf NAS-Port-Type is set Wireless (19), Nas-Port carries the SSID ID.
If NAS-Port-Type is set Ethernet (15), Nas-Port carries the Ethernet port ID.
NAS-Port-IDIf NAS-Port-Type is set Wireless (19), Nas-Port-Id carries the WiFi band as string.

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:

AttributeValue
User-nameThe authentication username. Overrides splash page username in client report to Console (optional).
WISPr_Bandwidth-Max-UPThe maximum throughput from the WiFi client to the AP in bits per second (optional).
WISPr_Bandwidth-Max-DOWNThe maximum throughput from the AP to the WiFi client in bits per second (optional).
Session-TimeoutThe number of seconds the session remains valid for.
Idle-TimeoutThe number of seconds after which the session is ended should the client be inactive.
Acct-Interim-IntervalThe 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
AttributeValue
Acct-Status-TypeAfter “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-NameAuthentication 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-IdThe unique string identifying the session. This ID shall be used during all requests within the same session.
Format: MAC address + SSID ID + Client counter
Calling-Station-IdThe Ethernet MAC address of the WiFi client.
Format: six hex bytes separated by hyphen (“-”).
Called-Station-IdThe primary MAC address of the Access Point which issued the request.
Format: six hex bytes separated by hyphen (“-”).
Acct-Session-TimeThe number of seconds this session has been active for.
Acct-Input-OctetsThe number of bytes uploaded by the WiFi client since the last accounting update.
Acct-Input-GigawordsThis 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-GigawordsThis 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.
NAS-Port-TypeNAS-Port-Type is sent to provide details about the client connection type:
15: Ethernet Client
19: Wireless Client
NAS-PortIf NAS-Port-Type is set Wireless (19), Nas-Port carries the SSID ID.
If NAS-Port-Type is set Ethernet (15), Nas-Port carries the Ethernet port ID.
NAS-Port-IDIf NAS-Port-Type is set Wireless (19), Nas-Port-Id carries the WiFi band as string.

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
AttributeValue
User-nameAuthentication 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-TypeThe final accounting update with Acct-Status-Type set to “Stop” to signal session logout.
Acct-Session-IdThe unique string identifying the session. This ID shall be used during all the requests within the same session.
Format: MAC address + SSID ID + Client counter
Framed-IP-Address The client IP address.
Calling-Station-IdThe Ethernet MAC address of the WiFi client.
Format: six hex bytes separated by hyphen (“-”).
Called-Station-IdThe primary MAC address of the Access Point which issued the request.
Format: six hex bytes separated by hyphen (“-”).
Acct-Session-TimeThe number of seconds this session has been active for.
Acct-Input-OctetsThe number of bytes uploaded by the WiFi client since the last accounting update.
Acct-Input-GigawordsThis 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-GigawordsThis 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.
Acct-Terminate-CauseAcct-Terminate-Cause field is added on session end to provide details about the cause. It contains one of the following values:
USER_REQUEST: user initiated log out
LOST_CARRIER: WiFi / Ethernet disconnect
ACCT_IDLE_TIMEOUT: idle timeout
ACCT_SESSION_TIMEOUT: session timeout

When the accounting server acknowledges the incoming request, a logout response packet is sent back to the Access Point.

Table of Contents