network mode

CHANGES.rst

@@ -11,7 +11,9 @@ Changes
 
 Features / Changes
 ~~~~~~~~~~~~~~~~~~~~~
-* n/a
+* Introduce "Network Mode" which allows other Magpie instances to act as external authentication providers using JSON
+  Web Tokens (JWT). This allows users registered across multiple Magpie instances in a network to more easily gain
+  access to the resources within the network, without requiring the duplication of user credentials across the network.
 
 Bug Fixes
 ~~~~~~~~~~~~~~~~~~~~~

config/magpie.ini

@@ -28,6 +28,10 @@ pyramid.includes =
 magpie.port = 2001
 magpie.url = http://localhost:2001
 
+# Enable network mode which allows different instances of Magpie to authenticate users for each other.
+# magpie.network_mode = true
+# magpie.default_token_expiry = 86400
+
 # magpie.config_path =
 
 # --- cookie definition --- (defaults below if omitted)

docs/authentication.rst

@@ -422,3 +422,84 @@ Furthermore, as described in the `procedure`_, :envvar:`MAGPIE_USER_REGISTRATION
 specify whether administrator approval is required or not. This additional step is purely up to the developers and
 server managers that use `Magpie` to decide if they desire more control over which individuals can join and access
 their services.
+
+.. _Network Mode:
+
+Network Mode
+------------
+
+If the :envvar:`MAGPIE_NETWORK_MODE` is enabled, an additional external authentication provider is added to Magpie which
+allows networked instances of Magpie to authenticate users for each other.
+
+Users can then log in to any Magpie instance where they have an account and request a personal network token in the form
+of a `_JSON Web Token <https://datatracker.ietf.org/doc/html/rfc7519>`_ which can be used to authenticate this user on
+any Magpie instance in the network.
+
+Managing the Network
+~~~~~~~~~~~~~~~~~~~~
+
+In order for Magpie instances to authenticate each other's users, each instance must be made aware of the existence of
+the others so that it knows where to send authentication verification requests.
+
+In order to register another Magpie instance as part of the same network, an admin user can create a
+:term:`Network Node` with a request to ``POST /network-nodes``. The parameters given to that request include a ``name``
+and a ``url``. The ``name`` is a the name of that other Magpie instance in the network and should correspond to the
+same value as the :envvar:`MAGPIE_INSTANCE_NAME` value set by the other Magpie instance. The ``url`` is a the root URL
+of the other Magpie instance.
+
+Once a :term:`Network Node` is registered, Magpie can use that other instance to authenticate users as long as the other
+instance also has :envvar:`MAGPIE_NETWORK_MODE` enabled.
+
+Managing Personal JWTs
+~~~~~~~~~~~~~~~~~~~~~~
+
+A :term:`User` can request a new network token with a request to the ``PATCH /token`` route. This route takes one
+optional parameter ``expires`` which is an integer indicating how long (in seconds) until that token expires, the
+default expiry for this token is :envvar:`MAGPIE_DEFAULT_TOKEN_EXPIRY`.
+
+Every time a :term:`User` makes a request to the ``PATCH /token`` route a new token is generated for them. This
+effectively cancels all previously created tokens for that user. If a user wishes to cancel all tokens, they can provide
+an ``expires`` value of ``0`` when making the request.
+
+Authentication
+~~~~~~~~~~~~~~
+
+Once a :term:`User` gets a personal network token, they can use that token to authenticate with any Magpie instance in
+the same network. When a user makes a request, they should set the ``provider_name`` parameter to the value of
+:envvar:`MAGPIE_NETWORK_PROVIDER` and provide the network token in the Authorization header in the following format:
+
+.. code-block:: http
+
+    Authorization: Bearer <network_token>
+
+When using the :ref:`Magpie Adapter <utilities_adapter>`, the token can also be passed as a parameter to the request,
+where the parameter name set by :envvar:`MAGPIE_NETWORK_TOKEN_NAME` and the value is the personal network token.
+
+Authorization
+~~~~~~~~~~~~~
+
+Managing authorization for :term:`Users` who authenticate using personal network tokens is complicated by the fact that
+a :term:`User` is not required to have a full account on both Magpie instances in order to using this authentication
+mechanism. This means that a :term:`User` may be logged in as a node-specific "anonymous" user.
+
+When another Magpie instance is registered as a :term:`Network Node`, a few additional entities are created:
+
+#. a group used to manage the permissions of all users who authenticate using the new :term:`Network Node`.
+   * this group's name will be the :envvar:`MAGPIE_NETWORK_NAME_PREFIX` followed by the :term:`Network Node` name
+#. a group used to manage the permissions of all users who authenticate using *any* other instance in the network
+   * this group's name will be the :envvar:`MAGPIE_NETWORK_GROUP_NAME`
+   * this group will only be created once, when the first :term:`Network Node` is registered
+#. an anonymous user that belongs to the two groups that were just created.
+   * this user name will be the :envvar:`MAGPIE_NETWORK_NAME_PREFIX` followed by the :term:`Network Node` name
+
+Here is an example to illustrate this point:
+
+* There are 3 Magpie instances in the network named A, B, and C
+* There is a :term:`User` named ``"toto"`` registered on instance A
+* There is no :term:`User` named ``"toto"`` who belongs to the ``"anonymous_network_A"`` group registered on instance B
+* There is a :term:`User` named ``"toto"`` who belongs to the ``"anonymous_network_A"`` group registered on instance C
+* Instance A is registered as a :term:`Network Node` on instances B and C
+* when ``"toto"`` gets a personal network token from instance A and uses it to log in on instance B they log in as the
+  the temporary ``"anonymous_network_A"`` user.
+* when ``"toto"`` gets a personal network token from instance A and uses it to log in on instance C they log in as the
+  ``"toto"`` user on instance C.

docs/configuration.rst

@@ -969,6 +969,83 @@ remain available as described at the start of the :ref:`Configuration` section.
     Name of the :term:`Provider` used for login. This represents the identifier that is set to define how to
     differentiate between a local sign-in procedure and a dispatched one some known :ref:`authn_providers`.
 
+Network Mode Settings
+~~~~~~~~~~~~~~~~~~~~~
+
+The following configuration parameters are related to Magpie's "Network Mode" which allows networked instances of Magpie
+to authenticate users for each other. All variables defined in this section are only used if
+:envvar:`MAGPIE_NETWORK_MODE` is enabled.
+
+.. envvar:: MAGPIE_NETWORK_MODE
+
+    [:class:`bool`]
+    (Default: ``False``)
+
+    .. versionadded:: 3.37
+
+    Enable "Network Mode" which enables all functionality to authenticate users using other Magpie instances as
+    external authentication providers.
+
+.. envvar:: MAGPIE_INSTANCE_NAME
+
+    [:class:`str`]
+
+    .. versionadded:: 3.37
+
+    The name of this Magpie instance in the network. This variable is used to determine if an authentication token was
+    issued by this instance of Magpie, or another instance in the network.
+
+    This variable is required if :envvar:`MAGPIE_NETWORK_MODE` is ``True``.
+
+.. envvar:: MAGPIE_DEFAULT_TOKEN_EXPIRY
+
+    [:class:`int`]
+    (Default: ``86400``)
+
+    .. versionadded:: 3.37
+
+    The default expiry time (in seconds) for an authentication token issued for the purpose of network authentication.
+
+.. envvar:: MAGPIE_NETWORK_TOKEN_NAME
+
+    [|constant|_]
+    (Value: ``"magpie_token"``)
+
+    .. versionadded:: 3.37
+
+    The name of the request parameter key whose value is the authentication token issued for the purpose of network
+    authentication.
+
+.. envvar:: MAGPIE_NETWORK_PROVIDER
+
+    [|constant|_]
+    (Value: ``"magpie_network"``)
+
+    .. versionadded:: 3.37
+
+    The name of the external provider that authenticates users using other Magpie instances as external authentication
+    providers.
+
+.. envvar:: MAGPIE_NETWORK_NAME_PREFIX
+
+    [|constant|_]
+    (Value: ``"anonymous_network_"``)
+
+    .. versionadded:: 3.37
+
+    A prefix added to the anonymous network user and network group names. These names are constructed by prepending the
+    remote Magpie instance name with this prefix. For example, a Magpie instance named ``"example123"`` will have a
+    corresponding user and group named ``"anonymous_network_example123"``.
+
+.. envvar:: MAGPIE_NETWORK_GROUP_NAME
+
+    [|constant|_]
+    (Value: ``"magpie_network"``)
+
+    .. versionadded:: 3.37
+
+    The name of the group created to manage permissions for all users authenticated using Magpie instances as external
+    authentication providers.
 
 .. _config_phoenix:
 

docs/glossary.rst

@@ -138,6 +138,16 @@ Glossary
         :py:data:`magpie.constants.MAGPIE_ANONYMOUS_USER`. Otherwise, it is whoever the
         :term:`Authentication` mechanism identifies with token extracted from request :term:`Cookies`.
 
+    Network Node
+        A reference to an instance of the Magpie software within a network of Magpie instances. Each Magpie instance
+        within the network is registered in the database as a row in the ``network_nodes`` table. Each node is
+        represented by a name that is unique across all nodes in the network, and a url that is used to send http
+        requests to that specific node.
+
+    Network Token
+        A unique random string that can be used to authenticate a user as part of the :ref:`Network Mode` authentication
+        procedure.
+
     OpenAPI
     OAS
         The |OpenAPI-spec|_ (`OAS`) defines a standard, programming language-agnostic interface description for

magpie/adapter/magpieowssecurity.py

@@ -269,11 +269,18 @@ def update_request_cookies(self, request):
         """
         settings = get_settings(request)
         token_name = get_constant("MAGPIE_COOKIE_NAME", settings_container=settings)
+        network_mode = get_constant("MAGPIE_NETWORK_MODE", settings_container=settings,
+                                    settings_name="magpie.network_mode")
+        headers = dict(request.headers)
+        network_token_name = get_constant("MAGPIE_NETWORK_TOKEN_NAME", settings_container=settings)
+        if network_mode and "Authorization" not in headers and network_token_name in request.params:
+            headers["Authorization"] = "Bearer {}".format(request.params[network_token_name])
+            request.params["provider_name"] = request.params.get("provider_name",
+                                                                 get_constant("MAGPIE_NETWORK_PROVIDER", settings))
         if "Authorization" in request.headers and token_name not in request.cookies:
             magpie_prov = request.params.get("provider_name", get_constant("MAGPIE_DEFAULT_PROVIDER", settings))
             magpie_path = ProviderSigninAPI.path.format(provider_name=magpie_prov)
             magpie_auth = "{}{}".format(self.magpie_url, magpie_path)
-            headers = dict(request.headers)
             headers.update({"Homepage-Route": "/session", "Accept": CONTENT_TYPE_JSON})
             session_resp = requests.get(magpie_auth, headers=headers, verify=self.twitcher_ssl_verify)
             if session_resp.status_code != HTTPOk.code:

magpie/alembic/versions/2023-08-25_2cfe144538e8_add_network_tables.py

@@ -0,0 +1,54 @@
+"""
+Add Network_Tokens Table
+
+Revision ID: 2cfe144538e8
+Revises: 5e5acc33adce
+Create Date: 2023-08-25 13:36:16.930374
+"""
+import uuid
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm.session import sessionmaker
+from sqlalchemy_utils import URLType
+
+# Revision identifiers, used by Alembic.
+# pylint: disable=C0103,invalid-name  # revision control variables not uppercase
+revision = "2cfe144538e8"
+down_revision = "5e5acc33adce"
+branch_labels = None
+depends_on = None
+
+Session = sessionmaker()
+
+
+def upgrade():
+    op.create_table("network_tokens",
+                    sa.Column("token", UUID(as_uuid=True),
+                              primary_key=True, default=uuid.uuid4, unique=True),
+                    sa.Column("user_id", sa.Integer,
+                              sa.ForeignKey("users.id", onupdate="CASCADE", ondelete="CASCADE"), unique=True)
+                    )
+    op.create_table("network_nodes",
+                    sa.Column("id", sa.Integer, primary_key=True, autoincrement=True),
+                    sa.Column("name", sa.Unicode(128), nullable=False, unique=True),
+                    sa.Column("url", URLType(), nullable=False)
+                    )
+    op.add_column("users", sa.Column("network_node_id", sa.Integer,
+                                     sa.ForeignKey("network_nodes.id", onupdate="CASCADE", ondelete="CASCADE"),
+                                     nullable=True))
+    op.drop_constraint("uq_users_user_name", "users")
+    op.create_unique_constraint("uq_users_user_name_network_node_id", "users", ["user_name", "network_node_id"])
+    op.drop_constraint("uq_users_email", "users")
+    op.create_unique_constraint("uq_users_email_network_node_id", "users", ["email", "network_node_id"])
+
+
+def downgrade():
+    op.drop_constraint("uq_users_user_name_network_node_id", "users")
+    op.create_unique_constraint("uq_users_user_name", "users", ["user_name"])
+    op.drop_constraint("uq_users_email_network_node_id", "users")
+    op.create_unique_constraint("uq_users_email", "users", ["email"])
+    op.drop_table("network_tokens")
+    op.drop_table("network_nodes")
+    op.drop_column("users", "network_node_id")

magpie/api/exception.py

@@ -85,6 +85,7 @@ def verify_param(  # noqa: E126  # pylint: disable=R0913,too-many-arguments
                  is_equal=False,                    # type: bool
                  is_type=False,                     # type: bool
                  matches=False,                     # type: bool
+                 not_matches=False,                 # type: bool
                  ):                                 # type: (...) -> None   # noqa: E123,E126
     # pylint: disable=R0912,R0914
     """
@@ -123,12 +124,13 @@ def verify_param(  # noqa: E126  # pylint: disable=R0913,too-many-arguments
     :param is_equal: test that :paramref:`param` equals :paramref:`param_compare` value
     :param is_type: test that :paramref:`param` is of same type as specified by :paramref:`param_compare` type
     :param matches: test that :paramref:`param` matches the regex specified by :paramref:`param_compare` value
+    :param not_matches: test that :paramref:`param` doesn't match the regex specified by :paramref:`param_compare` value
     :raises HTTPError: if tests fail, specified exception is raised (default: :class:`HTTPBadRequest`)
     :raises HTTPInternalServerError: for evaluation error
     :return: nothing if all tests passed
     """
     content = {} if content is None else content
-    needs_compare = is_type or is_in or not_in or is_equal or not_equal or matches
+    needs_compare = is_type or is_in or not_in or is_equal or not_equal or matches or not_matches
     needs_iterable = is_in or not_in
 
     # precondition evaluation of input parameters
@@ -159,9 +161,11 @@ def verify_param(  # noqa: E126  # pylint: disable=R0913,too-many-arguments
             raise TypeError("'is_type' is not a 'bool'")
         if not isinstance(matches, bool):
             raise TypeError("'matches' is not a 'bool'")
+        if not isinstance(not_matches, bool):
+            raise TypeError("'not_matches' is not a 'bool'")
         # error if none of the flags specified
         if not any([not_none, not_empty, not_in, not_equal,
-                    is_none, is_empty, is_in, is_equal, is_true, is_false, is_type, matches]):
+                    is_none, is_empty, is_in, is_equal, is_true, is_false, is_type, matches, not_matches]):
             raise ValueError("no comparison flag specified for verification")
         if param_compare is None and needs_compare:
             raise TypeError("'param_compare' cannot be 'None' with specified test flags")
@@ -178,11 +182,11 @@ def verify_param(  # noqa: E126  # pylint: disable=R0913,too-many-arguments
             is_str_cmp = isinstance(param, six.string_types)
             ok_str_cmp = isinstance(param_compare, six.string_types)
             eq_typ_cmp = type(param) is type(param_compare)
-            is_pattern = matches and isinstance(param_compare, Pattern)
+            is_pattern = (matches or not_matches) and isinstance(param_compare, Pattern)
             if is_type and not (is_str_typ or is_cmp_typ):
                 LOGGER.debug("[param: %s] invalid type compare with [param_compare: %s]", type(param), param_compare)
                 raise TypeError("'param_compare' cannot be of non-type with specified verification flags")
-            if matches and not isinstance(param_compare, (six.string_types, Pattern)):
+            if (matches or not_matches) and not isinstance(param_compare, (six.string_types, Pattern)):
                 LOGGER.debug("[param_compare: %s] invalid type is not a regex string or pattern", type(param_compare))
                 raise TypeError("'param_compare' for matching verification must be a string or compile regex pattern")
             if not is_type and not ((is_str_cmp and ok_str_cmp) or (not is_str_cmp and eq_typ_cmp) or is_pattern):
@@ -252,6 +256,12 @@ def verify_param(  # noqa: E126  # pylint: disable=R0913,too-many-arguments
             param_compare_regex = re.compile(param_compare, re.I | re.X)
         fail_conditions.update({"matches": bool(re.match(param_compare_regex, param))})
         fail_verify = fail_verify or not fail_conditions["matches"]
+    if not_matches:
+        param_compare_regex = param_compare
+        if isinstance(param_compare, six.string_types):
+            param_compare_regex = re.compile(param_compare, re.I | re.X)
+        fail_conditions.update({"not_matches": not re.match(param_compare_regex, param)})
+        fail_verify = fail_verify or not fail_conditions["not_matches"]
     if fail_verify:
         content = apply_param_content(content, param, param_compare, param_name, with_param, param_content,
                                       needs_compare, needs_iterable, is_type, fail_conditions)

magpie/api/login/__init__.py

@@ -1,3 +1,4 @@
+from magpie.constants import get_constant
 from magpie.utils import get_logger
 
 LOGGER = get_logger(__name__)
@@ -11,4 +12,7 @@ def includeme(config):
     config.add_route(**s.service_api_route_info(s.SigninAPI))
     config.add_route(**s.service_api_route_info(s.ProvidersAPI))
     config.add_route(**s.service_api_route_info(s.ProviderSigninAPI))
+    if get_constant("MAGPIE_NETWORK_MODE", settings_name="magpie.network_mode"):
+        config.add_route(**s.service_api_route_info(s.TokenAPI))
+        config.add_route(**s.service_api_route_info(s.TokenValidateAPI))
     config.scan()