Hotspot

In a network, a HotSpot gateway is an element that provides Internet access and other services, typically over wireless technologies, to occasional client devices during a specific period of time.

Intelligent client management may be required when offering additional services, such as establishing user-based session privileges, client statistics accounting, or service agreement requests.

Typical services deployed by a HotSpot gateway require user information, which cannot be received through the communications link or network layers. Thus, specific mechanisms are implemented to gather this essential information. Captive portals are generally used to obtain said information (credentials) from network clients.

A captive portal is a web browser-based tool used to force a client to present user credentials before network access is granted. Since this tool operates at the application layer, the HotSpot has to facilitate appropriate methods for a successful connection at lower layers.

As soon as the HotSpot gateway obtains user credentials, Authentication, Authorization and Accounting (AAA) services can be used to manage clients. As a result, session context maintenance and the implementation of required protocols are often needed to interact with AAA servers.

The HotSpot feature aims to provide a set of functions that help integrate tasks reviewed by a HotSpot gateway. This document explains how to implement a HotSpot gateway solution using the HotSpot feature. Functions provided by the HotSpot feature are detailed, together with their configuration and monitoring aspects.

Proprietary solution 

Our solution provides a HotSpot gateway that is ready to interact with a captive portal and AAA servers running in external locations. This means the captive portal can be located wherever commercial solutions for captive portals can be tested (even online).

Main characteristics and services:

Redirecting HTTP traffic to an external captive portal.
Interoperability with AAA protocols.
Client session management: uplink/downlink bandwidth limits, maximum credits for uplink/downlink bytes, monitoring of client statistics and periodic session accounting.
Definition of a authorized list containing MAC addresses that grant network access to clients without requesting user credentials.
Definition of traffic policies to control client access to web content and services.

Solution restrictions:

Every captive portal uses a different format to specify user credentials over HTTP sessions. This lack of homogeneity implies the captive portal must be compatible with our manner of gathering information.
Web server containing the captive portal and the AAA servers, which are located in external sites

Subscriber sessions 

A subscriber is defined as a physical device that must be authorized to access the network through a HotSpot gateway way. Every subscriber has a HotSpot session characterized by its MAC address.

A subscriber session is initially created in unauthorized status. That means traffic coming from this device is classified as non-accepted in the HotSpot, and traffic policies are applied for that type of traffic. To change the session status to authorized, a process of authentication and authorization of the subscriber must be carried out using a method based on a captive portal. When a session status switches to authorized, every packet from the subscriber defined is classified as accepted and no traffic policies are applied to it.

A authorized mac list is made up of MAC addresses belonging to subscribers whose packets are classified as accepted in the HotSpot, regardless of the session status. Therefore, access policies and restrictions defined for non-accepted packets are not applied to them.

A common method to classify the IP packets as accepted is the walled garden. The walled garden is a set of criteria, being usually well known hosts, defined at IP or an upper level that must be applied to a traffic policy. Packets that match these criteria are automatically classified as accepted, even if the subscriber session is unauthorized.

Note

In OSDX, a walled garden is defined by mean of a traffic selector which must be assigned to the traffic policy used be hotspot service.

There are two ways in which policies are applied to packets classified as non-accepted:

If it is an HTTP packet, once the defined traffic policy is processed, it is intercepted and redirected to the embedded HTTP server. This way, the router supplants the original destination and responds with an HTTP message that redirects the subscriber to the captive portal URL.

If it is not an HTTP packet, it is discarded.

A client is defined as a source of IP traffic (a source IP address). This means a subscriber could have one or more IP clients in the HotSpot database. When a session associated to a MAC address is authorized, all traffic sent by IP clients from said MAC address is classified as accepted.

A session switches from authorized to unauthorized if any of the following events occurs:

Session lifetime is exceeded.
The traffic quota allowed (received or transmitted) is exceeded.
An explicit request from the subscriber is dealt with.

Every authorized session has a set of attributes whose value can be assigned from the defaults configured in the HotSpot feature, or that can be sent for that specific session by an AAA server. Any value received in an AAA message takes preference over the one configured in the HotSpot. The attributes defined for a subscriber session are the following:

Attribute

Type

Default value

Description

Session timeout

mandatory

3600

Time (seconds) a session remains in authorized status

Uplink bandwidth limit

optional

Bitrate (kbps) limit when it comes to receiving IP traffic from a subscriber in authorized status

Downlink bandwidth limit

optional

Bitrate (kbps) limit for transmitting IP traffic to a subscriber in authorized status

Uplink maximum bytes

optional

Maximum number of bytes the HotSpot can receive from a subscriber in authorized status

Downlink maximum bytes

optional

Maximum number of bytes the HotSpot can transmit to a subscriber in authorized status

Accounting interim interval

optional

Time interval (in seconds) to send periodic accounting records of sessions in authorized status

User URL

optional

Destination URL to which a subscriber must be redirected if the authentication is succesful

Redirecting HTTP traffic to the Captive Portal 

Received HTTP traffic classified as non-accepted is intercepted by the HotSpot and a traffic proxy redirects it to the an embedded HTTP server located in the router. This server builds an HTTP response, redirecting the subscriber’s HTTP client to the URL of the captive portal. The embedded server is called the Universal Authentication Method (UAM) server and is described further on.

In this HTTP redirection, the new destination URL is built by adding a set of parameters to the configured portal URL. These are used to provide information about the client and the router to the captive portal. In the router, the URL portal value can be set in two different ways, with the following priority order:

URL set in the specific attribute used for this matter in this subscriber session. The value of this attribute can be received in the response from an AAA server.

URL configured through the redirection captive-portal url command.

In the second case, when the HotSpot redirects to the URL configured by the portal-page command, the following parameters are added to build the URL:

Attribute

Description

uamip

IP address in which the UAM server is listening

uamport

TCP port in which the UAM server is listening

challenge

Temporal challenge generated for the client used in CHAP authentication

called

MAC address used to identify the router

mac

MAC address of the subscriber device

ip

IP address of the client

userurl

Original URL requested by the client

status

Session status represented by a integer value 1 (authorized) or 0 (unauthorized)

md

Message digest if uam-server authentication ciphered-secret is configured

The URL portal value received from an AAA server is built only by adding parameters userurl, challenge, md, and all the configured optionals.

Finally, the URL syntax is as follows:

http[s]://<portal-page>?param1=value1&param2=value2&param3=value3...

String parameter values (e.g., userurl) are added to the encoded URL.

Example of URL built when the value configured by the portal-page command is used:

http://any-domain.com/index.html?uamip=192.168.1.1&uamport=4532&called=00:00:5E:00:53:00&mac=00:00:5E:00:53:01&ip=192.168.1.15&userurl=www.teldat.com&status=0

All these parameters can be parsed and used by the captive portal to generate customized web pages for a given client, update roaming databases, dynamically create users in AAA servers, etc.

The UAM Server 

The Universal Authentication Method or UAM is a browser-based login method where a client provides user credentials through HTTP requests. Authentication is then carried out at the network and transport layers. In our proprietary solution, a captive portal mechanism is implemented for this task. Wireless ISP Roaming 2.0 (WISPr 2.0) specifications, published by the Wireless Broadband Alliance (WBA), include a Universal Authentication Method, widely taken as reference, to implement login protocols using captive portals. Our solution is based on the WISPr 2.0 recommendations described in said document.

The UAM server is an embedded HTTP server located in the router. It is in charge of receiving HTTP messages from clients and performing some kind of action over their subscriber sessions (authenticate, de-authenticate, …). By enabling HTTP redirection in the HotSpot feature, non-accepted HTTP traffic is received by the internal UAM server. The latter builds an HTTP response, redirecting the client to a captive portal page.

The following diagram shows a basic sequence of events for user authentication:

The steps are described below.

A client starts a web browser and requests an arbitrary URL. A subscriber session is created in the HotSpot for the client in unauthorized status.

The HotSpot intercepts the HTTP request, classifying it as non-accepted traffic. The UAM server receives the request and redirects the client to the portal page.

The captive portal page is presented to the client.

Some communication between the captive portal and the client takes place. Eventually, an HTTP request from the client must be sent to the UAM server for user credentials submission.

The HotSpot sends an access request to the AAA server using said credentials. The AAA server then responds with an accept/reject message, which might include session attributes.

After successful authentication, the subscriber session switches to authorized status and the client is redirected by HTTP to the proper URL.

Any other traffic will be forwarded by the gateway while the session is in authorized status.

HTTP messages received by the UAM Server 

HTTP messages received from clients can be handled in two different ways:

HTTP requests for an arbitrary URL, originally destined to some remote HTTP server, may be intercepted by the HotSpot feature and redirected to the UAM server by means of a traffic proxy.

HTTP requests can be directly destined to the UAM server to make a query or perform some change over the subscriber session.

Changes in the subscriber session linked to HTTP requests directly destined to the UAM server are defined by the URL path. The syntax of the URL must be one of the following:

URLs that trigger an authentication process: login, logon.
URLs that trigger an deauthentication process: logout, logoff.
URLs that request information on the subscriber session: status.
Special URLs whose authentication is compatible with others captive portal: auth?action=login

After an authentication process, and depending on its result, a HTTP message redirects the client to an URL page. If the authentication is successful, the HTTP response redirects the client to an URL page according to the following priority order:

Value set in the userurl attribute of the subscriber session. This attribute can be received in the HTTP request, together with the user credentials or in a response from an AAA server.

URL configured through the redirection success-page command.

Original URL requested by the client and remembered by the router.

If the authentication process fails, the HTTP response redirects the client to an URL page according to the following priority order:

URL configured through the redirection fail-page command.
Captive portal URL.

Receiving user credentials through HTTP requests 

To obtain the user credential, the client must send an HTTP message to the UAM server requesting one of the described URLs used to trigger an authentication process. This HTTP message contains a set of parameters where credentials are specified.

In this HTTP request, the method used must be of type GET or POST. If the method is GET, the parameters with credentials must be added to the URL following a URL query format:

http[s]://<uamip>:[<uamport>]/login?param1=value1&param2=value2&...

Where param<n> are the credentials and value<n> are their respective values.

If the HTTP method is POST, the fields with credentials must be included in the body of the HTTP message as indicated here:

param1=value1&param2=value2&...

The following table lists predefined parameters the UAM server can process:

Parameter

Description

username or user

User name used to perform authentication with the AAA server

password or pass

User password used to perform authentication with the AAA server

userurl

URL used to redirect the user if the authentication succeeds

action

Trigger a login action based on the value

Example on how to submit credentials using an URL query string format:

http://192.0.2.42:4532/login?username=name&password=pass

The username (or user) parameter is mandatory in this HTTP message. Additionally, the message must include a parameter that specifies the password (password or pass) for this user.

User authentication using the UAM Server 

The HotSpot feature provides different mechanisms for user authentication. By enabling the Challenge-Handshake Authentication Protocol (CHAP) in the UAM server, the HotSpot generates a 16 bytes random challenge for every subscriber. This challenge is sent in the initial redirect response to the client that is able to start a CHAP authentication process. Additionally, a shared secret between the UAM server and the captive portal can be used to encrypt the user password. Said secret should never be sent to the network.

The authentication process consists of three phases:

A client with an unauthorized session tries to request some arbitrary URL, and the UAM server responds with an HTTP redirect to the captive portal. If CHAP authentication is enabled in the UAM server, a challenge for that subscriber is generated, valid for 10 minutes. This challenge is included in the HTTP response which redirects to the portal.
Eventually, the client must send a HTTP request to the UAM server to supply the required username and password (ciphered or not). This password must be added with one of the following parameter identifiers: password or pass.

Performing a PAP is up to the administrator. The following pseudo-code shows how to calculate the password before supplying it to the UAM server, according to the authentication type desired:
if "CHALLENGE" available
  if "SECRET" configured
    newchallenge = MD5(CHALLENGE, SECRET)
  else
    newchallenge = CHALLENGE
  endif

  if "PAP" desired
    password = XOR(PASSWORD, newchallenge)
    SEND_LOGIN(user, password)
  endif
else
  password = PASSWORD
  SEND_LOGIN(user, password)
end if
When CHALLENGE and SECRET are both known by the portal and the UAM server, password and newchallenge are calculated. PASSWORD depends on the type of value entered by the user on the login form.
In the HTTP request received by the UAM server, if the password is supplied using the password or pass parameters, an authentication process of type PAP is triggered.

The following pseudo-code shows how the UAM server calculates the RADIUS attributes used to perform the authentication on the AAA server:
if "CHALLENGE" available
  if "SECRET" configured
    newchallenge = MD5(CHALLENGE, SECRET)
  else
    newchallenge = CHALLENGE
  endif

  if "password" received
    aaa-password = XOR(password, newchallenge)
    SEND_RADIUS_PAP_REQUEST(user, aaa-password)
  endif
else
  aaa-password = password
  SEND_RADIUS_PAP_REQUEST(user, aaa-password)
endif
When CHALLENGE and SECRET are both known by the portal and the UAM server and password are received in the HTTP request and newchallenge, aaa-password are calculated.

AAA services 

The HotSpot feature uses Radius to implement Authentication, Authorization and Accounting services. Therefore, a Radius client must be properly configured in the equipment. A Radius client can also be configured by enabling the AAA feature. Here you can find more information about AAA configuration.

Authentication and Authorization 

To authenticate and authorize a subscriber session, the Radius client must send an Access-Request to a Radius server. The Radius attributes included in the Access-Request depend on the type of authentication configured. In case of OSDX, it’s based on the user and password submitted by the subscriber.

The attributes included in a RADIUS Access-Request are the following:

Attribute

Description

User-Name

User name submitted by the subscriber

User-Password

Password submitted by the subscriber

Service-Type

Text value defined in the IETF RFC 2865

Calling-Station-Id

Subscriber device MAC address

Called-Station-Id

Network interface MAC address where the HotSpot is configured

Framed-Ip-Address

Client IP address

Accounting 

Subscriber session accounting means enabling the AAA feature. Accounting records can be sent at the beginning and the end of a session and, optionally, in periodic intervals, provided the interim-interval parameter was pre-configured. Standard attributes for Radius accounting are defined in IETF RFC 2865 and IETF RFC 2866.

The list of attributes included in an accounting record is as follows:

Attribute

Description

User-Name

User name submitted by the subscriber

Acct-Status-Type

Type of accounting record: START STOP or INTERIM

Acct-Input-Octets

Number of bytes received from a subscriber

Acct-Output-Octets

Number of bytes transmitted to a subscriber

Framed-Ip-Address

Client IP address

Calling-Station-Id

Subscriber device MAC address

Called-Station-Id

Network interface MAC address where the HotSpot is configured.

Configuration 

The hotspot service is configured at the following path:

set service hotspot <ID>

Where <ID> is the name of the instance that the configured parameters apply to. This allows configuring more than a single Hotspot in the device if necessary.

A valid hotspot configuration requires all mandatory parameters to be filled out on the device. This includes:

A aaa authentication list which contains the information required to talk with the radius server.
The downstream-interfaces which defines where the subscribers are located on the network at interface level.
The redirection captive-portal url required to redirect the HTTP traffic of the non-authenticated subscribers.
The traffic policy name that contains the exceptions to forward packets of the non-authenticated subscribers.
The uam-server address which defines the IP address of the UAM server.

Note that some of these configurations paths, like aaa authentication list and traffic policy, are references to other configuration paths that must be present on the device.

Set up 

The following image shows a common type of deployment.

There are some peculiarities that are relevant for the configuration:

Subscribers obtains the address by mean of the DHCP protocol.
Both the AAA radius server and the captive portal are defined by mean of a fqdn. This means that the DNS traffic must be allowed to resolve the domains but also that the traffic policy must use names instead IPs for filtering since they may change.

First, define the allowed services by mean of a traffic selector:

set traffic selector ALLOWED-SERVICES rule 1 description 'DHCP traffic'
set traffic selector ALLOWED-SERVICES rule 1 destination port 67
set traffic selector ALLOWED-SERVICES rule 1 protocol udp
set traffic selector ALLOWED-SERVICES rule 1 source port 68
set traffic selector ALLOWED-SERVICES rule 2 description 'DNS traffic'
set traffic selector ALLOWED-SERVICES rule 2 destination port 53
set traffic selector ALLOWED-SERVICES rule 2 protocol tcp,udp

Similarly, the walled garden or the list of authorized hosts reachable by non authorized subscribers, must be defined. As fqdn must be used for filtering, it’s necessary to use the app-detect feature.

set system conntrack app-detect dictionary 1 custom app-id 33 fqdn 'any-domain.com$'
set system conntrack app-detect dns
set system conntrack app-detect dns-host

set traffic selector WALLED-GARDEN rule 1 app-id custom 33

Use both traffic selectors to match the traffic in the traffic policy.

set traffic policy HOTSPOT-POLICY rule 1 action accept
set traffic policy HOTSPOT-POLICY rule 1 selector ALLOWED-SERVICES
set traffic policy HOTSPOT-POLICY rule 2 action accept
set traffic policy HOTSPOT-POLICY rule 2 selector WALLED-GARDEN

Additionally, AAA configuration must be defined:

set system aaa group radius RADIUS_GROUP server RADIUS_SERVER
set system aaa list RADIUS_LIST method 1 group radius RADIUS_GROUP
set system aaa server radius RADIUS_SERVER address aaa.any-domain.com
set system aaa server radius RADIUS_SERVER key aaa_secret_password

Finally, define the service configuration using the just created HOTSPOT-POLICY and RADIUS_LIST.

set service hotspot HOTSPOT aaa authentication list RADIUS_LIST
set service hotspot HOTSPOT downstream-interfaces br0
set service hotspot HOTSPOT redirection captive-portal url 'https://any-domain.com'
set service hotspot HOTSPOT traffic policy HOTSPOT-POLICY
set service hotspot HOTSPOT uam-server address 192.168.150.1
set service hotspot HOTSPOT uam-server authentication chap
set service hotspot HOTSPOT uam-server authentication plaintext-secret secret_password

If everything is correct, the device should accept the configuration and the hotspot service will block any traffic, not defined in the traffic policy, of non-authenticated subscribers.

Monitoring 

The following operational command can be used to list information of the current sessions.

admin@osdx# run service hotspot HOTSPOT show sessions

---------------------------------------------------------------------
       MAC          IPv4 address       Status         Expires on
---------------------------------------------------------------------
00:00:5E:00:53:01  192.168.150.152  authorized    2025-03-07 15:38:33
00:00:5E:00:53:02  192.168.150.153  unauthorized  2025-03-07 14:48:40

Sessions can be filtered out by status using the status {authorized}|{unauthorized} argument.