Providing a new OAuth consumer module

The OAuth Core module allows you to easily create a new OAuth consumer. For a working example, you might want to study the code of the “oauth_test.module” shipping with the module.

Create a new OAuth consumer is very straightforward:

• Depend on the OAuth API module.
• Implement hook_oauth_info() for your consumer in a new file mymodule.oauth.inc.

That’s it. You can now register a new account, authorize or authenticate with your provider directly within drupal.

For modifying the defaults register/authenticate behavior you may implements you custom methods but those provided should be satisfy the majority.

First, you don't need to write any install file to customize the fields with your provider. While it is recommended to use the default schema provided, you can add extra field to the application entity easily.

A simple example hook_oauth_info() implementation could look like that:

<?php
function hook_oauth_info() {
  return array(
    'twitter' => array(
      'name' => t('Twitter'),
      'base' => 'twitter',
      'description' => 'Adds integration with the Twitter microblogging service.',
      'version' => '1.0',
      'token table' => array(
        'token length' => 64,
      ),
    ),
  );
}
?>

OAuth Info will let you define the token table where token credentials are stored. That is, Access Token and Secret of your users. By default OAuth is configured to use the PECL Native extension and protocol 1.0a. For a full description of what is supported @see hook_oauth_info().

Now, this basic declaration allows you to benefit from two menu callbacks: authentication and oauth_callback. Go visit your user account, under the new “External Identities” tab, and check that your module is listed. The default action will be to Add an external identity.

By default, this callback function will be declared in the same file as the oauth_info hook ($module.$group.inc) called in our case twitter.oauth.inc. Because every provider is different, you may need to store extra values or perform special authentication operation. No worry, you have the full flexibility over this. Simply implement hook_oauth_authenticate in the file specified:

<?php
/**
 * Implements hook_oauth_authenticate; Starts a Twitter authentication.
 */
function twitter_oauth_authenticate(DrupalOAuthConsumer $oauth) {
  $oauth->disableSSLChecks();

  // 1. Establish a requestToken.
  $request = $oauth->getRequestToken('https://twitter.com/oauth/request_token');

  // 2. Direct user to Service Twitter.
  if (!is_null($request) && $request['oauth_callback_confirmed']) {
    $authentication_url = 'https://twitter.com/oauth/authenticate';
    header("Location: $authentication_url?oauth_token=" . $request['oauth_token'], TRUE, 302);
  } else {
//    watchdog('twitter', $message, $variables)
  }
}
?>

You notice that the OAuth Core platform gives you an already configured and instantiated OAuth object, which might greatly reduce the complexity of developing new applications. For dev purpose, I decided to disable SSL Checkings, the first step is to establish a request token. For the step 2, I decided to use a simple Location redirection but you could write your own logic to making popping up a nice Javascript window. Notice that I performed non-OAuth 1.0a operations, such as checking the value of oauth_callback_confirmed. This is very specific to Twitter and that’s here precisely that hook are useful.

After that first operation, the user will be redirected to the twitter service provider, then the service will answer back to my callback.

<?php
/**
 * Implements hook_oauth_callback; Process an OAuth response from Twitter.
 *
 * This function basically load the user who authorized our app. Then identify
 * the user with its unique Twitter token, check for correspondence in the
 * authmap, and create a new user if the ref does not match.
 *
 * Direct call to this function is protected by a code generated on request
 * token call.
 */
function twitter_oauth_callback(DrupalOAuthConsumer $oauth) {
  $oauth->disableSSLChecks();

  // 3. Request an accessToken from Twitter.
  $access = $oauth->getAccessToken('https://twitter.com/oauth/access_token');

  // 4. Finalize the login operations.
  $oauth->authenticate($access['user_id'], $access);
}
?>

This is the basic code to process a response from the service provider. The step 3 returns an access token. Feel free to do whatever you want but don’t forget to add them in the table. When calling the authenticate method, the first parameter is the authname (the unique identifier from your provider), the second one is the full response object.