**Project Information **
* Name of tool/project: OAuthRateLimiter
* Project home page: https://www.mediawiki.org/wiki/Extension:OAuthRateLimiter
* Name of team requesting review: #platform_engineering
* Primary contact: @Pchelolo, @Clarakosi
* Target date for deployment: August 14th
* Link to code repository / patchset: https://gerrit.wikimedia.org/r/c/mediawiki/extensions/OAuthRateLimiter/+/613282
**Description of the tool/project: **
The extension holds a single database table with a mapping from OAuth client ID to the rate limit tier. The rate limits for different tiers are statically configured in mediawiki-config. The tiers are assigned to the clients via a maintenance script. Dynamic tiers and UI for tier management might be implemented later if needed.
The ratelimit claims for the client is supplied to the OAuth extension via a new hook. The OAuth extension adds the claims to the access token JWT as private claims, which is then used by the envoy API Gateway to supply to the ratelimit service.
Currently the code depends on the fork of the oauth2-server library, that includes a single [[ https://github.com/thephpleague/oauth2-server/pull/1122 | pull request ]] which adds support for private claims. We're working with upstream to get the pull request accepted in the upstream library, and the need for the fork will eventually disappear.
**Description of how the tool will be used at WMF:**
We are developing an API Portal/Gateway. The work is described by the [[ https://www.mediawiki.org/wiki/Core_Platform_Team/Initiatives/API_Gateway | API Gateway initiative ]].
As part of this project, we plan to use the extension, [[ https://www.mediawiki.org/wiki/Extension:OAuthRateLimiter | OAuthRatelimiter ]], to add ratelimiter information to the OAuth token.
**Dependencies**
* mediawiki-extensions-OAuth
**Has this project been reviewed before?**
No
**Working test environment**
1. Download both [[ https://gerrit.wikimedia.org/r/admin/repos/mediawiki/extensions/OAuth | OAuth ]] and [[ https://gerrit.wikimedia.org/r/admin/repos/mediawiki/extensions/OAuthRateLimiter | OAuthRateLimiter ]] to `extensions/` folder
2. Checkout [[https://gerrit.wikimedia.org/r/c/mediawiki/extensions/OAuthRateLimiter/+/613282 | 613282 ]] into OAuthRateLimiter
3. Checkout [[https://gerrit.wikimedia.org/r/c/mediawiki/extensions/OAuth/+/610335 | 610335 ]] into OAuth
4. Run composer update to bring in fork of league/oauth2-server
5. Add the following code at the bottom of your LocalSettings.php:
```lang=php
wfLoadExtension( 'OAuth' );
wfLoadExtension( 'OAuthRateLimiter' );
```
6. Run the [[ https://www.mediawiki.org/wiki/Manual:Update.php | update ]] script which will automatically create the necessary database tables that these extensions needs.
7. Generate public and private keys
```lang=bash
openssl genrsa -out private.key 2048
openssl rsa -in private.key -pubout -out public.key
```
8. Configure user rights & general params:
```lang=php
// 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' => [
'request_per_unit' => 1000,
'unit' => 'sec'
]
],
'Tier 1' => [
'ratelimit' => [
'request_per_unit' => 10000,
'unit' => 'sec'
]
]
];
```
9. Follow [[ https://www.mediawiki.org/wiki/OAuth/For_Developers#Registration | 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.
10. Follow [[ https://www.mediawiki.org/wiki/OAuth/For_Developers#Authorization_2 | OAuth 2.0 authorization ]] steps to authorize the client and get an access_token. Note: requests to `/oauth2/access_token` must be a POST.
11. Use a website like https://jwt.io/ to decode the access_token. You should see the default rate limit information from $wgOAuthRateLimiterTierConfig
12. To change a user’s client tier use the maintenance script: `php setClientTierName.php --client=<your_client_id> --tier="Tier 1"`
13. To see the updated ratelimit in the access_token, you’ll need to rerun steps 10-11
**Post-deployment**
#platform_engineering will own the extension.