======= Hotspot ======= .. sidebar:: Contents .. contents:: :depth: 3 :local: In a network, a HotSpot gateway is an element that provides, typically over wireless technologies, Internet access and other services to occasional client devices during a specific period of time. Smart 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 crucial information. Captive portals are generally used to obtain data (credentials) from network clients. A **captive portal** is a web browser-based tool that forces clients to enter 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 section 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 an 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 is authorized to access the network through a HotSpot gateway. 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*, the subscriber must be authenticated and authorized carried using a captive portal-based method. 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. An **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, 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 means of a **traffic selector** assigned to the traffic policy used by the hotspot service. Policies are applied to packets classified as *non-accepted* in two ways: 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*, the 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 derive 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 an *authorized* subscriber Downlink bandwidth limit, optional, , Bitrate (kbps) limit when transmitting IP traffic to an *authorized* subscriber Uplink maximum bytes, optional, , Maximum number of bytes the HotSpot can receive from an *authorized* subscriber Downlink maximum bytes, optional, , Maximum number of bytes the HotSpot can transmit to an *authorized* subscriber Accounting interim interval, optional, , Time interval (in seconds) to send periodic session accounting records in *authorized* status User URL, optional, , Destination URL to which a subscriber must be redirected if 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 an embedded HTTP server located in the router. This server builds an HTTP response, redirecting the subscriber's HTTP client to the captive portal's URL. The embedded server is called **Universal Authentication Method (UAM)** and is described further on. In this HTTP redirection, the new destination URL is built by adding a set of parameters to the URL of the configured portal. These are used to give the captive portal information on the client and the router. 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 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 solely by adding parameters ``userurl``, ``challenge``, ``md``, and all the configured options. Finally, the URL syntax looks 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 used 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 the submission of user credentials. 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 de-authentication process: ``logout``, ``logoff``. * URLs that request information on the subscriber session: ``status``. * Special URLs whose authentication is compatible with other captive portals: ``auth?action=login`` After an authentication process, and depending on its result, an 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 GET or POST. If the method is GET, the parameters with credentials must be added to the URL following an 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 below: .. 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``, Username 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 authentication is successful ``action``, Triggers 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-byte 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 random 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 (valid for 10 minutes) is generated. This challenge is included in the HTTP response which redirects to the portal. 2. Eventually, the client must send an HTTP request to the UAM server to provide 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 passing it on to the UAM server in accordance with 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, a ``PAP`` authentication process is triggered. The following pseudo-code shows how the UAM server calculates the RADIUS attributes used to perform 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, ``newchallenge`` and ``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 device. 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. When it comes to OSDX, it is 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``, Username 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``, MAC address of the network interface 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 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 to which the configured parameters apply. This means that more than a single Hotspot can be configured in the device if necessary. A valid hotspot configuration requires all mandatory parameters to be filled out on the device. This includes: * An ``aaa authentication list``, which contains the information required to talk with the radius server. * The ``downstream-interfaces``, which define the network location of subscribers at interface level. * The ``redirection captive-portal url`` required to redirect the HTTP traffic of non-authenticated subscribers. * The ``traffic policy`` name containing exceptions to forward packets belonging to non-authenticated subscribers. * The ``uam-server address``, which defines the IP address of the UAM server. Note that some of these configuration 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 deployment. .. image:: hotspot_example.svg :alt: HotSpot simple scenario :width: 700px :align: center There are some peculiarities that are relevant when it comes to the configuration: * Subscribers obtain the address by means of the DHCP protocol. * Both the *AAA radius server* and the *captive portal* are defined by means of a fqdn. This means that the DNS traffic may resolve *domains*, but also that the *traffic policy* must use names instead of IPs for filtering purposes (since they may change). First, define the services allowed by means 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. Since *fqdn* is used for filtering, the ``app-detect`` feature must be used. .. 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-detect 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 newly created ``HOTSPOT-POLICY`` and ``RADIUS_LIST`` commands. .. 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* belonging to non-authenticated subscribers. Monitoring ========== The following operational command can be used to list information on 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