network mode

.github/.gitleaks.toml

@@ -49,6 +49,9 @@ title = "gitleaks config"
 	description = "Asymmetric Private Key"
 	regex = '''-----BEGIN ((EC|PGP|DSA|RSA|OPENSSH) )?PRIVATE KEY( BLOCK)?-----'''
 	tags = ["key", "AsymmetricPrivateKey"]
+	[rules.allowlist]
+		description = "test for presence of private keys"
+		paths = ['''tests/test_magpie_cli.py''']
 [[rules]]
 	description = "Generic Credential"
 	regex = '''(?i)(api_key|apikey|secret)(.{0,20})?['|"][0-9a-zA-Z]{16,45}['|"]'''

.github/workflows/tests.yml

@@ -62,11 +62,18 @@ jobs:
             python-version: "3.10"
             allow-failure: false
             test-case: check
-          # remote test
+          # remote test (note that network tests are skipped since the remote server won't have network mode enabled)
           - os: ubuntu-latest
             python-version: "3.11"
             allow-failure: true
             test-case: start test-remote
+          # remote network tests using a remote server with network mode enabled
+          - os: ubuntu-latest
+            python-version: "3.12"
+            allow-failure: true
+            test-case: start test  # the tests that are run are limited by the PYTEST_ADDOPTS in test-option below
+            test-option: >- 
+              PYTEST_ADDOPTS='-m "remote and network"' MAGPIE_NETWORK_CREATE_MISSING_PEM_FILE=True MAGPIE_NETWORK_ENABLED=on MAGPIE_NETWORK_INSTANCE_NAME=example
           # coverage test
           - os: ubuntu-latest
             python-version: "3.11"
@@ -105,6 +112,9 @@ jobs:
         run: |
           hash -r
           env | sort
+      - name: Create private key for network testing
+        if: ${{ matrix.test-case == 'test-local' }}
+        run: ${{ matrix.test-option }} make create-private-key
       # run '-only' test variations since dependencies are preinstalled, skip some resolution time
       - name: Run Tests
         run: ${{ matrix.test-option }} make stop ${{ matrix.test-case }}-only

.gitignore

@@ -56,3 +56,7 @@ magpie_delete_users*.txt
 requirements-all.txt
 gunicorn.app.wsgiapp
 error_log.txt
+
+# Secrets
+*.pem
+*.key

CHANGES.rst

@@ -33,7 +33,11 @@ Features / Changes
 ------------------------------------------------------------------------------------
 
 Features / Changes
-~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~
+
+* Introduce "Network Mode" which allows other Magpie instances to act as external authentication providers using access
+  tokens. 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.
 * Add CLI helper ``batch_update_permissions`` that allows registering one or more `Permission` configuration files
   against a running `Magpie` instance.
 * Security fix: bump Docker base ``python:3.11-alpine3.19``.

Makefile

@@ -802,3 +802,7 @@ conda-env: conda-base	## create conda environment if missing and required
 			echo "Creating conda environment at '$(CONDA_ENV_PATH)'..." && \
 		 	"$(CONDA_BIN)" create -y -n "$(CONDA_ENV_NAME)" python=$(PYTHON_VERSION)) \
 		)
+
+.PHONY: create-private-key
+create-private-key:  ## create a private key file according to the MAGPIE_NETWORK_PEM_FILES and MAGPIE_NETWORK_PEM_PASSWORDS settings
+	@bash -c '$(CONDA_CMD) magpie_create_private_key --config "$(APP_INI)"'

ci/magpie.env

@@ -12,8 +12,11 @@ MAGPIE_ADMIN_PASSWORD=qwerty-ci-tests
 MAGPIE_LOG_LEVEL=INFO
 MAGPIE_LOG_REQUEST=false
 MAGPIE_LOG_EXCEPTION=false
+MAGPIE_NETWORK_INSTANCE_NAME=node1
 MAGPIE_TEST_VERSION=latest
 MAGPIE_TEST_REMOTE_SERVER_URL=http://localhost:2001
+MAGPIE_TEST_REMOTE_NODE_SERVER_HOST=localhost
+MAGPIE_TEST_REMOTE_NODE_SERVER_PORT=2002
 MAGPIE_TEST_ADMIN_USERNAME=unittest-admin
 # auto-generate password
 MAGPIE_TEST_ADMIN_PASSWORD=

config/magpie.ini

@@ -28,6 +28,12 @@ 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_enabled = true
+# magpie.network_default_token_expiry = 86400
+# magpie.network_instance_name =
+# magpie.network_pem_files = key.pem
+
 # magpie.config_path =
 
 # --- cookie definition --- (defaults below if omitted)

docs/authentication.rst

@@ -422,3 +422,116 @@ 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_ENABLED` is enabled, `Magpie` instances can be linked in a network which allows them to
+associate user accounts across the network and provide limited resource access to users who have accounts on other
+`Magpie` instances in the network. Each `Magpie` instance is considered a node in the network.
+
+Users who have an account on one `Magpie` instance can request an access token from another instance in the network
+which the user can use to access resources protected by the other `Magpie` instance.
+
+Users with accounts on multiple instances in the network can also choose to link their accounts. This allows users who
+use access tokens to ensure that they have the same access to resources that they would have if they logged in to
+`Magpie` using any other method.
+
+
+Managing the Network
+~~~~~~~~~~~~~~~~~~~~
+
+Each `Magpie` instance must be made aware of the existence of the other instances in the network so that they know where
+to send token requests and account linking 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 includes
+
+* ``name``:
+    * the name of that other `Magpie` instance in the network and should correspond to the same value as the
+      :envvar:`MAGPIE_NETWORK_INSTANCE_NAME` value set by the other `Magpie` instance.
+* ``jwks_url``:
+    * URL that provides the instance's public key in the form of a JSON Web Key Set.
+    * This is usually ``https://{hostname}/network/jwks`` where ``{hostname}`` is the hostname of the other instance
+* ``authorization_url``
+    * URL that provides the instance's Oauth authorize endpoint.
+    * This is usually ``https://{hostname}/ui/network/authorize`` where ``{hostname}`` is the hostname of the other
+      instance.
+* ``token_url``
+    * URL that provides the instances Oauth token endpoint.
+    * This is usually ``https://{hostname}/network/token`` where ``{hostname}`` is the hostname of the other instance.
+* ``redirect_uris``
+    * JSON array of valid redirect URIs for the instance. These are used by the instance's Oauth authorize
+      endpoint to safely redirect the user back once they have authorized `Magpie` to link their accounts on two
+      different instances.
+    * This is usually ``https://{hostname}/network/link`` where ``{hostname}`` is the hostname of the other
+      instance.
+
+
+Once a :term:`Network Node` is registered, `Magpie` can treat the other instance as if they are in the same network as
+long as:
+
+* Both instances have :envvar:`MAGPIE_NETWORK_ENABLED` enabled
+* Both instances have :envvar:`MAGPIE_NETWORK_INSTANCE_NAME` set
+* Both instances have :envvar:`MAGPIE_NETWORK_PEM_FILES` set in order to verify communication between nodes using an
+  asymmetric public/private key-pair.
+
+
+Managing Personal Access Tokens
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A :term:`User` can request a new access token from another node with a request to the
+``GET /network/nodes/{node_name}/token`` route.
+
+Every time a :term:`User` makes a request to this route, `Magpie` send a request to the other instance, and provides it
+to the user. A new token is generated every time. This effectively cancels all previously created tokens for that user.
+
+To cancel an existing token without generating a new one. A :term:`User` can make a request to the
+``DELETE /network/nodes/{node_name}/token`` route.
+
+Authentication
+~~~~~~~~~~~~~~
+
+Once a :term:`User` gets an access token, they can use that token to authenticate with the instance that issued that
+token.
+
+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 access 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

@@ -986,6 +986,134 @@ 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_ENABLED` is enabled.
+
+.. envvar:: MAGPIE_NETWORK_ENABLED
+
+    [:class:`bool`]
+    (Default: ``False``)
+
+    .. versionadded:: 3.38
+
+    Enable "Network Mode" which enables all functionality to authenticate users using other Magpie instances as
+    external authentication providers.
+
+.. envvar:: MAGPIE_NETWORK_INSTANCE_NAME
+
+    [:class:`str`]
+
+    .. versionadded:: 3.38
+
+    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_ENABLED` is ``True``.
+
+.. envvar:: MAGPIE_NETWORK_DEFAULT_TOKEN_EXPIRY
+
+    [:class:`int`]
+    (Default: ``86400``)
+
+    .. versionadded:: 3.38
+
+    The default expiry time (in seconds) for an access token issued for the purpose of network authentication.
+
+.. envvar:: MAGPIE_NETWORK_INTERNAL_TOKEN_EXPIRY
+
+    [:class:`int`]
+    (Default: ``30``)
+
+    .. versionadded:: 3.38
+
+    The default expiry time (in seconds) for an JSON Web Token issued for the purpose of communication between nodes in
+    the network.
+
+.. envvar:: MAGPIE_NETWORK_TOKEN_NAME
+
+    [|constant|_]
+    (Value: ``"magpie_token"``)
+
+    .. versionadded:: 3.38
+
+    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.38
+
+    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.38
+
+    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.38
+
+    The name of the group created to manage permissions for all users authenticated using Magpie instances as external
+    authentication providers.
+
+.. envvar:: MAGPIE_NETWORK_PEM_FILES
+
+    [:class:`str`]
+    (Default: ``${MAGPIE_ROOT}/key.pem``)
+
+    .. versionadded:: 3.38
+
+    Path to a PEM file containing a public/private key-pair. This is used to sign and verify communication sent between
+    nodes in the network.
+
+    Multiple PEM files can be specified if key rotation is desired. To specify multiple PEM files, separate each file
+    path with a ``:`` character. The first file in the list will contain the primary key and will be used to sign all
+    outgoing communication.
+
+.. envvar:: MAGPIE_NETWORK_PEM_PASSWORDS
+
+    [:class:`str`]
+    (Default: ``None``)
+
+    .. versionadded:: 3.38
+
+    Password used to encrypt the PEM files in :envvar:`MAGPIE_NETWORK_PEM_FILES`.
+
+    If multiple files require passwords, they can be listed as a JSON array. An empty string will be treated the same as
+    no password.
+
+    For example, if you have four files specified in :envvar:`MAGPIE_NETWORK_PEM_FILES` and only the first and third
+    file require a password, set this variable to ``["pass1", "" ,"pass2", ""]`` where ``pass1`` and ``pass2`` are the
+    passwords.
+
+.. envvar:: MAGPIE_NETWORK_CREATE_MISSING_PEM_FILE
+
+    [:class:`bool`]
+    (Default: ``False``)
+
+    .. versionadded:: 3.38
+
+    If enabled *and* there is a single file specified in :envvar:`MAGPIE_NETWORK_PEM_FILES` *and* that file is missing,
+    `Magpie` will generate a new private key file when starting up. If a password is specified for that file in
+    :envvar:`MAGPIE_NETWORK_PEM_PASSWORDS` then the private key file will be encrypted with that password as well.
 
 .. _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

env/magpie.env.example

@@ -32,6 +32,9 @@ MAGPIE_TEST_VERSION=latest
 # this means you must have a separately running Magpie instance reachable at that endpoint to run 'remote' tests
 # to ignore this, consider setting an empty value or running 'make test-local' instead
 MAGPIE_TEST_REMOTE_SERVER_URL=http://localhost:2001
+# below URL specifies a host and port for a fake network node (used for network tests)
+MAGPIE_TEST_REMOTE_NODE_SERVER_HOST=localhost
+MAGPIE_TEST_REMOTE_NODE_SERVER_PORT=2002
 # below are the credentials employed to run tests (especially if running on non-default remote server)
 MAGPIE_TEST_ADMIN_USERNAME=admin
 MAGPIE_TEST_ADMIN_PASSWORD=qwerty

magpie-cron

@@ -1 +1,2 @@
 0 * * * * /bin/bash -c "set -a ; source <($MAGPIE_ENV_DIR/*.env) ; set +a ; magpie_sync_resources"
+1 0 * * * /bin/bash -c "set -a ; source <($MAGPIE_ENV_DIR/*.env) ; set +a ; magpie_purge_expired_network_tokens"