oauth2-php - Step by Step Setup and Testing

My partners and I are now developing OAuth2.0 for Drupal Single-Sign-On (SSO) and Services API integration. During development we discover the oauth2-php library from Google code (http://code.google.com/p/oauth2-php/). Here a simple step-by-step setup and testing procedure.

Download the latest source code

The official package is still a OAuth2.0 draft v9 implementation (http://oauth2-php.googlecode.com/files/oauth2-php.zip). Here we will use the latest development code snippet from its Mercurial repository.

First of all you should install the mercurial package for fetching source code. In case of Debian it is very simple:

Once complete package installation just execute command as below (http://code.google.com/p/oauth2-php/source/checkout):

This will generate a directory under your current folder with name "oauth2-php". Move it to your Apache document root, e.g. ~/public_html. Don't forget that we are using PHP5.2+ PDO support so you should have it setup before testing.

Optionally, just download my package with additional patch (http://code.google.com/p/oauth2-php/issues/detail?id=9) applied: oauth2-php-1288518310.tar.gz

Setup database backend

Go to the folder "oauth2-php/server/examples/pdo" you will find a file "mysql_create_tables.sql". Just create a MySQL database as name "mydb" and create the table as below:

I guess you can handle the phpMyAdmin and corresponding permission setup, which will not detail here. Don't forget to configure the file "oauth2-php/server/examples/pdo/lib/pd0_oauth.php" as your database setup.

Install Poster for Firefox

Poster (https://addons.mozilla.org/en-US/firefox/addon/2691/) is a very simple plugin for Firefox, which can let you make HTTP request to remote server with a handy interface. Just install it. We will need it to submit POST request for token refresh.

Click "CTRL + ALT + P" will trigger the Poster interface as below:

Let's play with the oauth2-php basic authorization workflow

Well you should now get ready to test the overall oauth2-php library implementation.

First of all we should setup a client account for the connection. Take an example: now if you hope to use Facebook connect, you should first request Facebook to issue an client id/secret pair for your application, so here you are doing something similar. Access your "/oauth2-php/server/examples/pdo/addclient.php" from Firefox as below, and fill in corresponding information. Some more tips:

• Client ID is filtered by [0-9a-z-_]{3,12} (Assume you understand Regex).
• Client Secret can be anything.
• Redirect URL will be reuse during later step, here I point to "/"

Also double check the result with phpMyAdmin:

Now access your "/oauth2-php/server/examples/pdo/authorize.php" in Firefox with following syntax (An error page will be display if no correct parameter is provided):

Screen will show as below:

Once click on "Yep" you will forward to your redirect URL setup as above, with additional parameter similar as below. This step is similar as when you click on Facebook connect button, a popup show and ask for your login, then request for your authorization to let this website (i.e. application) to sign you in with Facebook SSO, access your simple profile element, send you email, and so on page.

Now you have the access token with "XBzbb1c%2FqhMDv2s0b7yKy0l8WzU4XtHT". Now access your "/oauth2-php/server/examples/pdo/protected_resource.php" with following parameter and it will show you the protected resource page:

Good! Now you can go though with basic OAuth2.0 server side implementation and demonstration!

Testing token endpoint with authorization code

Up to now we have already test with addclient.php, authorize.php and protected_resource.php, so how about the token endpoint token.php? This will be a bit more complicated and you will need the help of Poster to submit your POST request.

Before start I will strongly recommend you to have a quick review of "Section 4. Obtaining an Access Token" from original OAuth2.0 draft v10 document (http://tools.ietf.org/html/draft-ietf-oauth-v2-10#section-4).

In case of authorization code test case, first access authorize.php as below:

It will redirect you to your redirect URL with following parameter:

Now you get the authoriztion code "DR2BYUbpLAEahiwQZ7BrOVD8Ot09MWMl". Open Poster and fill in information as below:

• URL: Your token endpoint, e.g. /oauth2-php/server/examples/pdo/token.php
• Content Type: application/x-www-form-urlencoded
• Parameter Body: grant_type=authorization_code&client_id=0123456789ab&client_secret=hello world&code=DR2BYUbpLAEahiwQZ7BrOVD8Ot09MWMl&redirect_uri=/

Click on POST and it will give you a result page as below (if your code is expired, go to phpMyAdmin and hack the auth_codes.expires manually...):

Great, your get a new access token with your temporary issued authorization code :D

Testing token endpoint with password

Sorry that the bundled oauth2-php server implementation didn't handle this grant type yet. It just return FALSE in lib/oauth2.php line 200, and we should override it within our own implementation of child class, e.g. lib/pdo_oauth2.php

P.S. In case of Drupal single-sign-on with OAuth2.0 BUT not forward end-user to authorization server for login with popup, we can collect the end-user credential from web application's interface and request authorization server to bind user with this token endpoint.

Testing token endpoint with assertion

Similar as case of password endpoint, it is not yet implemented (lib/oauth2.php line 224). Let's come back later :S

Testing token endpoint with refresh token

Sorry please come back later (lib/oauth2.php line 224, 265, 273 and 278)...

Consultion

Most of the OAuth2.0 draft v10 logic are already well implemented within oauth2-php; for sure that you should fill in the missing abstract function by your own :S

With Poster you don't need to setup a custom script to test the server implementation, just a few click and kick and go :D