MediaWiki extensions manual
Release status: beta
Implementation Hook
Description Adds ratelimit claims to OAuth JWT
Author(s) Clara Andrew-Wani and Petr Pchelko
Latest version 0.0.1 (continuous updates)
MediaWiki 1.35+
Database changes Yes
License GNU General Public License 2.0 or later
  • $wgOAuthRateLimiterTierConfig
  • $wgOAuthRateLimiterDefaultClientTier
Quarterly downloads 1 (Ranked 137th)
Translate the OAuthRateLimiter extension if it is available at translatewiki.net
Issues Open tasks · Report a bug

The OAuthRateLimiter extension implements an OAuth hook to add ratelimit values to the OAuth JSON Web Token (JWT).

Requirements edit

  • OAuthRateLimiter relies on the OAuth extension
  • Currently, only mysql and sqlite database backends are supported

Installation edit

  • Download and move the extracted OAuthRateLimiter 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/OAuthRateLimiter
  • Only when installing from Git, run Composer to install PHP dependencies, by issuing composer install --no-dev in the extension directory. (See task T173141 for potential complications.)
  • Add the following code at the bottom of your LocalSettings.php file:
    wfLoadExtension( 'OAuthRateLimiter' );
  • Run the update script which will automatically create the necessary database tables that this extension needs.
  • Configure as required.
  •   Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration edit

Parameters edit

Variable name Default value Description
Default client tier name used when there is no tier name in the database
Rate limit tiers for clients

Local development edit

To set up a working test environment follow the instructions below.

  • Follow install instructions for both OAuth and OAuthRateLimiter
  • Generate public and private keys
    openssl genrsa -out private.key 2048
    openssl rsa -in private.key -pubout -out public.key
  • Configure user rights & general params:
    // OAuth requires emails to be authenticated, this automatically authenticates an email added to user preference
    $wgEmailAuthentication = false;
    // Rights to add/update a consumer
    $wgGroupPermissions['*']['mwoauthproposeconsumer'] = true;
    $wgGroupPermissions['*']['mwoauthupdateownconsumer'] = true;
    // location of private & public key 
    $wgOAuth2PrivateKey = "/var/www/mediawiki/extensions/OAuth/private.key";
    $wgOAuth2PublicKey = "/var/www/mediawiki/extensions/OAuth/public.key";
    // OAuthRatelimiter configs
    $wgOAuthRateLimiterDefaultClientTier = 'default';
    $wgOAuthRateLimiterTierConfig = [
        'default' => [
            'ratelimit' => [
                'requests_per_unit' => 1000,
                'unit'  => 'sec'
        'Tier 1' => [
            'ratelimit' => [
                'requests_per_unit' => 10000,
                'unit'  => 'sec'
  • Follow OAuth registration steps to register an OAuth application. Make sure to choose OAuth 2.0 for OAuth protocol version and to save your consumer and private token for the next steps.
  • Follow OAuth 2.0 authorization steps to authorize the client and get an access_token. Note: requests to /oauth2/access_token must be a POST.
  • Use a website like https://jwt.io/ to decode the access_token. You should see the default rate limit information from $wgOAuthRateLimiterTierConfig
  • To change a user’s client tier use the maintenance script: php setClientTierName.php --client=<your_client_id> --tier="Tier 1". To see the updated ratelimit in the access_token, you’ll need to rerun the OAuth 2.0 authorization steps