[feature] Added support for simultaneous-use #615

Closes #615

---------

Co-authored-by: Federico Capoano <f.capoano@openwisp.io>

Author: pandafy

docs/images/idle-timeout-radius-reply.png

@@ -39,6 +39,7 @@ OpenWISP architecture.
     user/social_login.rst
     user/saml.rst
     user/enforcing_limits.rst
+    user/simultaneous_use.rst
     user/change_of_authorization.rst
     user/radius_monitoring
     user/management_commands.rst

docs/images/simultaneous-use-radius-check.png

@@ -411,6 +411,20 @@ authorize the request with other freeradius modules.
 Set this to ``True`` if you are performing authorization exclusively
 through the REST API.
 
+.. _openwisp_radius_simultaneous_use_enabled:
+
+``OPENWISP_RADIUS_SIMULTANEOUS_USE_ENABLED``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Default**: ``True``
+
+Allows disabling the :doc:`Simultaneous-Use <simultaneous_use>` feature,
+e.g.:
+
+.. code-block:: python
+
+    OPENWISP_RADIUS_SIMULTANEOUS_USE_ENABLED = False
+
 ``OPENWISP_RADIUS_API_ACCOUNTING_AUTO_GROUP``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/index.rst

@@ -0,0 +1,71 @@
+Limiting concurrent sessions (``Simultaneous-Use``)
+===================================================
+
+``Simultaneous-Use`` is a FreeRADIUS feature that restricts how many
+sessions a user can keep active at the same time. When the maximum limit
+is reached and the user attempts to start another session from a different
+client device, the authorization is rejected with the following RADIUS
+reply message:
+
+.. code-block:: text
+
+    You are already logged in - access denied
+
+FreeRADIUS can enforce this check through its ``sql`` module, but that's
+not multi-tenant aware: this can cause issues when a user belongs to
+multiple organizations with different session limits, potentially
+resulting in wrong limits being applied.
+
+To address this, OpenWISP RADIUS provides a multi-tenant aware
+``Simultaneous-Use`` check in its authorization REST API endpoint.
+
+Configuring Simultaneous-Use Check
+----------------------------------
+
+Add the ``Simultaneous-Use`` RADIUS check to the desired RADIUS group by
+following these steps:
+
+1. In the admin interface, navigate to **RADIUS** in the left-hand menu.
+2. Go to **Groups**.
+3. Select the group you want to configure.
+4. In the **GROUP CHECKS** section, click on **Add another Group check**.
+5. Fill in the fields as follows:
+
+   - **Attribute**: ``Simultaneous-Use``
+   - **Operator**: ``:=``
+   - **Value**: ``1`` (or any number greater than 0; `1` limits users to
+     one concurrent session)
+
+   .. image:: ../images/simultaneous-use-radius-check.png
+       :alt: Example of setting Idle-Timeout to 240
+
+.. important::
+
+    When using Simultaneous-Use, it is recommended to add an
+    ``Idle-Timeout`` RADIUS reply to the same RADIUS group, with a low
+    value (below 300 seconds). This ensures inactive sessions are cleared
+    quickly, preventing users from being blocked due to stale sessions.
+
+6. For the same radius group, in the **GROUP REPLIES** section, click on
+   **Add another Group reply**.
+7. Fill in the fields as follows:
+
+   - **Attribute**: ``Idle-Timeout``
+   - **Operator**: ``=``
+   - **Value**: ``240``
+
+   .. image:: ../images/idle-timeout-radius-reply.png
+       :alt: Example of setting Idle-Timeout to 240
+
+8. Click on **Save and continue editing** at the bottom of the page.
+
+Disabling the ``Simultaneous-Use`` check
+----------------------------------------
+
+The ``Simultaneous-Use`` feature is **enabled by default**.
+
+It can be disabled with the :ref:`OPENWISP_RADIUS_SIMULTANEOUS_USE_ENABLED
+<openwisp_radius_simultaneous_use_enabled>` setting.
+
+This is useful if you already rely on another FreeRADIUS module to enforce
+``Simultaneous-Use`` and do not need the OpenWISP implementation.

docs/user/settings.rst

@@ -302,41 +302,83 @@ def get_replies(self, user, organization_id):
 
             group_checks = get_group_checks(user_group.group)
 
-            for Counter in app_settings.COUNTERS:
-                group_check = group_checks.get(Counter.check_name)
-                if not group_check:
-                    continue
-                try:
-                    counter = Counter(
-                        user=user, group=user_group.group, group_check=group_check
-                    )
-                    remaining = counter.check()
-                except SkipCheck:
-                    continue
-                # if max is reached send access rejected + reply message
-                except MaxQuotaReached as max_quota:
-                    data.update(self.reject_attributes.copy())
-                    if "Reply-Message" not in data:
-                        data["Reply-Message"] = max_quota.reply_message
-                    return data, self.max_quota_status
-                # avoid crashing on unexpected runtime errors
-                except Exception as e:
-                    logger.exception(f'Got exception "{e}" while executing {counter}')
-                    continue
-                if remaining is None:
-                    continue
-                reply_name = counter.reply_name
-                # send remaining value in RADIUS reply, if needed.
-                # This emulates the implementation of sqlcounter in freeradius
-                # which sends the reply message only if the value is smaller
-                # than what was defined to a previous reply message
-                if reply_name not in data or remaining < self._get_reply_value(
-                    data, counter
-                ):
-                    data[reply_name] = remaining
+            # Validate simultaneous use
+            simultaneous_use = self._check_simultaneous_use(
+                data, user, group_checks, organization_id
+            )
+            if simultaneous_use is not None:
+                return simultaneous_use
+
+            # Execute counter checks
+            counter_result = self._check_counters(
+                data, user, user_group.group, group_checks
+            )
+            if counter_result is not None:
+                return counter_result
 
         return data, self.accept_status
 
+    def _check_simultaneous_use(self, data, user, group_checks, organization_id):
+        """
+        Check if user has exceeded simultaneous use limit
+
+        Returns rejection response if limit is exceeded
+        """
+        if (check := group_checks.get("Simultaneous-Use")) is None or (
+            max_simultaneous := int(check.value)
+        ) <= 0:
+            # Exit early if the `Simultaneous-Use` check is not defined
+            # in the RadiusGroup or if it permits unlimited concurrent sessions.
+            return None
+        open_sessions = RadiusAccounting.objects.filter(
+            username=user.username,
+            organization_id=organization_id,
+            stop_time__isnull=True,
+        ).count()
+        if open_sessions >= max_simultaneous:
+            data.update(self.reject_attributes.copy())
+            if "Reply-Message" not in data:
+                data["Reply-Message"] = "You are already logged in - access denied"
+            return data, self.reject_status
+
+    def _check_counters(self, data, user, group, group_checks):
+        """
+        Execute counter checks and return rejection response if any quota is exceeded
+        Returns None if all checks pass
+        """
+        for Counter in app_settings.COUNTERS:
+            group_check = group_checks.get(Counter.check_name)
+            if not group_check:
+                continue
+            try:
+                counter = Counter(user=user, group=group, group_check=group_check)
+                remaining = counter.check()
+            except SkipCheck:
+                continue
+            # if max is reached send access rejected + reply message
+            except MaxQuotaReached as max_quota:
+                data.update(self.reject_attributes.copy())
+                if "Reply-Message" not in data:
+                    data["Reply-Message"] = max_quota.reply_message
+                return data, self.max_quota_status
+            # avoid crashing on unexpected runtime errors
+            except Exception as e:
+                logger.exception(f'Got exception "{e}" while executing {counter}')
+                continue
+            if remaining is None:
+                continue
+            reply_name = counter.reply_name
+            # send remaining value in RADIUS reply, if needed.
+            # This emulates the implementation of sqlcounter in freeradius
+            # which sends the reply message only if the value is smaller
+            # than what was defined to a previous reply message
+            if reply_name not in data or remaining < self._get_reply_value(
+                data, counter
+            ):
+                data[reply_name] = remaining
+
+        return None
+
     @staticmethod
     def _get_reply_value(data, counter):
         value = data[counter.reply_name]["value"]

docs/user/simultaneous_use.rst

@@ -328,7 +328,7 @@ def to_representation(self, obj):
         user_group = get_user_group(obj, organization.pk)
         if not user_group:
             raise Http404
-        group_checks = get_group_checks(user_group.group).values()
+        group_checks = get_group_checks(user_group.group, counters_only=True).values()
         checks_data = UserGroupCheckSerializer(
             group_checks, many=True, context={"user": obj, "group": user_group.group}
         ).data

openwisp_radius/api/freeradius_views.py

@@ -113,6 +113,7 @@ def get_default_password_reset_url(urls):
         "location": "disabled",
     },
 )
+SIMULTANEOUS_USE_ENABLED = get_settings_value("SIMULTANEOUS_USE_ENABLED", True)
 
 try:  # pragma: no cover
     assert PASSWORD_RESET_URLS

openwisp_radius/api/serializers.py

@@ -1069,6 +1069,7 @@ def test_user_radius_usage_view(self):
             self.assertEqual(response.status_code, 200)
             self.assertIn("checks", response.data)
             checks = response.data["checks"]
+            self.assertEqual(len(checks), 2)
             self.assertDictEqual(
                 dict(checks[0]),
                 {

openwisp_radius/settings.py

@@ -30,6 +30,8 @@
 RadiusAccounting = load_model("RadiusAccounting")
 RadiusPostAuth = load_model("RadiusPostAuth")
 RadiusGroupReply = load_model("RadiusGroupReply")
+RadiusGroupCheck = load_model("RadiusGroupCheck")
+RadiusGroup = load_model("RadiusGroup")
 RegisteredUser = load_model("RegisteredUser")
 OrganizationRadiusSettings = load_model("OrganizationRadiusSettings")
 Organization = swapper.load_model("openwisp_users", "Organization")
@@ -1344,7 +1346,7 @@ def test_authorize_counters_reply_interaction(self):
 
         with self.subTest("Counters disabled"):
             with mock.patch.object(app_settings, "COUNTERS", []):
-                with self.assertNumQueries(6):
+                with self.assertNumQueries(7):
                     response = self._authorize_user(auth_header=self.auth_header)
                 self.assertEqual(response.status_code, 200)
                 expected = {
@@ -1437,6 +1439,139 @@ def test_authorize_counters_exception_handling(self):
                 self.assertEqual(response.status_code, 200)
                 self.assertEqual(response.data, truncated_accept_response)
 
+    @mock.patch.object(app_settings, "SIMULTANEOUS_USE_ENABLED", True)
+    def test_authorize_simultaneous_use(self):
+        user = self._get_org_user().user
+        group = user.radiususergroup_set.first().group
+        self._create_radius_groupreply(
+            group=group,
+            groupname=group.name,
+            attribute="Idle-Timeout",
+            op="=",
+            value="240",
+        )
+        org2 = self._create_org(name="org2")
+        self._create_org_user(organization=org2, user=user)
+
+        with self.subTest("Authorization within simultaneous use limit"):
+            simultaneous_use_check = self._create_radius_groupcheck(
+                group=group,
+                groupname=group.name,
+                attribute="Simultaneous-Use",
+                op=":=",
+                value="2",
+            )
+
+            # Create one open session (within limit of 2)
+            acct_data = self.acct_post_data
+            acct_data.update(
+                {
+                    "username": user.username,
+                    "unique_id": "test_session_1",
+                    "stop_time": None,
+                }
+            )
+            self._create_radius_accounting(**acct_data)
+
+            # Authorization should succeed
+            response = self._authorize_user(auth_header=self.auth_header)
+            self.assertEqual(response.status_code, 200)
+            self.assertEqual(response.data["control:Auth-Type"], "Accept")
+
+        with self.subTest("Authorization exceeding simultaneous use limit"):
+            RadiusGroupCheck.objects.filter(id=simultaneous_use_check.id).update(
+                value="1"
+            )
+
+            # Already have one open session (at the limit of 1)
+            response = self._authorize_user(auth_header=self.auth_header)
+            self.assertEqual(response.status_code, 401)
+            self.assertEqual(response.data["control:Auth-Type"], "Reject")
+            self.assertEqual(
+                response.data["Reply-Message"],
+                "You are already logged in - access denied",
+            )
+            self.assertEqual(
+                response.data["Idle-Timeout"],
+                {"op": "=", "value": "240"},
+            )
+
+        with self.subTest("Closed sessions are ignored"):
+            # Keep limit at 1 and Close all previously open sessions
+            RadiusAccounting.objects.filter(stop_time=None).update(
+                stop_time="2025-08-12T23:00:24.020460+01:00"
+            )
+
+            # Authorization should succeed (closed sessions don't count)
+            response = self._authorize_user(auth_header=self.auth_header)
+            self.assertEqual(response.status_code, 200)
+            self.assertEqual(response.data["control:Auth-Type"], "Accept")
+
+        with self.subTest("Open session in different org is ignored"):
+            # Keep limit at 1 and create an open session for the user in org2
+            self._create_radius_accounting(
+                **{
+                    **self.acct_post_data,
+                    "username": user.username,
+                    "unique_id": "test_session_org2",
+                    "stop_time": None,
+                    "organization": org2,
+                }
+            )
+
+            # Authorization should succeed (session in different org doesn't count)
+            response = self._authorize_user(auth_header=self.auth_header)
+            self.assertEqual(response.status_code, 200)
+            self.assertEqual(response.data["control:Auth-Type"], "Accept")
+
+        with self.subTest("Zero limit allows unlimited simultaneous sessions"):
+            RadiusGroupCheck.objects.filter(id=simultaneous_use_check.id).update(
+                value="0"
+            )
+
+            # Create multiple open sessions
+            acct_data.update(
+                {
+                    "username": user.username,
+                    "stop_time": None,
+                    "session_time": 1,
+                    "input_octets": 0,
+                    "output_octets": 0,
+                }
+            )
+            for i in range(2, 4):  # Create 2 more sessions (total 3)
+                acct_data["unique_id"] = f"test_session_{i}"
+                self._create_radius_accounting(**acct_data)
+
+            # Authorization should still succeed with unlimited sessions
+            response = self._authorize_user(auth_header=self.auth_header)
+            self.assertEqual(response.status_code, 200)
+            self.assertEqual(response.data["control:Auth-Type"], "Accept")
+
+    @mock.patch.object(app_settings, "SIMULTANEOUS_USE_ENABLED", False)
+    @mock.patch("openwisp_radius.api.freeradius_views.RadiusAccounting.objects.count")
+    def test_authorize_simultaneous_use_disabled_in_settings(self, mocked_count):
+        user = self._get_org_user().user
+        group = user.radiususergroup_set.first().group
+        self._create_radius_groupcheck(
+            group=group,
+            groupname=group.name,
+            attribute="Simultaneous-Use",
+            op=":=",
+            value="1",
+        )
+
+        # Create an open session that would normally exceed limit
+        acct_data = self.acct_post_data
+        acct_data.update({"username": user.username, "stop_time": None})  # Open session
+        self._create_radius_accounting(**acct_data)
+
+        # Authorization should succeed (check is disabled)
+        response = self._authorize_user(auth_header=self.auth_header)
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.data["control:Auth-Type"], "Accept")
+        mocked_count.assert_not_called()
+
     def test_authorize_radius_token_200(self):
         self._get_org_user()
         rad_token = self._login_and_obtain_auth_token()