Extension:WSOAuth/For developers

From mediawiki.org
Jump to navigation Jump to search

This page explains how to develop and add a new OAuth provider to WSOAuth and how to develop WSOAuth extensions.

Creating an OAuth provider for WSOAuth[edit]

Authentication plugins must implement the AuthProvider interface class provided by WSOAuth and must implement at least the following methods:

public function login(&$key, &$secret, &$auth_url)

  • This function is called to initiate the OAuth conversion (i.e. the user has not been authenticated yet and visits the login page for the first time).
  • $key must be set to the consumer key returned by the OAuth provider.
  • $secret must be set to the consumer secret returned by the OAuth provider.
  • $auth_url must be set to the authorization URL to which the user will be redirected.
  • Must return true if the authorization grant has been successfully received, else it must return false.

An example implementation of this function:

try {
    list($auth_url, $token) = $this->client->initiate(); // From \MediaWiki\OAuthClient\Client

    $key = $token->key;
    $secret = $token->secret;

    return true;
} catch (\MediaWiki\OAuthClient\Exception $e) {
    return false;
}

public function logout(\User &$user)

  • Called when the user logs out to notify the OAuth provider, if necessary, that clean up such as removing the user's session can be performed.
  • This function shadows PluggableAuth's function deauthenticate(User $user).

public function getUser($key, $secret, &$errorMessage)

  • This function is called after login() has been executed and the user has been redirected back from the OAuth provider.
  • The purpose of this function is to retrieve the user info from the session variables set during login().
  • This function must return an array with the following format if the user info could be retrieved from the session variables set during the login() step of the authentication:
return [
    'name' => 'John', // required
    'realname' => 'John Doe', // optional
    'email' => 'john@doe.com' // optional
];
  • If the request failed, or the user is not authorised to log in, the function must return false.
  • $key is equal to $key set during login().
  • $secret is equal to $secret set during login().
  • $errorMessage can be edited to give a custom error message when the login has failed.

An example implementation of this function:

if (!isset($_GET['oauth_verifier']) {
    return false; // oauth_verifier is set by the OAuth extension. If it is not available, this means login() has not been performed.
}

try {
    $request_token = new Token($key, $secret); // From \MediaWik\OAuthClient
    $access_token = $this->client->complete($request_token, $_GET['oauth_verifier']);

    $access_token = new Token($access_token->key, $access_token->secret);
    $identity = $this->client->identify($access_token);

    return [
        "name" => $identity->username
    ];
} catch (\Exception $e) {
    return false;
}

public function saveExtraAttributes($id)

  • Called after a new user has been authenticated and added to the database to add any additional information to the database required by the OAuth provider.
  • This function shadows PluggableAuth's function saveExtraAttributes($id).

Adding a new OAuth provider to WSOAuth[edit]

You can add the OAuth provider you have developed to WSOAuth by placing the class you have written inside of extensions/WSOAuth/src/AuthenticationProvider. You must then update $wgOAuthCustomAuthProviders and $wgOAuthAuthProvider:

$wgOAuthCustomAuthProviders = [
    'google' => GoogleAuth::class // OAuth provider "google" uses class "GoogleAuth".
];

$wgOAuthAuthProvider = 'google';

You can also use the hook WSOAuthGetAuthProviders to dynamically add new auth providers. This can be handy for extension makers that do not want the site administrator to have to manually add a new auth provider.

Writing extensions[edit]

Extensions can be written to extend WSOAuth's functionality. These are different from OAuth providers, as they do not directly authenticate a user. Instead, WSOAuth extensions should alter the authentication flow by using the provided hooks:

More about how to write extensions can be found on Manual:Extensions.