Extension:NetworkSession

MediaWiki extensions manual

NetworkSession Release status: experimental
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
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

NetworkSession is a SessionProvider for api requests based on configured ip address and a secret token. It is intended for use cases such as having a system user in a wikifarm for a supporting application.

Installation

Enable the extension by adding wfLoadExtension( 'NetworkSession' ); along with the required config variables to LocalSettings.php.

Configuration

Extension configuration variables are sets of key=value pairs. The following config options are available for this extension.

Variable name	Default value	Description
$wgNetworkSessionProviderUsers	[]	Configures the set of users that will by provided, and the requirements the request must meet. This defaults to the empty list, if not configured the extension has no effect. All three values are required for each user. The top-level array keys are ignored, this can be a list or an assoc array depending on what is convenient to configure. Configured users must uniquely match a request. If a request matches multiple defined users the request will fail, not knowing which one to select.
$wgNetworkSessionProviderAllowedUserRights	null	Configures the limits to the set of user rights that will be 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 will be limited by anonymous user rights. If an anonymous user cannot create an account, than neither can an account here. When true the account will be created regardless of any other rights declarations. By default this is false and account creation limits are not overridden.

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'

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. Once the related service has transitioned to the new token the old user definition should be removed.

$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 will not be able to 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;