======= Hotspot ======= .. sidebar:: Contents .. contents:: :depth: 3 :local: 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). .. image:: hotspot_topology.svg :alt: HotSpot gateway solution with captive portal authentication :width: 700px :align: center 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*: 1. 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. 2. 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: .. csv-table:: :align: left :header: 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: 1. 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. 2. 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: .. csv-table:: :align: left :header: 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: .. code-block:: none http[s]://?param1=value1¶m2=value2¶m3=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: .. code-block:: none 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: .. image:: uam_server.png :alt: HotSpot GW solution with UAM Server authentication :align: center The steps are described below. 1. 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. 2. 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. 3. The captive portal page is presented to the client. 4. 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. 5. 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. 6. After successful authentication, the subscriber session switches to authorized status and the client is redirected by HTTP to the proper URL. 7. 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: 1. 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. 2. 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: 1. 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. 2. URL configured through the ``redirection success-page`` command. 3. 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: 1. URL configured through the ``redirection fail-page`` command. 2. 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: .. code-block:: none http[s]://:[]/login?param1=value1¶m2=value2&... Where ``param`` are the credentials and ``value`` 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: .. code-block:: none param1=value1¶m2=value2&... The following table lists predefined parameters the UAM server can process: .. csv-table:: :align: left :header: 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: .. code-block:: none 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: 1. 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. 2. 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: .. code-block:: text 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. 3. 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: .. code-block:: text 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. :doc:`Here <../../system/aaa/index>` 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: .. csv-table:: :align: left :header: 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: .. csv-table:: :align: left :header: 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: .. code-block:: none set service hotspot Where ```` 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. .. image:: hotspot_example.svg :alt: HotSpot simple scenario :width: 700px :align: center 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``: .. code-block:: none 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. .. code-block:: none 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``. .. code-block:: none 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: .. code-block:: none 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``. .. code-block:: none 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. .. code-block:: none 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. Command Summary =============== .. osdx:cmdtree:: cfg :maxdepth: 8 service hotspot .. osdx:cmdtree:: op :maxdepth: 5 service hotspot