What is OAuth?

OAuth is an open standard for authorization, specifically designed to work with HTTP. It’s not an authentication protocol - although it’s sometimes used as such. For authentication you could use OpenID.

OAuth deals with authorization of specific actions resources from one service to another. That could e.g. be access to content on your Facebook account, writing comments on your behalf, etc.

How to use OAuth

The following will not be an in-depth discussion of OAuth, but will serve as an example of how to use OAuth for a specific service. Specifically we will show how to use OAuth with TwentyThree™ - which is a video marketing platform with optional access restrictions to videos. TwentyThree uses OAuth version 1.0a.

When you understand the OAuth process, it should be easier to implement for other services.

The OAuth process

The OAuth process is divided in three major steps:

  1. The Consumer (light purple) server requests a request token from the Service Provider (dark purple).

  2. The user (light green) is directed to the Service Provider (dark green) with the request token, where the user grants the consumer access to services and resources.

  3. The consumer (light purple) communicates with the Service Provider (dark purple) to confirm the granted access, i.e. the Consumer receives an access token.

Color codes

Purple means that the servers communicate directly.

Green means the actions are performed in the browser.

Light colors (light purple and light green) are the Consumer, and dark colors (dark purple and dark green) are the Service Provider.

Billede1

When the Consumer has received an access token, this access token is used to perform actions or gain access to resources on the Service Provider’s server.

Let’s break it up.

1

The Drupal site obtains a request token from the Service Provider. This step is performed in the “background” for the user - the server communicates directly with each other.

If the Service Provider accepts the request, it returns a request token which can be used in the next step.

2

This step is performed in the browser. In this step the Consumer and Service Provider don’t communicate directly, but via the user’s browser. This ensures that the user doesn’t need to provide the Consumer with any credentials to the Service Provider. The user instead accepts or denies access in the Service Provider’s interface.

If the user grants access to the Service Provider’s services, the browser is directed back to the Consumer’s site.

3

Now the Consumer obtains the access token from the Service Provider.

When this step is performed, the access token is saved and used when the Consumer needs to access services from the Service Provider.

The access token has a limited timespan and needs to be renewed after a certain time limit.

Example:

Get an account

In order to test the example, you should get a TwentyThree account and read the API documentation.

Install Media 23Video OAuth

Install version 2.0 of the module Media 23Video OAuth, install requirements, and enable the module. The module is a sandbox module: https://www.drupal.org/sandbox/bartvig/2412809

You should fetch version 2 of the module with this git command:

git clone --branch 7.x-2.x bartvig@git.drupal.org:sandbox/bartvig/2412809.git media_23video_oauth

Requirements

Note that the module requires the PECL OAuth package or a library compatible with this. It also requires 23 Video for PHP for video functions after the OAuth authorization process.

The reason for this is that the PECL OAuth library is not totally compatible with TwentyThree because of naming conflicts of variables (this is out of scope for this blog post), which means we can only use PECL OAuth for the OAuth authorization of actions and resources to the TwentyThree application, but not the actual usage of actions and resources.

Furthermore, the library 23 Video for PHP doesn’t provide the OAuth authorization process, which is why we need the PECL OAuth library.

In this blog post we will only cover the authorization process and don’t need to use the 23 Video for PHP library.

Too many dependencies

The module is not perfect and it’s always annoying to have many dependencies when ideally you would only need a single dependency. For a future version of the module it would be nice to reduce the amount of libraries to use. One library should suffice.

For this blog post, though, we don’t want to capture Everything Needed to Understand OAuth, so we only want to describe the OAuth process, not fix everything in the world.

Add TwentyThree application/user

When you have installed the module, you need to connect the Drupal site with an application on TwentyThree. On TwentyThree you can setup several different applications. An application is basically an external site (from the view of TwentyThree) that has access to one or more channels on your TwentyThree account. You can set this up on your TwentyThree account on http://account.23video.com/profile/applications

Billede2

You need the consumer key and consumer secret for the Drupal module. The consumer key in this example is 12345678-xXxXxXxXxX.

 

Billede3

On http://yourdrupalsite/admin/config/media/media-23video add this consumer key and consumer secret.

Billede4

You connect to the application mentioned above, and through the OAuth process you can choose to grant access.

Billede6

That’s how easy it is to use OAuth.

Add roles

Now we just need to add what roles have access to this TwentyThree application. This is performed under “settings” for the just generated TwentyThree application.

Billede7

After adding the administrator role, it looks like this:

Billede8

Code

You probably want to see some code, so let’s look at some code.

The initial OAuth form

The first step is typing in the consumer key and consumer secret, which is just a basic Drupal form.

git clone --branch 7.x-2.x bartvig@git.drupal.org:sandbox/bartvig/2412809.git media_23video_oauth

Nothing fancy here. In the submit handler it starts to become interesting.

Submit handler

function media_23video_oauth_authorize_submit($form, &$form_state) { 
  global $base_url; $oauth = new OAuth($form_state['values']['consumer']['consumer_key'], $form_state['values']['consumer']
  ['consumer_secret']); try { $request = $oauth->getRequestToken('http://api.visualplatform.net/oauth/request_token',  $base_url . '/admin/config/media/media-23video/oauth-callback'); 
  if ($request['oauth_callback_confirmed'] == TRUE) { 
      media_23video_oauth_application_add($form_state['values']['consumer']['consumer_key'], $form_state['values']['consumer']['consumer_secret'], $request['oauth_token'], $request['oauth_token_secret']);
      $form_state['redirect'] = 'http://api.visualplatform.net/oauth/authorize?oauth_token=' .       check_plain($request['oauth_token']); } } catch { … } 
}

We use the consumer key and secret to instantiate an OAuth object and request a Request Token from the Consumer with the url to TwentyThree’s request token function and an url to our Drupal site’s OAuth callback function.

This is step 1 in the figure from the top of the post, which is performed on the server. The redirect is the first line in step 2. The next paragraph deals with the last part of step 2 and step 3.

The left out code adds the application information we have so far to the database. When the user grants access to the application on the TwentyThree interface, it will be updated with the received access token.

OAuth authorization callback function

function media_23video_oauth_authorize_callback() {
  global $base_url; $params = drupal_get_query_parameters(); 
  $application = media_23video_oauth_application_get_by_oauth_token($params['oauth_token']); 
   if (!$application) { 
      drupal_set_message(t("Application/user doesn't exist"), 'error'); 
      drupal_goto('admin/config/media/media-23video'); } // Create OAuth object and set tokens. 
      $oauth = new OAuth($application->consumer_key, $application->consumer_secret); 
      $oauth->setToken($application->oauth_token, $application->oauth_token_secret); try { 
         $response = $oauth->getAccessToken('http://api.visualplatform.net/oauth/access_token', NULL, $params['oauth_verifier']); 
    } 
      catch { … } // Update application in database.
}

This is the last part of step 2. The Service Provider (TwentyThree) redirects to the callback function, which uses the verifier token obtained from TwentyThree to request an Access Token.

When the Drupal site gets the Access Token, the TwentyThree application is updated in the database and we’re done. The OAuth process has finished.

OAuth is easy

As you can see, when you have wired your head around the OAuth process it’s not really that difficult to use, and you don’t need a lot of code.