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.

Static token for service authentication

For service-to-service authentication, you can use a static token.

Configure token

$GLOBALS['mwsgTokenAuthenticatorServiceToken'] = 'api_test_8f42d1a6e0b34b78a2f1c3de9b123abc';

Additionally, you can limit access to specific CIDR ranges by configuring

$GLOBALS['mwsgTokenAuthenticatorServiceCIDR'] = '127.0.0.1/32';

This authentication only works for REST and Action API calls.

Include header Authorization: ApiKey {my_token} when making calls.

Normally, just doing this does not allow you access to any APIs, you need to whitelist them explicitly:

Action API:

$GLOBALS['mwsgTokenAuthenticatorServiceAllowedAPIModules'] = [
	ApiOpenSearch::class
];

REST API:

$GLOBALS['mwsgTokenAuthenticatorServiceAllowedRestPaths'] = [
	'/mws/v1/user-token/verify',
];

Configuring user that the service token represents:

$GLOBALS['mwsgTokenAuthenticatorServiceUser'] = 'ChatBot service user';

This is the default user and it will be create and configured automatically. If you want to use a different user, create it manually and set this variable to the username. Due to user token limitations, only "actual" (non-system) users can be used here.

mwstake / mediawiki-component-token-authenticator

Maintainers

Details