MediaWiki extensions manual
JWTAuth
Release status: stable
Implementation User identity , User rights
Description Adds support for using JSON Web Tokens to log in to MediaWiki
Author(s) Jeffrey Wang (MyWikis-JeffreyWangtalk)
Compatibility policy Main branch maintains backward compatibility.
MediaWiki 1.35.0+
License MIT License
Download

GitHub:

Note:
No localisation updates are
provided by translatewiki.net .
Parameters
$wgJWTAuthAlgorithm, $wgJWTAuthKey, $wgJWTGroupMapping, $wgJWTAuthDebugMode

The JWTAuth extension adds support for using JSON Web Tokens to log in to MediaWiki. JWTs are a common medium for conveying an authentication assertion in the tangible form of a token.

Prerequisites

JWTAuth is not a complete auth system. It is simply the last mile of processing JWTs. To learn more about how JWTs work, go to JWT.io. JWTAuth only facilitates the verification of JWTs that were already issued. Therefore, an auth system that issues JWTs is the primary prerequisite.

The JWT needs to be passed into the wiki's Special:JWTLogin page. It will take whatever content is POSTed in the Authorization parameter (query string) and process it. The content should begin with Bearer  (with a space after the word "Bearer") or Bearer:, followed by the actual JWT.

Why use JWTAuth?

Presentation about JWTAuth at EMWCon Spring 2023

Comparison with PluggableAuth

JWTAuth is not intended to be a competitor to PluggableAuth. JWTAuth does not deal with the actual authentication against the user base. It only verifies JWTs given to it. Consequently, JWTAuth only deals with MediaWiki's SessionManager. Meanwhile, PluggableAuth deals with AuthManager.

Limitations

One inherent limitation of JWTAuth is its inability to check for whether tokens are revoked. This is not a bug; it is expected behavior because of the design of this auth process. It is able to detect whether the token is expired or forged, but if a token were to be revoked before the scheduled expiry time, the JWTAuth extension would have no way of knowing, as it doesn't talk back with the IdP who issued the token. Most PluggableAuth-based extensions don't suffer from this limitation. Usually, it's best to use the JWTAuth extension in an environment where the ability to immediate revoke a token is either unnecessary because another layer of auth would take care of it (like a company-issued computer shutting down when its associated employee's employment comes to an end), or not important. The best way to mitigate this issue would be to set the validity period to be as short as possible.

This also means JWTAuth doesn't include single sign-out.

There are many discussions of the merits of using JWTs versus other authentication mechanisms, and especially about what the best way to use them would be, but they are beyond the scope of this page. Please see JWT.io to learn more about JWTs.

Advantages

However, JWTAuth is relatively fast compared to using the authentication process defined by AuthManager and PluggableAuth because it does not involve any back-and-forth between the IdP and the SP. JWTs are useful for persisting auth session throughout the token's life because it means it can reuse token across multiple services and avoids needing to log in multiple times. It's best for systems where user will be logged in to several sites at once, including MediaWiki, and when sites are accessed from a central login system.

The JWTAuth extension doesn't require a JWT to be sent with each request to the web server. It only needs it to be sent once to Special:JWTLogin per login session. Once the JWTAuth extension authenticates the user based on the validity of the token, a cookie is set in MediaWiki to authenticate them for the rest of the MediaWiki session. The rest of the session is managed by MediaWiki and JWTAuth doesn't interface with it after that point.

Installation

  • Download and place the file(s) in a directory called JWTAuth in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php file: 
    wfLoadExtension( 'JWTAuth' );
$wgJWTAuthAlgorithm = ''; // can be: HS256, RS256, EdDSA
$wgJWTAuthKey = ''; // Depends on which algorithm you are using
$wgJWTGroupMapping = [
  // one group can map to multiple MediaWiki groups...
  'customgroup1' => [
    'sysop', 'bureaucrat'
  ],
  // ...or just one MediaWiki group.
  'customgroup2' => 'sysop'
];
  • Yes Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration

$wgJWTAuthAlgorithm
The algorithm used to encode and decode the JWT.
$wgJWTAuthKey
When using a symmetric algorithm, this is the shared passkey used to encode and decode the JWT.
When using an asymmetric algorithm, this is the public key. (The private key would be stored on side of the issuer of the JWT.)
$wgJWTGroupMapping
The mapping of any custom group names passed in via the groups claim.

Integrating your auth system with JWTAuth on MediaWiki

The following procedure must be followed to successfully authenticate a user into the wiki:

  1. A JWT claim must be well formed and encoded into the JWT payload format using the key that has already been agreed upon.
  2. Find the path to your wiki's location of Special:JWTLogin. For instance, if your wiki is under https://wiki.example.com and $wgArticlePath = "/wiki/$1"; then the location is https://wiki.example.com/wiki/Special:JWTLogin.
  3. The payload must be POSTed to this aforementioned URL. The URL should have a parameter called Authorization with the content Bearer: JWTTOKENHERE. For instance, Bearer: eyJhbGciOiJIUzI...66Vkfljr.
  4. The payload must conform to the claim names promulgated by IANA: https://www.iana.org/assignments/jwt/jwt.xhtml

Below are the claims that are required by the JWTAuth extension. If any of these are missing, the authentication process will fail. If you are unsure of what these mean, or the allowed values for them, please visit https://jwt.io for more details.

  • preferred_username: Username. This is used by JWTAuth to form the user's username on MediaWiki. Please make sure the usernames conform to MediaWiki's allowed username rules.
  • exp: Expiry timestamp.
  • iat: Issued at timestamp.
  • nbf: Not valid before timestamp.
  • iss: Issuer
  • aud: Audience
  • sub: Subject

You can put nonsense (but nonempty) values for iss, aud, and sub, as they are not checked by JWTAuth, but our JWT decoding library (Firebase JWT) will cause the auth process to fail if they are not set.

The following claims are optional, but are highly recommended because they will be added to users' profiles:

  • email
  • family_name
  • given_name

As of 0.1.0, most of these claim names cannot be changed to match the token generator's preferences because these claim names are standard conventions. The party generating the token is responsible for sending well-formed responses that conform to internet standards. The group claims name can be changed to match your preferences by modifying $wgJWTGroupClaimsName.

If you want to assign groups to a user, pass them in, separated by commas, by using the groups claim. For instance, "groups": "customgroup1,customgroup2". Then, define the mapping in $wgJWTGroupMapping like it was done in the example config shown above.

Please see the README for this extension for more details.

This article is issued from Mediawiki. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.