README

This component provides everything needed to generate random tokens for users that can be later exchanged for user information.

Usage

Generate token

REST API endpoint /mws/v1/user-token/generate can be used to generate a token for the user.

Client-side: mws.tokenAuthenticator.generateToken( withIssuer ). Params: withIssuer - boolean - default: false. If true, will include info about the wiki (url) that issued the token. To be used when verifying token, as a target for verification. If used, salt must be used.

Verify token

Call REST API endpoint /mws/v1/user-token/verify/{token} to verify the token. If valid, you will receive info on the user that the token was issued for, including user ID, username, and other info.

Verification when using salt

If token was salted, you will need to decode it using the salt, and then b64 decode it. Pass only the token from the decoded token object at verification time.

Salt

Configure $GLOBALS['mwsgTokenAuthenticatorSalt'] = '<random string>'; in your LocalSettings.php file, to salt the tokens issued by this service. This is recommended for security reasons. Note that token will only be salted if so required, not by default.

When salted, token structure is changed, instead of just a plain string token, token is a b64-encoded JSON that looks like this

[
    'verifyCallback' => $callbackUrl,
    'token' => $token,
    'sig' => $signature,
]

Where:

verifyCallback is the URL to call to verify the token, wiki that generated it.
token is the actual token
sig is the signature of the token to verify its issuer is trustworthy. Signature is a HMAC value generated by hasing verifyCallback . token with the salt.

mwstake / mediawiki-component-token-authenticator

Maintainers

Details