Extension:JWTAuth
このページの一部 (installation and configuration 関連) の事実の正確性は、情報が古くなったことにより損なわれている可能性があります。 |
JWTAuth リリースの状態: 安定 |
|
---|---|
実装 | 利用者識別 , 利用者権限 |
説明 | Adds support for using JSON Web Tokens to log in to MediaWiki |
作者 | Jeffrey Wang (MyWikis-JeffreyWangトーク) |
最新バージョン | 2.0.0 |
互換性の方針 | 後方互換性を維持するメイン ブランチ。 |
MediaWiki | 1.35.0+ |
データベースの変更 | はい |
ライセンス | MIT ライセンス |
ダウンロード | |
$wgJWTAuthAlgorithm, $wgJWTAuthKey, $wgJWTGroupMapping, $wgJWTAuthDebugMode |
|
四半期ごとのダウンロード数 | 0 |
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 2.0.0 was released on July 24, 2023. The extension was rewritten to use PluggableAuth.
Version 1 vs. version 2
Some users have reported version 2 is difficult to use due to the documentation being sparse. While the developers work on this, you can use version 1, which has been reported to still work very well.
- Documentation for version 1: https://www.mediawiki.org/w/index.php?title=Extension:JWTAuth&oldid=5896711
- Source code for version 1: https://github.com/jeffw16/JWTAuth/tree/v1
- Download via Git:
git clone https://github.com/jeffw16/JWTAuth -b v1
- Download via Git:
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 into the wiki's Special:JWTLogin page. It will take whatever content is POST
ed 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?
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: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' ); $wgJWTAuth_Algorithm = ''; // can be: HS256, RS256, EdDSA $wgJWTAuth_Key = ''; // Depends on which algorithm you are using
- 完了 – ウィキの「Special:Version」に移動して、拡張機能が正しくインストールされたことを確認します。
Configuration
This section is out of date - we are working on fixing this.
As of August 10, 2024, JWTAuth 2.0 doesn't use the $wgPluggableAuth_Config[]['data'] array to configure it. Instead, the extension still uses its own config variable naming format, which is explained below. (This is a legacy carried over from the original v1 implementation.)
$wgJWTAuth_Algorithm
- The algorithm used to encode and decode the JWT. Currently, only
HS256
,RS256
, andEdDSA
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.
- Find the path to your wiki's location of
Special:JWTLogin
. For instance, if your wiki is underhttps://wiki.example.com
and$wgArticlePath = "/wiki/$1";
then the location ishttps://wiki.example.com/wiki/Special:JWTLogin
. - The payload must be
POST
ed to this aforementioned URL. The URL should have a parameter calledAuthorization
with the contentBearer: JWTTOKENHERE
. For instance,Bearer: eyJhbGciOiJIUzI...66Vkfljr
. - 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
: Issueraud
: Audiencesub
: 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.
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.
See also
この拡張機能は以下のウィキ ファーム/ウィキ ホスト/パッケージに含まれています: これは正式な一覧ではありません。 一部のウィキ ファーム/ウィキ ホスト/パッケージは、ここに記載されていなくてもこの拡張機能を含んでいる場合があります。 必ずご利用のウィキ ファーム、ウィキ ホスト、バンドルで確認してください。 |
- Outdated pages/ja
- PluggableAuth plugins/ja
- Stable extensions/ja
- User identity extensions/ja
- User rights extensions/ja
- MIT licensed extensions/ja
- Extensions in Wikimedia version control/ja
- LoadExtensionSchemaUpdates extensions/ja
- All extensions/ja
- Extensions included in Canasta/ja
- Extensions by MyWikis/ja
- Login extensions/ja