Using OAuth-enabled APIs with CakePHP

A growing number of APIs support OAuth, i.e. it is possible to give service A access to service B without giving B’s username/password to A. In this article I’m going to show you how to use OAuth-enabled APIs with CakePHP (and the OAuth consumer component I have written).

First, there are some preparations necessary, namely the download of the required files:

• Get the OAuth component and place its content in “app/controllers/components”
• Get the OAuth library and put it in “vendors/OAuth”

The next step is to register your application at the service provider (e.g. Yahoo’s Fire Eagle) to get consumer key and consumer secret. Those values are then stored in a class called FireEagleConsumer if we go on using Fire Eagle as example service provider in this article:

// app/controllers/components/oauth_consumers/fire_eagle_consumer.php
class FireEagleConsumer extends AbstractConsumer {
    public function __construct() {
        parent::__construct('THE KEY', 'THE SECRET');
    }
}

This class is then used by the component to access consumer key and secret.

Using an OAuth-enabled API consists of four steps:

• Get RequestToken
• Authorize RequestToken
• Exchange RequestToken for AccessToken
• Access the API using the AccessToken

In the ideal case the first three steps are performed once. But it is also possible that for example the service provider expires the AccessToken after some time, and so those steps have to be repeated.

Anyway, let’s have a look at how those steps look in code. We start with getting the RequestToken:

// app/controller/oauth_consumer_example_controller.php
class OauthConsumerExampleController extends AppController {
    public $uses = array();
    public $components = array('OauthConsumer');
	
    public function index() {
        $requestToken = $this->OauthConsumer->getRequestToken('FireEagle', 'https://fireeagle.yahooapis.com/oauth/request_token');
        $this->Session->write('requestToken', $requestToken);
    }
}

The code is probably self-explanatory, we have to add the component to the $components array, and then we get the RequestToken from the specified url (while writing this I just realized it would make sense to move the url to the FireEagleConsumer class…).

The next step is simple: we have to redirect the user to the authorize page of the service provider:

// app/controller/oauth_consumer_example_controller.php
class OauthConsumerExampleController extends AppController {
    public $uses = array();
    public $components = array('OauthConsumer');
	
    public function index() {
        $requestToken = $this->OauthConsumer->getRequestToken('FireEagle', 'https://fireeagle.yahooapis.com/oauth/request_token');
        $this->Session->write('requestToken', $requestToken);
        $this->redirect('http://fireeagle.yahoo.net/oauth/authorize?oauth_token='.$requestToken->key);
    }
}

After the RequestToken is authorized, we get redirected to a callback url we specified while registering the application. We can now exchange the authorized RequestToken for an AccessToken:

// app/controller/oauth_consumer_example_controller.php
class OauthConsumerExampleController extends AppController {
    public $uses = array();
    public $components = array('OauthConsumer');

    ...

    public function callback() {
        $requestToken = $this->Session->read('requestToken');
        $accessToken = $this->OauthConsumer->getAccessToken('FireEagle', 'https://fireeagle.yahooapis.com/oauth/access_token', $requestToken);
    }
}

In a real use case you would also save the data of the AccessToken (key and secret) to the database, so you don’t have to perform all those steps every time you want to call the API.

The last step is to call the API, in this example to get the latest location of the user:

// app/controller/oauth_consumer_example_controller.php
class OauthConsumerExampleController extends AppController {
    public $uses = array();
    public $components = array('OauthConsumer');

    ...

    public function callback() {
        $requestToken = $this->Session->read('requestToken');
        $accessToken = $this->OauthConsumer->getAccessToken('FireEagle', 'https://fireeagle.yahooapis.com/oauth/access_token', $requestToken);
        $data = $this->OauthConsumer->get('FireEagle', $accessToken->key, $accessToken->secret, 'https://fireeagle.yahooapis.com/api/0.1/user');
        // do something with the data
    }
}

That’s it. Feedback is welcome!

Update 2008-09-15: Slightly adapted for new version of the component.