README

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

Usage - User token

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.

Dynamic token for service authentication

As static token limits the amount of APIs you can access, in order to access full range of APIs, use dynamic token. This token is similar to a user token, but instead of being issued for a user, it's issued for a service, and can be used to authenticate the service on the behalf of the "Service user".

This tokens are always encrypted and salted, so you will need to decode it first using the salt value, to get the actual token, and callbackUrl

Generate using /mws/v1/app-token/generate.

When making requests provide header: Authorization AppToken {decoded token}. This will provide you with a full-access session.

Note that this will authenticate as user mwsgTokenAuthenticatorServiceUser. It will give this user sysop group, to ensure it can execute all APIs. If another user is assigned to this, make sure it is ok that this user gets sysop group.

mwstake / mediawiki-component-token-authenticator

Maintainers

Details