OAuth Pin Based Authorization for Twitter, LinkedIn, Imgur and Others - PHP OAuth API package blog

Contents

What is the Pin based OAuth Authorization?

Implementing the Pin Based OAuth Authorization in PHP

Conclusion

What is the Pin based OAuth Authorization?

Before understanding what is the pin based authorization, it is important to understand how the regular OAuth authorization flow works, so you can understand what is different.

OAuth is a protocol usually employed to access an API with the permission of a given user. So it usually starts by leading the user to a page of the application site. That page redirects the user to an authorization page on the site of the API that the application wants to access.

So for instance if you have an application that wants to call the Twitter API to retrieve information from a given user profile, you need to obtain authorization from that user to access the API on his behalf and get the information you need. So you need to tell that user to go to a page of your site. That page is handled by a script that redirects the user to the Twitter OAuth authorization page.

In that page the user is prompted by Twitter about the permissions that your site wants the user to grant to access the API on his behalf. If the user authorizes your application access to Twitter API, the user browser is redirected back to your site, so its scripts complete the OAuth authorization process.

This is the regular process. However, there are cases on which it cannot be implemented because the user cannot get back to your application using a regular browser.

For instance, a native mobile application may be able to redirect the user to access the OAuth authorization page, but then returning to the application by redirecting the broswer would not make sense because native mobile applications are not browser based.

The same goes when your application is a script that runs from the command line, desktop applications, or is a game running on a console, or is an application running on embedded system, etc..

The alternative for these cases is to use the so called Pin Based OAuth Authorization. It is similar to the regular OAuth authorization process, except that when the user is redirected to the OAuth authorization page and grants the requested API access permissions, instead of being redirected to the application site, the user gets a special code that is called the pin.

The pin code must be provided to the application somehow, so it completes the OAuth authorization process by itself without further user intervention. From then on, the application can access to the authorized API regularly.

Implementing the Pin Based OAuth Authorization in PHP

The PHP OAuth API class also supports the pin based authorization flow. It is very simple.  There are two main differences relatively to the regular OAuth authorization flow.

First you need to set the redirect_uri variable to the value 'oob'. oob means Out Of Band. It is a special value that tells the OAuth server to show the user the pin code instead of redirecting back the user to your application site.

The second difference is that you need run your authorization script setting the pin class variable to whatever the user entered as the authorization pin code. From then on the OAuth client class will complete the OAuth process without further user intervention. So this part of the process does not need to be implemented by a Web page script, like in the regular OAuth authorization process.

Lets see how this works in practice for instance with Twitter. Here is the beginning of the regular login_with_twitter.php example script adapted for pin based authorization:

 require('http.php');
 require('oauth_client.php');

 $client = new oauth_client_class;
 $client->server = 'Twitter';
 $client->redirect_uri = 'oob';
 $client->client_id = 'Your-Twitter-Application-ID-here';
 $client->client_secret = 'Your-Twitter-Application-Secret-here';

The user should access the page of this script, so he is redirected to the Twitter OAuth authorization page. When he authorizes your application access, he will see the pin code.

Your application must provide a way to let the user enter the pin code manually, so it can proceed with the process. You need to run the script above again, except that this time you need to set the pin variable to the code the user entered.

To simplify the process and reusing the same script without changing it much, this package comes with a separate script named enter_pin.php. This script presents a form to the user to let him enter the pin code.

The form also shows a select input to let the user choose which authorization script will be used after the pin is entered. Your regular application will not show this input. It was just added to this form just to make it reusable by multiple example authorization scripts.

The form script also assigns the constant OAUTH_PIN to the pin code the user entered. So the login_with_twitter.php script just needs to check if that constant is set and assign the pin variable like this:

 if(defined('OAUTH_PIN'))
  $client->pin = OAUTH_PIN;

In your real application you would not use a Web form based script to let the user enter the pin. So you need to implement the necessary code to get the pin from the user.

Conclusion

The pin based OAuth authorization process can be implemented by either OAuth 1.0a and 2.0 APIs. However, not all types of OAuth servers support the pin based authorization.

Some implement alternative solutions for when it is not possible to implement the regular OAuth authorization. You need to check the documentation of the server you want to use to see if it supports pin based authorization or not.

For now, if you have other questions, just post a comment to this article here.