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 0
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).


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


  • Download and place the file(s) in a directory called OAuthRateLimiter in your extensions/ folder.
  • 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 :
    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.

To users running MediaWiki 1.24 or earlier:

The instructions above describe the new way of installing this extension using wfLoadExtension(). If you need to install this extension on these earlier versions (MediaWiki 1.24 and earlier), instead of wfLoadExtension( 'OAuthRateLimiter' );, you need to use:

require_once "$IP/extensions/OAuthRateLimiter/OAuthRateLimiter.php";



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 developmentEdit

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