[docs] Explain basic concepts in detail #380

Closes #380

docs/index.rst

@@ -14,8 +14,7 @@ For a full introduction please refer to :doc:`user/intro`.
     :maxdepth: 1
 
     user/intro.rst
-    user/organization-permissions.rst
-    user/organization-owners.rst
+    user/basic-concepts.rst
     user/management-commands.rst
     user/settings.rst
     user/rest-api.rst

docs/user/basic-concepts.rst

@@ -0,0 +1,237 @@
+Basic Concepts
+==============
+
+.. contents::
+    :depth: 2
+    :local:
+
+Superusers
+----------
+
+.. image:: https://github.com/openwisp/openwisp-users/raw/docs/docs/images/superuser.png
+    :target: https://github.com/openwisp/openwisp-users/raw/docs/docs/images/superuser.png
+    :alt: Superuser status flag
+
+A superuser, also known as a "super administrator," is a special type of admin user
+account with full access to all aspects of an OpenWISP instance.
+
+The **Superuser status** flag in the user details page indicates whether a user is a
+superuser or not. Only superusers are allowed to edit this flag.
+
+Superusers have all permissions enabled by default and can create, manage and delete any
+organization available in the system.
+
+However, it's essential to use superuser accounts sparingly due to their elevated
+privileges.
+
+To grant access to specific features and organizations within your OpenWISP system,
+consider creating staff users without the "superuser status" flag enabled. Assign them
+to one of the available permission groups, as explained in the following sections. These
+users will have limited administrative capabilities, managing only the objects permitted
+by their assigned permissions and associated organization.
+
+Staff Users
+-----------
+
+Users with the **Staff status** flag enabled, as shown in the screenshot above, have
+access to the OpenWISP Admin interface. This access allows them to manage various
+aspects of the OpenWISP instance according to their assigned permissions and
+organizational role.
+
+Users with this flag disabled will still be able to interact with OpenWISP, but in a
+more limited way. They can use non-administrative user interfaces or specific REST API
+HTTP endpoints designed for end-users.
+
+.. note::
+
+    An example of an end-user is someone who signs up for a public WiFi hotspot service
+    via the :doc:`WiFi Login Pages </user/wifi-login-pages>` module. This optional
+    OpenWISP module is commonly used in public WiFi hotspot deployments.
+
+Permissions
+-----------
+
+The permission system used by OpenWISP is based on the `Django Permission System
+<https://docs.djangoproject.com/en/4.2/topics/auth/default/#permissions-and-authorization>`_.
+
+In short, a permission indicates whether a user has the authority to perform the
+following operations:
+
+- **View**: Access the details of a specific class of objects, e.g., view the details of
+  users.
+- **Add**: Create a new object of a specific class, e.g., add a new user.
+- **Change**: Edit the details of a specific class, e.g., modify existing user details.
+- **Delete**: Remove an object of a specific class, e.g., delete users.
+
+.. note::
+
+    For more detailed technical information, please refer to the `Django Documentation
+    <https://docs.djangoproject.com/en/4.2/topics/auth/default/>`_.
+
+.. _default_permission_groups:
+
+Default Permission Groups
+-------------------------
+
+.. image:: https://github.com/openwisp/openwisp-users/raw/docs/docs/images/permission-groups.png
+    :target: https://github.com/openwisp/openwisp-users/raw/docs/docs/images/permission-groups.png
+    :alt: Default Permission Groups of OpenWISP
+
+A permission group is a collection of permissions that can be assigned to multiple
+users.
+
+It is then possible to change the permissions on the group to reflect the changes on all
+the users who are part of the permission group.
+
+This allows to avoid having to assign permissions to individual users, which is hard to
+maintain and leads to inconsistent permission configuration over time.
+
+OpenWISP provides a few permission groups which are explained below.
+
+Administrator
+~~~~~~~~~~~~~
+
+This permission group is designed for users who need to manage most aspects of an
+organization without having superuser access.
+
+Operator
+~~~~~~~~
+
+This permission group is designed for users who need to be able to perform a limited
+amount of operations like provisioning new devices and perform regular network
+maintenance operations but are not allowed to create new users or change the permissions
+settings of other users.
+
+Use this for users who have very specific and limited responsibilities in the network.
+
+Organizations & Multi-Tenancy
+-----------------------------
+
+The concept of multi-tenancy in OpenWISP is implemented through "organizations".
+
+An organization in OpenWISP represents a distinct entity or tenant within the system.
+Each organization has its own set of users, configurations, data, and administrative
+controls, allowing for isolation and management of network resources.
+
+Key Features of Organizations:
+
+- **Isolation & Privacy**: Organizations provide a logical separation of resources,
+  ensuring that data and configurations are segregated between different entities or
+  tenants. Each tenant can only see and interact with the data of their organizations
+  and :ref:`shared objects` defined by super administrators.
+- **User Management**: Each organization can have its own set of users with specific
+  roles and permissions tailored to their responsibilities within that organization.
+- **Administrative Controls**: Super administrators can define, oversee, and manage
+  :ref:`shared objects`, permission policies, and any other processes relating to
+  organizations to ensure consistency across the entire system.
+
+By leveraging organizations, OpenWISP provides a robust framework for implementing
+multi-tenancy, allowing for the efficient management of network resources across diverse
+entities or tenants within a single instance of the platform.
+
+.. note::
+
+    Multi-Tenancy and Organizations are implemented in OpenWISP with the
+    `django-organizations <https://github.com/bennylope/django-organizations>`_
+    third-party app.
+
+Organization Membership and Roles
+---------------------------------
+
+A user can be associated to one or multiple organizations and have different roles in
+each.
+
+Here's a summary of the default organization roles.
+
+Organization Manager
+~~~~~~~~~~~~~~~~~~~~
+
+.. image:: https://github.com/openwisp/openwisp-users/raw/docs/docs/images/org-manager.png
+    :target: https://github.com/openwisp/openwisp-users/raw/docs/docs/images/org-manager.png
+    :alt: Organization Manager
+
+Any user with the "Is admin" flag enabled for a specific organization (as shown in the
+screenshot above) is considered by the system a manager of that organization.
+Organization managers have the authority to view and interact with the data belonging to
+that organization according to their set of permissions (as defined in :ref:`Permission
+Groups <default_permission_groups>`).
+
+To modify this flag, navigate to the "ORGANIZATION USERS" section on the "Change user"
+page.
+
+Organization Members (End-Users)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: https://github.com/openwisp/openwisp-users/raw/docs/docs/images/org-member.png
+    :target: https://github.com/openwisp/openwisp-users/raw/docs/docs/images/org-member.png
+    :alt: Organization Member
+
+Any user with the "Is admin" flag disabled for a specific organization (as shown in the
+screenshot above) is considered by the system a regular end-user of that organization.
+
+These users are consumers of a service provided by the organization. They will not be
+able to see or interact with any object of that organization via the administrative
+interface, even if they are flagged as Staff users.
+
+They can only consume REST API endpoints or other non administrative user interface
+pages.
+
+A real-world example of this is the `User API endpoints of OpenWISP RADIUS
+<https://openwisp-radius.readthedocs.io/en/stable/user/api.html#user-api-endpoints>`_,
+which allow users to sign up to an organization, verify their phone number by receiving
+a verification code via SMS, see their RADIUS sessions, etc. All those endpoints are
+tied to an organization because different organizations can have very different
+configurations. Users are allowed to consume those endpoints only if they're members.
+
+Organization Owners
+~~~~~~~~~~~~~~~~~~~
+
+An organization owner is a user designated as the owner of a particular organization.
+This owner cannot be deleted or edited by other administrators; only superusers have
+permission to perform these actions.
+
+By default, the first manager of an organization is designated as the owner of that
+organization.
+
+Only superusers and organization owners are allowed to change the owner of an
+organization. Organization owners can be changed from the "Change organization" page by
+navigating to the "ORGANIZATION OWNER" section.
+
+If the ``OrganizationUser`` instance related to the owner of an organization is deleted
+or flagged as ``is_admin=False``, the admin interface will return an error informing
+users that the operation is not allowed. The owner should be changed before attempting
+to perform such actions.
+
+.. _shared_objects:
+
+Shared Objects
+--------------
+
+.. image:: https://github.com/openwisp/openwisp-users/raw/docs/docs/images/shared-object.png
+    :target: https://github.com/openwisp/openwisp-users/raw/docs/docs/images/shared-object.png
+    :alt: Shared Object
+
+A shared object is a resource that can be used by multiple organizations or tenants
+within the system.
+
+Shared objects do not belong to any specific organization. In the user interface, the
+organization field is empty, and it displays *"Shared systemwide (no organization)"* as
+shown in the screenshot above. These objects are defined and managed by super
+administrators and can include configurations, policies, or other data that need to be
+consistent across all organizations.
+
+By sharing common resources, global uniformity and consistency can be enforced across
+the entire system.
+
+.. note::
+
+    Only a specific subset of object classes can be shared. You can determine if an
+    object can be shared by attempting to create a new object for that class while
+    logged in as a superuser. If the organization field shows the option *"Shared
+    systemwide (no organization)"*, it means the object can be shared.
+
+Examples of shared objects include:
+
+- Shared Configuration Templates
+- Shared VPN servers
+- Shared Subnets

docs/user/intro.rst

@@ -1,2 +1,70 @@
 Users: Structure & Features
 ===========================
+
+The OpenWISP Users module leverages the capabilities of the `Django Framework
+<https://djangoproject.com/>`_ and its rich ecosystem to provide OpenWISP with features
+for managing user accounts, permission groups, supporting different authentication
+schemes, and implementing multi-tenancy. This allows multiple organizations to be
+managed by different users within a single OpenWISP instance, among other
+functionalities.
+
+Below is a summary of the key features available.
+
+User Management
+---------------
+
+- Create, read, update, and delete user accounts.
+- Support for custom user fields through extensible models (see
+  :doc:`../developer/extending` for more information).
+- :ref:`Export user data <export_users>` through a management command (from the Linux
+  shell).
+
+Multi-tenancy
+-------------
+
+- Create multiple organizations (also commonly referred to as tenants).
+- Users can be associated with one or multiple organizations as members, managers, or
+  owners.
+- Each organization can access only their data.
+- Shared data: some objects can be shared among multiple organizations.
+
+See :doc:`basic-concepts` for more information.
+
+Permissions and Roles
+---------------------
+
+- Granular permission control for users and organizations.
+- Default roles for administrators, managers, and regular users.
+- Customizable permission sets for specific needs.
+
+See :doc:`basic-concepts` for more information.
+
+API Integration
+---------------
+
+- RESTful API endpoints for user and organization management.
+- Secure API access with token-based authentication.
+
+See :doc:`rest-api` for more information.
+
+Admin Interface
+---------------
+
+- User-friendly Django admin interface.
+- Customizable admin views for user and organization management (see
+  :doc:`../developer/extending` for more information).
+
+Extensible Authentication
+-------------------------
+
+With some additional work, it is possible to leverage the rich ecosystem of Django third
+party apps to implement the following:
+
+- Possibility to log in in the admin interface via authentication schemes like OAuth,
+  SAML, MS Azure Authentication, etc.
+- Support multi-factor authentication (MFA).
+
+On a similar note, the `OpenWISP RADIUS <https://openwisp-radius.readthedocs.io/>`_
+module ships logic that allows end-users to log into WiFi services using OAuth (eg:
+social login provided by Google, Facebook) or SAML (eg: `EIDAS <https://www.eid.as/>`_,
+`SPID <https://www.spid.gov.it/en/>`_).