serendipity_hq/oauth-guzzle-middleware

OAuth middleware for Guzzle (6+)

0.1.0 2016-02-17 15:35 UTC

Requires

• php: >=5.5.0
• aerendir/php-oauth-common: *
• guzzlehttp/guzzle: ~6.0

Requires (Dev)

• codeclimate/php-test-reporter: dev-master
• fabpot/php-cs-fixer: *
• phpunit/phpunit: ~4.0

MIT

• Michael Dowling
• Adamo Aerendir Crespi

• oauth
• Guzzle

README

Guzzle 6+ OAuth Middleware

Signs HTTP requests using OAuth.

This version only works with Guzzle 6.0 and up!

(Forked from https://github.com/guzzle/oauth-subscriber and separated from original repo to be able to use continuous integration server and other analysis tools).

Installing

Requires PHP OAuth extension.

This project can be installed using Composer. Add the following to your composer.json:

{
    "require": {
        "serendipity_hq/oauth-guzzle-middleware": "~0.1"
    }
}

About OAuth

From OAuth Core 1.0a:

The OAuth protocol enables websites or applications (Consumers) to access Protected Resources from a web service (Service Provider) via an API, without requiring Users to disclose their Service Provider credentials to the Consumers. More generally, OAuth creates a freely-implementable and generic methodology for API authentication.

An example use case is allowing printing service printer.example.com (the Consumer), to access private photos stored on photos.example.net (the Service Provider) without requiring Users to provide their photos.example.net credentials to printer.example.com.

OAuth does not require a specific user interface or interaction pattern, nor does it specify how Service Providers authenticate Users, making the protocol ideally suited for cases where authentication credentials are unavailable to the Consumer, such as with OpenID.

OAuth aims to unify the experience and implementation of delegated web service authentication into a single, community-driven protocol. OAuth builds on existing protocols and best practices that have been independently implemented by various websites. An open standard, supported by large and small providers alike, promotes a consistent and trusted experience for both application developers and the users of those applications.

OAuth Versions

• [2007] OAuth Core 1.0 ([DEPRECATED] Community - OAuth.net)
• [2009] OAuth Core 1.0a (Community - OAuth.net)
• [2010] OAuth Protocol 1.0 (Informational - RFC5849)
• [2012] OAuth Protocol 2.0 (Standards Track - RFC6749)

This library supports

• OAuth Core 1.0a
• OAuth Protocol 1.0 (to implement)
• OAuth Protocol 2.0 (to implement)

How to use the OAuth Core 1.0a Middleware

You can send both 2-legged and 3-legged Requests by passing or not the token and token_secret values to the OAuth* middleware.

See the Terminology paragraph on hueniverse.com for more information about n-legged requests.

For a full working example see the Twitter example.

Send a 3-legged Request

/**
 * Sends ALL THE REQUESTS authenticated with OAuth.
 * @see [docs/examples/Twitter/](docs/examples/Twitter/) for more details.
 */

use GuzzleHttp\Client;
use GuzzleHttp\Handler\CurlHandler;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware\OpenAuthentication\OAuth10a;
use GuzzleHttp\RequestOptions;

// Consumer Credentials: created at Precondition 2
$consumerKey    = 'your-consumer-key';
$consumerSecret = 'your-consumer-secret';

// Set here the access token generated at Precondition 3
$accessTokenKey    = 'your-token-key';
$accessTokenSecret = 'your-token-secret';

// The home_timeline endpoint
$resourceUrl = 'statuses/home_timeline.json';

try {
    // Instantiate the Guzzle Client and the OAuth10a middleware
    $handler = new CurlHandler();
    $stack = HandlerStack::create($handler);
    $middleware = new OAuth10a([
        'consumer_key'     => $consumerKey,
        'consumer_secret'  => $consumerSecret,
        'token'            => $accessTokenKey,
        'token_secret'     => $accessTokenSecret,
        'request_method'   => OAuth10a::REQUEST_METHOD_HEADER,
        'signature_method' => OAuth10a::SIGNATURE_METHOD_HMAC,
    ]);
    $stack->push($middleware);

    // Set the client params
    $clientParams = [
        'base_uri'                      => 'https://api.twitter.com/1.1/',
        'handler'                       => $stack,
        // Set the oauth authentication for ALL REQUESTS
        RequestOptions::AUTH            => 'oauth',
        RequestOptions::HTTP_ERRORS     => false,
        RequestOptions::DEBUG           => true,
        RequestOptions::ALLOW_REDIRECTS => ['track_redirects' => true]
    ];

    $guzzleClient = new Client($clientParams);

    $tweetsList = $guzzleClient->get($resourceUrl);
    dump(json_decode($tweetsList->getBody()->__toString(), true));
} catch (\Exception $e) {
    dump($e->getMessage());
    echo "<br/>";
    dump($e);
}

To authenticate only a single Request with OAuth middleware, remove the RequestOptions::AUTH => 'oauth' option from the $clientParams array and put it into a $requestParams array:

/**
 * @see [docs/examples/Twitter/](docs/examples/Twitter/) for more details.
 */

...

try {
    ...
    $stack->push($middleware);

    // Set the client params
    $clientParams = [
        'base_uri'                      => 'https://api.twitter.com/1.1/',
        'handler'                       => $stack,
        // Remove the option from the CLient parameters
        // RequestOptions::AUTH            => 'oauth',
        RequestOptions::HTTP_ERRORS     => false,
        RequestOptions::DEBUG           => true,
        RequestOptions::ALLOW_REDIRECTS => ['track_redirects' => true]
    ];

    $guzzleClient = new Client($clientParams);

    $requestParams = [
        RequestOptions::AUTH => 'oauth'
    ];

    // Use OAuth on a pre Request basis
    $tweetsList = $guzzleClient->get($resourceUrl, $requestParams);

    dump(json_decode($tweetsList->getBody()->__toString(), true));
} catch (\Exception $e) {
    dump($e->getMessage());
    echo "<br/>";
    dump($e);
}

Send a 2-legged Request

To send 2-legged Requests simply omit token and token_secret parameters.

/**
 * Sends ALL THE REQUESTS authenticated with OAuth.
 * @see [docs/examples/Twitter/](docs/examples/Twitter/) for more details.
 */

use GuzzleHttp\Client;
use GuzzleHttp\Handler\CurlHandler;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware\OpenAuthentication\OAuth10a;
use GuzzleHttp\RequestOptions;

// Consumer Credentials: created at Precondition 2
$consumerKey    = 'your-consumer-key';
$consumerSecret = 'your-consumer-secret';

// DO NOT SET THOSE PARAMETERS
// $accessTokenKey    = 'your-token-key';
// $accessTokenSecret = 'your-token-secret';

// The home_timeline endpoint
$resourceUrl = 'statuses/home_timeline.json';

try {
    // Instantiate the Guzzle Client and the OAuth10a middleware
    $handler = new CurlHandler();
    $stack = HandlerStack::create($handler);
    $middleware = new OAuth10a([
        'consumer_key'     => $consumerKey,
        'consumer_secret'  => $consumerSecret,
        // DO NOT SET THOSE PARAMETERS
        // 'token'            => $accessTokenKey,
        // 'token_secret'     => $accessTokenSecret,
        'request_method'   => OAuth10a::REQUEST_METHOD_HEADER,
        'signature_method' => OAuth10a::SIGNATURE_METHOD_HMAC,
    ]);
    $stack->push($middleware);

    // Set the client params
    $clientParams = [
        'base_uri'                      => 'https://api.twitter.com/1.1/',
        'handler'                       => $stack,
        // Set the oauth authentication for ALL REQUESTS
        RequestOptions::AUTH            => 'oauth',
        RequestOptions::HTTP_ERRORS     => false,
        RequestOptions::DEBUG           => true,
        RequestOptions::ALLOW_REDIRECTS => ['track_redirects' => true]
    ];

    $guzzleClient = new Client($clientParams);

    $tweetsList = $guzzleClient->get($resourceUrl);
    dump(json_decode($tweetsList->getBody()->__toString(), true));
} catch (\Exception $e) {
    dump($e->getMessage());
    echo "<br/>";
    dump($e);
}

Using the RSA-SH1 signature method

    use GuzzleHttp\Middleware\OpenAuthentication\Oauth10a;

    $stack = HandlerStack::create();

    $middleware = new Oauth10a([
        'consumer_key'           => 'my_key',
        'consumer_secret'        => 'my_secret',
        'private_key_file'       => 'my_path_to_private_key_file',
        'private_key_passphrase' => 'my_passphrase',
        'signature_method'       => Oauth10a::SIGNATURE_METHOD_RSA,
    ]);
    $stack->push($middleware);

    $client = new Client([
        'handler' => $stack
    ]);

    $response = $client->get('http://httpbin.org', ['auth' => 'oauth']);