Extension:NetworkSession

Category:Extensions without an imageCategory:GPL licensed extensions
MediaWiki extensions manual
NetworkSession
Release status: betaCategory:Beta status extensions
Implementation User identity Category:User identity extensions
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.Category:Extensions with release branches compatibility policy
MediaWiki >= 1.43Category:Extensions with manual MediaWiki version
License GNU General Public License 2.0 or later
Download
Download extension
Git [?]:
Category:Extensions in Wikimedia version control
Translate the NetworkSession extension if it is available at translatewiki.net
Issues Open tasks · Report a bug
Category:All extensionsCategory:Extensions not in ExtensionJson

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.
  • Yes 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

Category:Extensions used on Wikimedia#NetworkSession
Category:All extensions Category:Beta status extensions Category:Extensions in Wikimedia version control Category:Extensions not in ExtensionJson Category:Extensions used on Wikimedia Category:Extensions with manual MediaWiki version Category:Extensions with release branches compatibility policy Category:Extensions without an image Category:GPL licensed extensions Category:User identity extensions