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.

Include header Authorization: ApiKey {my_token} when making calls. This authentication only works for REST and Action API calls.

Configure token(s)

$GLOBALS['mwsgTokenAuthenticatorServiceTokens'] = [
    [
        'token' => 'api_test_8f42d1a6e0b34b78a2f1c3de9b123abc',
        'cidr' => '127.0.0.1/32',
        'user-context' => 'MyUser',
        'api-modules' => [
            MyApi::class
        ],
        'rest-paths' => [
            '/mws/v1/some/rest/path',
        ],
    ]
];

Of these values, optional are:

cidr - if omitted, $GLOBALS['mwsgTokenAuthenticatorServiceCIDR'] will be used. It cannot be used to disable CIDR checking: if set to an empty string or an invalid range, the global value is used instead.
user-context - if omitted, $GLOBALS['mwsgTokenAuthenticatorServiceUser'] will be used.

Global settings

CIDR restriction (required)

Access is always limited to a CIDR range, configured by

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

This value must never be empty. Service tokens grant far-reaching (for AppTokens: full) access to the wiki, so they must only ever be usable from a trusted network range. Therefore:

If not configured, it defaults to 127.0.0.1/32 (local access only).
If set to an empty string, or to anything that is not a valid CIDR range, a ConfigException is thrown on setup.
Per-token cidr values cannot disable the check - invalid or empty values fall back to the global range.
Requests from IPs outside the configured range are rejected (session is not provided, token generation returns 403 Forbidden).

To allow a wider range, configure it explicitly, e.g. '10.0.0.0/8'. Note that a range like '0.0.0.0/0' effectively disables the protection and must not be used in production.

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.

When issuing and granting sessions based on these tokens, $GLOBALS['mwsgTokenAuthenticatorServiceCIDR'] = '127.0.0.1/32'; is respected, to limit access. As this token grants full access, the CIDR restriction is mandatory and cannot be disabled (see CIDR restriction).

When session is created for such token, it will be created on behalf of $GLOBALS['mwsgTokenAuthenticatorServiceUser']

Logging

Component logs into MWStake.TokenAuthenticator channel for token verification and to session for session providing.

mwstake / mediawiki-component-token-authenticator

Package info

Security

Statistics