Extension:NetworkSession
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 | |
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
[edit]Enable the extension by adding
along with
the required config variables to wfLoadExtension( 'NetworkSession' );
.
LocalSettings.php
Configuration
[edit]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
[edit]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
[edit]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
[edit]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;
See also
[edit]This extension is being used on one or more Wikimedia projects. This probably means that the extension is stable and works well enough to be used by such high-traffic websites. Look for this extension's name in Wikimedia's CommonSettings.php and InitialiseSettings.php configuration files to see where it's installed. A full list of the extensions installed on a particular wiki can be seen on the wiki's Special:Version page. |