PHPLeague OAuth 2.0 Client

The first library I’m going to discuss is the OAuth 2.0 Client, https://github.com/thephpleague/oauth2-client, maintained by Ben Ramsey, which is part of The PHP League. This library provides mechanisms for retrieving an access token and using a refresh token, enabling you to make requests to third party services. The providers available to this client are maintained in separate repositories and include:

• Facebook, https://github.com/league/oauth2-facebook
• GitHub, https://github.com/league/oauth2-github
• Google, https://github.com/league/oauth2-google
• Instagram, https://github.com/league/oauth2-instagram
• LinkedIn, https://github.com/league/oauth2-linkedin

The PHP League OAuth 2.0 Client also provides some options when it comes to grants, allowing this package to be used for single page JavaScript applications, applications that utilize PHP Frameworks, as well as options for internal applications. The grants shipped with this package are as follows:

• Authorization Code Grant
• Refresh Token Grant
• Client Credentials Grant
• Resource Owner Grant

Also worth noting, this project has a full suite of unit tests and is available for install via Composer at the command line

composer require league/oauth2-client:~0.3

Or in your composer.json file:

{
    "require": {
        "league/oauth2-client": "~0.3"
    }
}

This project is hosted on GitHub2. The README is full of documentation on how to use the client, so rather than duplicate the information here, please visit the repository on GitHub to review the source code and documentation.

Apigility

Apigility is a product from Zend Framework which allows you to create robust APIs very quickly. Apigility provides a GUI interface for everything you’d need to do when creating an API, including providing OAuth 2.0 authentication. Apigility is created in way that the Resource Server and Authentication server are delivered from the same API server. This is incredibly useful if you need to get an OAuth 2.0 API up and running quickly, as it will handle the creation of tokens, management of tokens, and the validation of tokens passed to the server. You can find more information about Apigility at http://www.apigility.org.

PHPLeague OAuth 2.0 Server

The other library I really wanted to highlight is from Alex Bilbie and compliments the OAuth 2.0 Client very well; it’s the OAuth 2.0 Server. This server allows you to implement an OAuth 2.0 server very easily and is very well documented. This is another case where I’m going to refer you to the documentation (because it’s good) and very specifically point out if you need an OAuth 2.0 server, this is a very strong choice.

One of the main differences and deciding factors for choosing between Apigility and OAuth 2.0 Server is availability of options. If you’ve written an API and are looking to move to OAuth 2.0 for auth, OAuth 2.0 Server will fit nicely with your existing API. If you have yet to build your API, Apigility provides a friendly interface allowing you to create the API and use OAuth 2.0 for authentication.

Foursquare

Foursquare is one of the most popular location based social networks around. Users can use their GPS-enabled smart phone to “check-in” at different locations. Some of the locations even have deals available once you check-in to their location. There’s a wealth of data here, so it only makes sense that there’s a way to retrieve and analyze it, right?

First, you need to create a new app on Foursquare at https://foursquare.com/developers/apps. The sign up form, which lists the access token and authorize URLs on the left, is shown in Figure 8.1. Once saved, the Administrative Information section of your application will have your Client ID and Client secret.

Foursquare has a public API built on the OAuth 2.0 Authorization Framework. It allows you to retrieve and create information for users, venues, check-ins, tips, lists and more. You’ll need to retrieve an access token, as outlined in Listing 8.1.

The service specific configuration for Foursquare should be replaced with:

// Service specific configuration here
$client_key = 'YOUR KEY';
$client_secret = 'YOUR SECRET';
$token_url = 'https://foursquare.com/oauth2/access_token';
// assumes this file is index.php
$redirect_uri = 'http://127.0.0.1:8080/';

To redirect users to the authorization dialog on Foursquare, the end of the script should look like:

$auth_url = "https://foursquare.com/oauth2/authenticate";
$params = [
   'client_id' => $client_key,
   'response_type' => 'code',
   'redirect_uri' => $redirect_uri,
];
$auth_url .= "?" . http_build_query($params);
Header("Location: {$auth_url}");

When a user first navigates to your script, they will be presented with the permission screen in Figure 8.2.

Once authorized, Listing 8.2 will retrieve all the recent check-ins for the people you have connected with on Foursquare. There’s a wealth of information available in these check-ins and you can use the data to create a pretty nifty looking display.

Listing 8.2

<?php
require ('vendor/autoload.php');
session_start();

// prepare our endpoint
$endpoint = 'https://api.foursquare.com/v2/checkins/recent';
$params = [
   'oauth_token' => $_SESSION['access_token'],
   // There is a 'v' value that we have to supply as
   // a yyyymmdd to indicate the expected api version. If
   // omitted, the request will be rejected
   'v' => '20140627'
];
$endpoint .= '?' . http_build_query($params);

$client = new GuzzleHttpClient();
$response = $client->get($endpoint);
$json = $response->getBody()->getContents();
// this will decode the json into an array
$data = json_decode($json, true);

// If you want to use the photo, you must request a size for
// the picture. The photo uri information comes to
// us nicely, so here's how you'd request a 200x200 picture
// to use
$recent_checkins = $data['response']['recent'];

// let's loop through all the checkins and output
// the user photos and shouts
foreach ($recent_checkins as $checkin) {
   // the shout
   echo "<h2>"
      . htmlentities($checkin['shout'], ENT_QUOTES)
      . "</h2>";
   echo "<h3> at "
      . htmlentities($checkin['venue']['name'], ENT_QUOTES)
      . "</h3>";
   // the user's photo
   $photo = $checkin['user']['photo']['prefix'];
   $photo .= '200x200';
   $photo .= $checkin['user']['photo']['suffix'];

   echo '<img src="' . $photo .'">';
}

Since we have an example of how to read data from the Foursquare API, let’s see if we can write a quick little script that allowing us to create a check-in. The checkin/add endpoint requires we send a POST request with some data in the request body. Let’s see what this looks like, as you’ll see in Listing 8.3, there’s really not much to it.

Listing 8.3

<?php
/**
 * This script is going to allow us to checkin at a venue
 * via the Foursquare API. In this example, the venue id is
 * known; but the venue end point can easily retrieve those
 * values if you don't know them.
 */
require ('vendor/autoload.php');
session_start();

// prepare our endpoint
$endpoint = 'https://api.foursquare.com/v2/checkins/add';
$params = [
   'oauth_token' => $_SESSION['access_token'],
   // There is a 'v' value that we have to supply as
   // a yyyymmdd to indicate the expected API version. If
   // omitted, the request will be rejected
   'v' => '20140627'
];
$endpoint .= '?' . http_build_query($params);

// for example sake, we're going to assume we already have
// the venue ID (RFK Stadium)
$venue_id = '4b15505bf964a5206cb023e3';

$client = new GuzzleHttpClient();
$response = $client->post(
   $endpoint,
   [
      'form_params' => [
         'shout' => 'I was here',
         'venueId' => $venue_id,
      ]
   ]
);

More information, including all the existing endpoints for the Foursquare API can be found at: https://developer.foursquare.com

GitHub

GitHub has exploded in popularity as a way to share code and projects with the world at large. Based on the popular Distributed Version Control System, git, GitHub allows developers spread all over the world to work closely together on projects. While it’s great for dispersed teams, it’s also widely used at companies where all the developers are local, due to the way it handles the integration of new code into projects.

To register an application to use GitHub’s OAuth integration, visit https://github.com/settings/applications/new. Figure 8.3 shows the registration form.

GitHub introduces a few new concepts in the way the request tokens are retrieved, so I’ve included some code demonstrating how to use the state and scopes option. If you recall, state acts as a kind of CSRF token and the scopes allow you to set the areas of the API the token can access. Listing 8.4 shows how you would go about getting the access token with GitHub.

Listing 8.4

<?php
require_once 'vendor/autoload.php';
session_start();

$client_id = 'YOUR ID';
$client_secret = 'YOUR SECRET';
$redirect_uri = 'http://127.0.0.1:8080';

$scope = 'gist,user,repo';
$state = 'bbc434234cdcdc3423432';
$client = new GuzzleHttpClient();

if (!isset($_GET['code'])) {
   $uri = 'https://github.com/login/oauth/authorize';
   $params = [
      'client_id' => $client_id,
      'redirect_uri' => $redirect_uri,
      'scope' => $scope,
      'state' => $state,
   ];
   $uri .= '?' . http_build_query($params);
   header("Location: $uri");
   exit;
}

$endpoint = "https://github.com/login/oauth/access_token";
$code = $_GET['code'];
// if the states don't match stop!
if ($state !== $_GET['state']) {
   trigger_error('CSRF Detected!', E_USER_ERROR);
}

$response = $client->post(
   $endpoint,
   [
      'form_params' => [
         'client_id' => $client_id,
         'client_secret' => $client_secret,
         'code' => $code,
         'redirect_uri' => $redirect_uri
      ]
   ]
);
$body = $response->getBody()->getContents();

// parse_str will parse the response body into the array
// $tokens. will now hold the value of the 'access_token'
parse_str($body, $tokens);

$_SESSION['access_token'] = $tokens['access_token'];

As you can see, the flow is pretty much the same, we’ve just added a few components. Now that we have our shiny, new access token, let’s use it to get some information. Let’s say we want to get a list of all the repositories we own. Assuming we’ve added the repo scope to our scopes list during the request process, we can do this very simply, see Listing 8.5.

Listing 8.5

<?php
require_once 'vendor/autoload.php';
session_start();

$access_token = $_SESSION['access_token'];

$client = new GuzzleHttpClient();
$response = $client->get(
   "https://api.github.com/user/repos",
   [
      'headers'=> [
         'Accept' => 'application/vnd.github.v3+json',
         'Authorization' => "token {$access_token}"
      ]
   ]
);
$body = json_decode($response->getBody(), true);

foreach ($body as $repo) {
   echo htmlentities($repo['name'], ENT_QUOTES) . ' '
      . htmlentities($repo['full_name'], ENT_QUOTES)
      . '<br>';
}

The script will print the name and full name of every repository we own, both public and private. If we wanted to keep our private repos out of the list we could add a query string to the URL ?type=public. If we wanted only our private repos we could use ?type=private. If we wanted to see just the repos we owned, add ?type=owner. There are sorting options as well; we can sort by created, update, pushed, and full name. You can check out https://developer.github.com/v3/repos for more information on how to interact with repositories.

Again, we’ve seen how simple it is to retrieve data from the API, but how about writing it? Let’s take a look at a new concept and actually edit a gist. GitHub is good about using the proper HTTP methods, so we can see how a PATCH request would work. For the next example, you’ll need to create a simple gist with a file name of oauth-gist.txt and some plain text content. Once created, the ID for the gist is the last component in the URL, for example:

https://gist.github.com/mfrost503/847dc6c4ea66f4fa037b

Now we can update it programatically, as shown in Listing 8.6.

Listing 8.6

<?php
require_once 'vendor/autoload.php';
session_start();

$access_token = $_SESSION['access_token'];

// ID of a gist that we can modify
$gist_id = 'e11aa9a8f4fc6b3dee80';

// prepare data for our patch
$data = [
   'description' => 'Updated Text',
   'files' => [
      'oauth-gist.txt' => [
         'content' => 'This is completely new text, right?'
      ]
   ]
];

// make the request
$client = new GuzzleHttpClient();
$response = $client->patch(
   'https://api.github.com/gists/' . $gist_id,
   [
      'headers' => [
         'Accept' => 'application/vnd.github.v3+json',
         'Authorization' => "token $access_token"
      ],
      'body' => json_encode($data)
   ]
);

// examine the response
$headers = $response->getHeaders();
echo "Status: " . $headers['Status'][0] . "<br />";

$contents = $response->getBody()->getContents();
var_dump(json_decode($contents));

As you can see, editing gists is a pretty easy process. You can use this PATCH call to rename files and also create new files, but you only need to send what you want to change, not the whole resource. If you were to use a completely new file name, a gist with that file name, description, and contents would be created.

So there you have it, a quick dive into the GitHub API, you can probably already notice some differences between the GitHub API and the Foursquare API. I assure you there more differences coming, but that said, both APIs are extremely easy to work with. If you’d like to learn about the GitHub API and some of the awesome things you can do with it, check out https://developer.github.com/v3/

Instagram

With the increasing popularity of the “selfie”, it’s good to know there is a service which allows you to upload, host, and share all your images. Instagram provides an API which allows users to view media, retrieve information, and comment on other media. The access token is very similar to the very first example provided, so we will not go through that again.

To register a new application on Instagram, go to https://www.instagram.com/developer/clients/manage/. You’ll see a form as shown in Figure 8.4.

We can reuse Listing 8.1 to get an access token to work with Instagram. The flow should be familiar; the main thing to note is Instagram requires a POST request to retrieve the access token. The updated script is shown in Listing 8.7.

Listing 8.7

<?php
/**
 * Flow for getting an Authentication Token
 * for an Instagram User.
 *
 * For these examples, we will save tokens in a session.
 * You can run it with php's dev server:
 *     php -S http://127.0.0.1:8080/
 */

require ('vendor/autoload.php');
session_start();

// Service specific configuration here
$client_key = 'YOUR APPLICATION ID';
$client_secret = 'YHOUR APPLICATION SECRET';

// you may need to whitelist the redirect_uri
$redirect_uri = 'http://127.0.0.1:8080/';

if (isset($_GET['code'])) {
   $client = new GuzzleHttpClient();

   // unlike other services, Instagram requires a POST
   $response = $client->post(
      'https://api.instagram.com/oauth/access_token',
      [
         'form_params' => [
            'client_id' => $client_key,
            'client_secret' => $client_secret,
            'grant_type' => 'authorization_code',
            'code' => $_GET['code'],
            'redirect_uri' => $redirect_uri,
         ]
      ]
   );
   // Your access token will be part of the body returned
   // from hitting this endpoint, typically via json.
   $json = $response->getBody()->getContents();
   $body = json_decode($json);
   // After this is where you would persist this token
   // in a database or session.
   $_SESSION['access_token'] = $body->access_token;
   exit;
}

// If we don't have a code, we need to request one.
$auth_url = "https://api.instagram.com/oauth/authorize/";
$params = [
   'client_id' => $client_key,
   'redirect_uri' => $redirect_uri,
   'response_type' => 'code',
];
$auth_url .= "?" . http_build_query($params);
Header("Location: {$auth_url}");

Users will be shown a screen like the one in Figure 8.5 to authorize your application.

Now that we have a valid token, we can see in Listing 8.8 how to retrieve some basic information about the user, including their profile photo.

Listing 8.8

<?php
require_once 'vendor/autoload.php';

session_start();
$access_token = $_SESSION['access_token'];

$client = new GuzzleHttpClient();

$api = 'https://api.instagram.com/v1';
$url = $api . '/users/self/'
     . '?access_token=' . $access_token;

$response = $client->get($url);
$body = $response->getBody()->getContents();
$user = json_decode($body);

echo '<h1>'
   . htmlentities($user->data->username, ENT_QUOTES)
   . '</h1>';

echo '<img src="' . $user->data->profile_picture . '">';

Simple, right? Next, we would normally do a follow up on how to create content, however, in an effort to not annoy a ton of people by liking, disliking, and commenting on photos, let’s not do that with this particular service. What I’m going to do here instead, is provide a more complex example to actually pull some media, see Listing 8.9. As always, you can explore the API documentation more after the fact if commenting is something you have an interest in doing.

Listing 8.9

<?php
require_once 'vendor/autoload.php';

session_start();
$access_token = $_SESSION['access_token'];

$client = new GuzzleHttpClient();
$base_url = "https://api.instagram.com/v1/";

// let's retrieve a list of our followers and take a look
// at the most recent media from our first follower

$follower_uri = $base_url
   . 'users/self/followed-by?access_token=' . $access_token;

$follow_response = $client->get($follower_uri);
$followers = json_decode(
   $follow_response->getBody()->getContents(), true
);
$follower_id = $followers['data'][1]['id'];

$recentmedia_uri = $base_url . 'users/' . $follower_id
   . '/media/recent?access_token=' . $access_token;

$recentmedia_response = $client->get($recentmedia_uri);
$recentmedia = json_decode(
   $recentmedia_response->getBody()->getContents(), true
);
$recentmedia_id = $recentmedia['data'][0]['id'];

$media_uri = $base_url . 'media/'
   . $recentmedia_id . '?access_token=' . $access_token;
$media_response = $client->get($media_uri);
$media = json_decode(
   $media_response->getBody()->getContents(), true
);
print $media['data']['user']['full_name'];

As you might imagine, there is far more data regarding the actual media available after the media call. You can get information about the user, links, dimensions for different resolutions of the photo, the comments, and–of course–the likes. I would encourage you to take a look at http://instagram.com/developer if you would like more information about what’s available in this API.

Reddit

Reddit is a social news network which allows registered users to post content, links, and other types of content. The users can then vote a thread up or down. People can build reputation based on how popular their posts tend to be. There’s a large contingency of programmers using Reddit regularly, but there are topics for many different interests.

To register an application to use Reddit’s OAuth support, start by visiting https://www.reddit.com/prefs/apps. Clicking on the are you a developer? create an app… button brings up the form shown in Figure 8.6.

The token process for Reddit is quite a bit different from anything we’ve seen. While the core of the process remains the same, there are a couple of different things we have to do to make the request. Listing 9 is a script we can use to get these tokens. In it, we will see how to use Basic Auth to authorize the access token request.

Listing 8.10

<?php
require_once 'vendor/autoload.php';
session_start();

$client_key = 'YOUR APPLICATION KEY';
$client_secret = 'YOUR APPLICATION SECRET';
$state = 'abvder2343fsdfewr';
$duration = 'permanent';
$scope = 'flair,history,read,vote,identity';
$redirect_uri = 'http://oauth.dev:8080/';

if (!isset($_GET['code'])) {
   $url = 'https://ssl.reddit.com/api/v1/authorize';
   $params = [
      'client_id' => $client_id,
      'response_type' => 'code',
      'state' => $state,
      'redirect_uri' => $redirect_uri,
      'scope' => $scope,
   ];
   $url .= '?' . http_build_query($params);
   header("Location: $url");
   exit;
}

$client = new GuzzleHttpClient();
// create basic authentication with client id and
// client secret
$basicAuth = base64_encode("{$client_id}:{$client_secret}");

$response = $client->post(
   'https://ssl.reddit.com/api/v1/access_token',
   [
      'headers' => [
         'Authorization' => 'Basic ' . $basicAuth
      ],
      'form_params' => [
         'grant_type' => 'authorization_code',
         'code' =>  $_GET['code'],
         'redirect_uri' => $redirect_uri,
      ]
   ]
);
$body = $response->getBody()->getContents();
$tokens = json_decode($body);
$_SESSION['access_token'] = $tokens->access_token;

It’s important to pay attention to the scopes. Many of the endpoints are scoped and there are quite a few to pick from. It’s a good idea to get acquainted with them before making the request for the tokens. When a user is authorizing your application, they’ll see them in the approval dialog, as in Figure 8.7.

The example I’m going to show for Reddit is the retrieval of your own user information, which requires the identity scope, see Listing 8.11.

Listing 8.11

<?php
require ('vendor/autoload.php');
session_start();
$access_token = $_SESSION['access_token'];

try {
   $client = new GuzzleHttpClient();
   $response = $client->get(
      'https://oauth.reddit.com/api/v1/me',
      [
         'headers' => [
            'Authorization' => 'bearer ' . $access_token
         ]
      ]
   );

   $response = $response->getBody()->getContents();
   var_dump($user);

} catch(GuzzleHttpExceptionClientException $e) {
   echo $e->getMessage();
}

You can find more information about the Reddit API at http://www.reddit.com/dev/api

YouTube

YouTube is a Google product which hosts videos and offers them for viewing. The YouTube API is part of the Google API family and has libraries for a number of different languages. To get started, visit https://console.developers.google.com/start, and in the right pop-out menu click on API Manager to register an application. Once created, you’ll need to create credentials for each API you want to use to get a secret.

While we’re not going to get into those libraries specifically, we are able to write a script to provide us with an access token, see Listing 8.12. Most Google APIs function the same way and support OAuth 2.03. Once you have the access token, you should be able to use it to access any of the APIs you’ve enabled in the Google API console.

Listing 8.12

<?php
require_once 'vendor/autoload.php';

$client_id = 'YOUR CLIENT ID';
$client_secret = 'YOUR CLIENT SECRET';
$redirect_uri = 'http://127.0.0.1:8080/';

if (!isset($_GET['code'])) {
   $params = [
      'client_id' => $client_id,
      'redirect_uri' => $redirect_uri,
      'response_type' => 'code',
      'scope' => 'https://www.googleapis.com/auth/youtube',
      'access_type' => 'offline',
   ];

   $auth_url = "https://accounts.google.com/o/oauth2/auth?"
      . http_build_query($params);
   header("Location: $auth_url");
   exit;
}

$client = new GuzzleHttpClient();
$response = $client->post(
   'https://accounts.google.com/o/oauth2/token',
   [
      'form_params' => [
         'client_id' => $client_id,
         'client_secret' => $client_secret,
         'redirect_uri' => $redirect_uri,
         'code' => $_GET['code'],
         'grant_type' => 'authorization_code',
      ]
   ]
);

$body = $response->getBody()->getContents();
$tokens = json_decode($body);

$_SESSION['access_token'] = $tokens->access_token;
$_SESSION['refresh_token'] = $tokens->refresh_token;

This pretty much sums up how to use any of the Google APIs, the following links that will help you learn more about the libraries and how to use them. Google has the most concepts to get familiar with from what we’ve seen here. This is due to the way Google has packaged their family of APIs. If you are interested in checking out the Google APIs, head over to https://developers.google.com. You can browse the APIs and read documentation about each one. You can check out the Developers console at https://console.developers.google.com; this is where you can setup a new project and configure your callbacks.