Extension:NetworkSession

MediaWiki extensions manual

NetworkSession Release status: beta
Implementation	User identity
Description	SessionProvider based on configured ip address and secret token
Author(s)	Erik Bernhardson (EBernhardson (WMF)talk)
Latest version	0.1.0 (2024-01-10)
Compatibility policy	Snapshots releases along with MediaWiki. Master is not backward compatible.
MediaWiki	>= 1.43
License	GNU General Public License 2.0 or later
Download	Download extension Git [?]: Download Git master browse repository (GitHub) commit history repository contributors (GitHub) code review
Translate the NetworkSession extension if it is available at translatewiki.net
Issues	Open tasks · Report a bug

The NetworkSession extension is a SessionProvider for API requests based on a configured IP address and a secret token. It is intended for use cases such as having a system user in a wiki farm for a supporting application.

Installation

• Download and move the extracted NetworkSession folder to your extensions/ directory.
  Developers and code contributors should install the extension from Git instead, using:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/NetworkSession
• Add the following code at the bottom of your LocalSettings.php file:

  wfLoadExtension( 'NetworkSession' );
  

• Configure as required.
•  Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration

Extension configuration parameters are sets of "key=value" pairs. The following configuration parameters are available for this extension:

Variable name	Default value	Description
$wgNetworkSessionProviderUsers	[]	Configures the set of users provided and the requirements for the request. This defaults to the empty list; the extension has no effect if not configured. All three values are required for each user. The top-level array keys are ignored. This can be a list or an associated array, depending on what is convenient to configure. Configured users must uniquely match a request. If a request matches multiple defined users, it will fail because it does not know which one to select.
$wgNetworkSessionProviderAllowedUserRights	null	Configures the limits to the user rights available when logged in through this provider. This does not grant any rights the account does not already have. It limits the rights they have to only this list. By default, no limits are applied.
wgNetworkSessionProviderCanAlwaysAutocreate	false	When false account auto-creation is limited by anonymous user rights. If an anonymous user cannot create an account, neither can an account here. When true, the account will be created regardless of other rights declarations. By default, account creation limits are not overridden.

Configuring rotating secrets

A common need is to replace the secret token without interrupting ongoing operations. This is accomplished by adding a second user with the same username and a new token. The old user definition should be removed once the related service has transitioned to the new token.

$wgNetworkSessionProviderUsers = [
    [
        'username' => 'Example bot',
        'token' => '@ryoEdR7p^lG1E&mMsO0tZn3Q6I&r03s',
        'ip_ranges' => [ '127.0.0.1' ],
    ],
    [
        'username' => 'Example bot',
        'token' => 'Ih4#JyFQfyTe1iNn7eWtTry%Ye!caySS',
        'ip_ranges' => [ '127.0.0.1' ],
    ],
];

Example configuration

In this example, a single user is configured. Requests that are made from either 127.0.0.1 (localhost) or 10.*.*.* and contain the required Authorization header will be authenticated as the configured user. This user will have, at most, read access to the wiki and cannot perform edits. The account will be created, regardless of account creation limits, if it doesn't already exist.

$wgNetworkSessionProviderUsers = [
    [
        // The name of the account that will be used. If the account does
        // not exist it will be created. If it cannot be created the user
        // will not be logged in.
        'username' => 'Example bot',
        // The secret token that must be provided in the `Authorization`
        // HTTP header.
        'token' => '@ryoEdR7p^lG1E&mMsO0tZn3Q6I&r03s',
        // The set of valid ip addresses or ip address ranges that the
        // request must come from.
        'ip_ranges' => [
            '127.0.0.1',
            '10.0.0.0-10.255.255.255',
        ]
    ]
];
$wgNetworkSessionProviderAllowedUserRights = [ 'read' ];
$wgNetworkSessionProviderCanAlwaysAutocreate = true;

Usage

HTTP Requests must specify the NetworkSession auth-scheme with the correct token as the authorization parameters in the Authorization HTTP header and come from a matching ip address. Requests must use https to protect the secret token. Non-https requests will be rejected. The following curl works with the example configuration below:

curl -H 'Authorization: NetworkSession @ryoEdR7p^lG1E&mMsO0tZn3Q6I&r03s' \
    https://localhost/w/api.php?action=query&meta=userinfo&format=json'

See also

• Extension:NetworkAuth