Use OAuth Authentication

Understanding OAuth

BibSonomy and PUMA are supporting OAuth 1.0a mechanism, also called three-legged OAuth. Actually, it's not necessary to know how it works exactly, but it's good to know some basics about this technology to prevent failures when using OAuth authentication mechanism.

A helpful overview you can find at https://github.com/Mashape/mashape-oauth/blob/master/FLOWS.md#oauth-10a-three-legged.

How to use OAuth

Be sure that the restclient-php library is installed correctly. In this case you can create a new PHP file. I would suggest to call it index.php. Include the autoloader file which is placed in composers vendor folder.

index.php

<?php
$projectPath = 'projectpath';
include $projectPath.'vendor/autoload.php';
?>

In this tutorial we're going to use PHP Sessions to save the AccessToken. The AccessToken contains encoded user credentials, which are required for API requests.

Okay, our next step is the initialization of the OAuthAdapter. Initially, we determine whether an AccessToken is not there.

index.php

<?php
use \AcademicPuma\OAuth\OAuthAdapter;

session_start(); //start session

if (empty($_SESSION['ACCESS_TOKEN'])) {
    ...
}

Is there no AccessToken, we're going to initalize the OAuthAdapter and fetch the RequestToken. We serialize this token and save it in the Session Array ($_SESSION['REQUEST_TOKEN'] = serialize($requestToken);). As soon we've got the REQUEST_TOKEN, we can start the redirect to the Host System (PUMA/BibSonomy) where the user can grant access to the API ($adapter->redirect($requestToken);).

index.php

<?php
if (empty($_SESSION['ACCESS_TOKEN'])) {

    $adapter = new OAuthAdapter([
        'consumerKey'       => CONSUMER_KEY,
        'consumerSecret'    => CONSUMER_SECRET,
        'callbackUrl'       => CALLBACK_URL,
        'baseUrl'           => BASE_URL
    ]);

    try {
        $requestToken = $adapter->getRequestToken(); //get Request Token
        $_SESSION['REQUEST_TOKEN'] = serialize($requestToken); //save Request Token in the session

    } catch(\Exception $e) {
        //do something
    }

    $adapter->redirect($requestToken); //redirect to PUMA/BibSonomy to verify user authorization
}

If there is an AccessToken in the Session Array, we can create a RestClient object directly and request the API.

index.php

<?php
if (empty($_SESSION['ACCESS_TOKEN'])) {
...
}

$accessToken = unserialize($_SESSION['ACCESS_TOKEN']); //unserialize AccessToken from the Session Array
$accessor = new OAuthAccessor(HOST, $accessToken, CONSUMER_KEY, CONSUMER_SECRET);

$restClient = new RESTClient($accessor);
$posts = $restClient->getPosts(Config\Resourcetype::BIBTEX, Config\Grouping::USER, 'stumme', ['myown'], '', '', 0, 100)->model();

var_dump($posts);

Now we have to create a callback page to which the user is redirected from the Host System. On this page we can fetch the AccessToken and save that in the Session.

I would suggest to call this page oauth_callback.php.

oauth_callback.php

<?php
$projectPath = './..';
include $projectPath.'/vendor/autoload.php';
include $projectPath.'/config.php';

use \AcademicPuma\OAuth\OAuthAdapter;

session_start(); //resume session

// Get the RequestToken from session
$requestToken = unserialize($_SESSION['REQUEST_TOKEN']);

$adapter = new OAuthAdapter([
   'consumerKey'       => CONSUMER_KEY,
   'consumerSecret'    => CONSUMER_SECRET,
   'callbackUrl'       => 'oauth_callback.php',
   'baseUrl'           => BASE_URL
]);

$accessToken = $adapter->getAccessToken($requestToken); //fetch Access Token

//persist the Access Token
$_SESSION['ACCESS_TOKEN'] = serialize($accessToken);

What happens exactly during the token exchange process?

1. We need the AccessToken in order to be permitted to request the API.
2. In order to get the AccessToken, we need the RequestToken. Therefore, we fetch the RequestToken from the Host System.
3. Once we've got the RequestToken, the user has to grant access for its account. Therefore, we initiating the redirect to the Host System.
4. Once the user has given permissions, he will be redirected to the callback script. With the permissions of the user, our script may fetch the AccessToken which we want to save in the Session Array.

I recommend to use a database to persist AccessTokens, instead of Sessions.

Be aware that every PUMA/BibSonomy user needs its own AccessToken. Thus, you have to save also the user name of the AccessToken owner.