Jump to content

Extension:JWTAuth

From mediawiki.org
This page is a translated version of the page Extension:JWTAuth and the translation is 5% complete.
Languages:
この拡張機能では、先に PluggableAuth 拡張機能をインストールする必要があります。
MediaWiki 拡張機能マニュアル
JWTAuth
リリースの状態: 安定
実装 利用者識別 , 利用者権限
説明 Adds support for using JSON Web Tokens to log in to MediaWiki
作者
最新バージョン 2.1.0
互換性の方針 後方互換性を維持するメイン ブランチ。
MediaWiki 1.43.0+
データベースの変更 はい
ライセンス MIT ライセンス
ダウンロード
拡張機能をダウンロード
Git [?]:
パラメーター
  • $wgJWTAuth_UseRealNameAsUserName
  • $wgJWTAuth_RequiredClaims
  • $wgJWTAuth_MigrateUsersByEmail
  • $wgJWTAuth_MigrateUsersByUserName
  • $wgJWTAuth_UseEmailNameAsUserName
  • $wgJWTAuth_Key
  • $wgJWTAuth_Algorithm
使用するフック
translatewiki.net で翻訳を利用できる場合は、JWTAuth 拡張機能の翻訳にご協力ください

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.

JWTAuth was rewritten to use PluggableAuth in version 2.0.0. However, this new approach did not fully work until version 2.1.0 - which also removed support for MediaWiki versions less than 1.43. Anyone using an older version of MediaWiki is thus encouraged to use the pre-PluggableAuth version of JWTAuth, "version 1" (technically, version 0.1.0) instead.

Version 1 vs. version 2

JWTAuth 2 is a rewrite of the original extension to use PluggableAuth, which brings benefits of the PluggableAuth ecosystem that the original version of JWTAuth couldn't leverage. We highly recommend using JWTAuth 2. That being said, JWTAuth 2.1.0 requires MediaWiki 1.43 or above, so if you're using an older version of MediaWiki between 1.35 and 1.42 (especially 1.35 or 1.39), please consider using JWTAuth 1.

JWTAuth 1 is no longer officially supported and no further updates are planned, but users have reported that version 1 works very well with MediaWiki 1.35 and 1.39.

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.

As of JWTAuth 2.0.0, the extension is based off of PluggableAuth and requires PluggableAuth 7.0 or higher to be installed on the wiki.

The JWT needs to be passed as a header parameter into the wiki's Special:Userlogin (version 2) or Special:JWTLogin page (version 1). 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. Full setup instructions can be found in the #Integrating your auth system with JWTAuth on MediaWiki section below.

Why use JWTAuth?

Presentation about JWTAuth at EMWCon Spring 2023 (before it was rewritten to use PluggableAuth)

JSON Web Tokens are a widely used medium to encode session data. They are issued by an identity provider (IdP) and consumed by service providers (SPs) by using a mutually agreed upon key (whether symmetric or asymmetric) to check if a given token is valid or not. If the SP is presented with a supposedly valid token supposedly issued by the IdP, it is taken for face value and the user is authenticated into the service.

Advantages

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:Userlogin (in version 1, 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.

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.

Installation

  • ダウンロードして、ファイルをextensions/フォルダー内のJWTAuthという名前のディレクトリ内に配置します。
    開発者とコード寄稿者は、上記の代わりに以下を使用してGitからインストールします:
    cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/JWTAuth
  • 以下のコードを LocalSettings.php ファイルの末尾に追加します: 
    wfLoadExtension( 'JWTAuth' );
  • Configure as described below.
  • Yes 完了 – ウィキの「Special:Version」に移動して、拡張機能が正しくインストールされたことを確認します。

Configuration

This section only describes the configuration you need to do on the MediaWiki LocalSettings.php file. For information on how to send a JWT request to your wiki, please take a look at the #Integrating your auth system with JWTAuth on MediaWiki section below.

Version 2 (PluggableAuth-based)

The configuration is done in PluggableAuth's config settings (see Extension:PluggableAuth#Configuration).

$wgPluggableAuth_Config

Default value:: []

A mandatory array of arrays specifying the JWTAuth configuration. The data field of the array contains an array with keys specific to the JWTAuth extension. If one of the keys is not present in the configuration array, its value will fallback to the value of the configuration variable with the same name prefixed by $wgJWTAuth_; for example, if the value for Algorithm is not present in the data section for a JWTAuth plugin configuration, the value of the global $wgJWTAuth_Algorithm configuration variable will be used. The following are valid keys:

Algorithm Default value: "HS256" The algorithm used to encode and decode the JWT. Currently, only HS256, RS256, and EdDSA are supported. The former uses a simple passphrase, whereas the latter two use a public/private keypair. As elliptical curves cannot be cracked by quantum algorithms, we highly recommend EdDSA.
Key 必須 When using a symmetric encryption algorithm like HS256, this is the shared passkey used to encode and decode the JWT. When using an asymmetric encryption algorithm such as RS256 or EdDSA, this is the public key. (The private key would be stored on side of the issuer of the JWT.)
UseRealNameAsUserName Default value: false If a new user is being created in the database and no preferred username was provided by the issuer or preferred_username was set to null or the empty string, a value of true for this flag indicates that the user's real name, if provided by the issuer, should be used as the new user's username. If set to true, and no preferred username was provided by the issuer, the literal "User" will be used as username for the first user, and any subsequent users will use the literal "User" followed by a number. E.g., "User", "User1", "User2", etc. The same naming happens if this parameter is set to false.
UseEmailNameAsUserName Default value: false If a new user is being created in the database, and no preferred username was provided by the issuer or preferred_username was set to null or the empty string, and either no real name was provided by the issuer or UseRealNameAsUserName was undefined or set to false, a value of true for this flag indicates that the name portion of the user's email address, if provided by the issuer, should be used as the new user's username. This parameter should not be set to true at the same time UseRealNameAsUserName is set to true. In this case this setting will be ignored.
MigrateUsersByUserName Default value: false If a user already exists in the database with the same user name as the authenticated user and has null values for subject and issuer, use this user, setting the subject and issuer in the database to those of the authenticated user. This is useful when the wiki previously used a different authentication mechanism. If neither this parameter nor MigrateUsersByEmail are set to true the settings for user creation will be used as described above.
MigrateUsersByEmail Default value: false If a user already exists in the database with the same email address as the authenticated user and has null values for subject and issuer, use this user, setting the subject and issuer in the database to those of the authenticated user. This is useful when the wiki previously used a different authentication mechanism. If neither this parameter nor MigrateUsersByUserName are set to true the settings for user creation will be used as described above.

RSA key example

wfLoadExtensions([ 'PluggableAuth', 'JWTAuth' ]);

$wgPluggableAuth_Config = [
    "JWTAuth Instance Name" => [
        'plugin' => 'JWTAuth',
        'data' => [
            'Algorithm' => 'RS256',
            'Key' => '-----BEGIN PUBLIC KEY-----
Key Here
-----END PUBLIC KEY-----'
        ]
    ]
];

EdDSA key example

wfLoadExtensions([ 'PluggableAuth', 'JWTAuth' ]);

$wgPluggableAuth_Config = [
    "JWTAuth Instance Name" => [
        'plugin' => 'JWTAuth',
        'data' => [
            'Algorithm' => 'EdDSA',
            'Key' => '-----BEGIN PUBLIC KEY-----
Key Here
-----END PUBLIC KEY-----'
        ]
    ]
];

Symmetric passphrase example

wfLoadExtensions([ 'PluggableAuth', 'JWTAuth' ]);

$wgPluggableAuth_Config = [
    "JWTAuth Instance Name" => [
        'plugin' => 'JWTAuth',
        'data' => [
            'Algorithm' => 'HS256',
            'Key' => 'passphrase'
        ]
    ]
];

Version 1 (standalone)

$wgJWTAuth_Algorithm
The algorithm used to encode and decode the JWT. Currently, only HS256, RS256, and EdDSA are supported. The former uses a simple passphrase, whereas the latter two use a public/private keypair. As elliptical curves cannot be cracked by quantum algorithms, we highly recommend EdDSA.
$wgJWTAuth_Key
When using a symmetric encryption algorithm like HS256, this is the shared passkey used to encode and decode the JWT.
When using an asymmetric encryption algorithm such as RS256 or EdDSA, this is the public key. (The private key would be stored on side of the issuer of the JWT.)

Integrating your auth system with JWTAuth on MediaWiki

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

  • A JWT claim must be well formed and encoded into the JWT payload format using the key that has already been agreed upon.
  • The payload must be sent in one of two ways:
    • Via an HTTP POST request with the following two requirements:
      1. The URL to make the POST request to:
      2. All of the following headers need to be included in this POST request:
        • Authorization (case sensitive, spelled the American way) with the content Bearer: JWTTOKENHERE. For instance, Bearer: eyJhbGciOiJIUzI...66Vkfljr.
        • (Version 2 only) authAction with the content login. (When doing a POST to Special:Userlogin, MediaWiki's AuthManager requires that you set the header "authAction: login" as well.)
    • Have $_SERVER['HTTP_AUTHORIZATION'] set, most likely with an Apache mod.
  • The payload must conform to the claim names promulgated by IANA: https://www.iana.org/assignments/jwt/jwt.xhtml

An example form, which could be used for testing, to submit a JWT using Version 2 is: 

<form method="post" action="{path to wiki}/Special:Userlogin">
  <input type="text" name="Authorization" value="Bearer: {JWT value}">
  <input type="hidden" name="authAction" value="login">
  <input type="submit">
</form>

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. As of JWTAuth 2.0.0, the groups claim name cannot be changed anymore.

For version 2, if you want to assign groups to a user, pass them in, separated by commas, by using the groups claim. The groups will be synced using the group sync mechanism present in PluggableAuth. To configure it, see Extension:PluggableAuth#Group_Synchronization.

Please see the README for this extension for more details.

Release notes

Version 2.1.0 - August 30, 2025
  • Fixed issue with passing header into Special:Userlogin, removed support for MW < 1.43
Version 2.0.0 - July 24, 2023
  • Updated to use PluggableAuth
Version 0.1.0 - April 6, 2023
  • Added Special:JWTLogin to read whitelist
Version 0.0.2 - February 18, 2023
  • Various fixes
Version 0.0.1 - February 17, 2023
  • Initial version


Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:JWTAuth/ja&oldid=7853540"