Flickr and OAuth

What is Flickr?
I think you landed on this page because you know what Flickr is, so let’s come to the point and discuss about the API.

Why am explaining?
Although each and everything, about API, is well documented on Flickr website here, I'm just trying to explain the whole process by dividing it into small parts.

Old Authentication API
The current Flickr authorization scheme is not the first one it used. In the early days of Flickr, users granted the power to an app to act on their behalf by giving  the apps their Flickr username and password. Doing so meant that in order to revoke  an app’s permission, users would have to change their Flickr password. Of course, doing that would also instantly revoke permissions of other third-­party apps with knowledge of the user’s password. The new authorization scheme is meant to correct obvious problems with the old scheme. Why should you as a user have to use your Flickr password for anything other than your dealings with Flickr? Why should revoking permissions to one app mean revoking permissions to other apps?

Old Authentication API will be deprecated
After July 31st, 2012 Flickr will no longer support the old Authentication API. Check here.

OAuth API
New Flickr API is based on OAuth, an open standard for authorization. In this case users are not required to submit their credentials to third party. They can allow or revoke limited permissions given to a particular app at any given time without changing their access credentials. Site like Facebook and Twitter are already using this spectrum. Flickr support OAuth 1.0a only.


Web based Application API Authentication Although Flickr provides API support for web based applications, desktop application and mobile applications. Here we will discuss only about the first one. The whole process is divided into number of steps :

1)     Get your api key

Go to the url : http://www.flickr.com/services/apps/create/apply/ and create your application. I opted for Non-commercial one. Following screen will appear :

Enter your app name and description. Click on submit button. Next screen would show you the API Key and secret.

 

2)     Configure your key

 
In figure 2 there is a ‘Edit auth flow for this app’ link. Click on it. You will get the following screen.

 
Add description, confirm app type, enter callback url and upload app logo. Save Changes.
 

3)    Make signing request and get request token : 

You must sign all requests to the Flickr API. Currently, Flickr only supports HMAC-SHA1 signature encryption. For this you have to create a base string, one of the most crucial part of API implementation.

The base string is constructed by concatenating the HTTP verb, the request URL, and all request parameters sorted by name, using lexicograhpical byte value ordering, separated by an '&'.

To make an ‘Request Token’ request we have to sent number of parameters to Flickr and if  the request is successful, Flickr would return oauth_token, oauth_token_secret and oauth_callback_confirmed.

 

Use the following code to make token request.

 

<?php

$mt                    = microtime();

$rand                  = mt_rand();

$oauth_nonce           = md5($mt . $rand);

$request_token_url     = "http://www.flickr.com/services/oauth/request_token";

$nonce                 = $oauth_nonce;

$timestamp             = gmdate('U'); //It must be UTC time

$cc_key                = "3a540b0a1863d48b8d9e484726aa8864";

$cc_secret             = "ad5ee477b09a5bb7";

$sig_method            = "HMAC-SHA1";

$oversion              = "1.0";

$callbackURL           = "http://www.techaviator.com/shiv/flickr/callback.php";

$basestring = “oauth_callback=".urlencode($callbackURL)."&oauth_consumer_key=".$cc_key."&oauth_nonce=".$nonce."&oauth_signature_method=".$sig_method."&oauth_timestamp=".$timestamp."&oauth_version=".$oversion;

$baseurl         = "GET&".urlencode($request_token_url)."&".urlencode($basestring);

$hashkey         = $cc_secret."&";

$oauth_signature = base64_encode(hash_hmac('sha1', $ baseurl, $hashkey, true));

$fields = array(

           'oauth_nonce'=>$nonce,

           'oauth_timestamp'=>$timestamp,

           'oauth_consumer_key'=>$cc_key,

           'oauth_signature_method'=>$sig_method,

           'oauth_version'=>$oversion,

           'oauth_signature'=>$oauth_signature,

           'oauth_callback'=>$callbackURL

     );

$fields_string = "";

    

//You have to encode each and every field again

foreach($fields as $key=>$value)               

$fields_string .= "$key=".urlencode($value)."&";

$fields_string = rtrim($fields_string,'&');

$url = $request_token_url."?".$fields_string;

$ch         = curl_init(); 

     $timeout    = 5; // set to zero for no timeout 

     curl_setopt ($ch, CURLOPT_URL, $url); 

curl_setopt ($ch, CURLOPT_RETURNTRANSFER, 1); 

curl_setopt ($ch, CURLOPT_CONNECTTIMEOUT, $timeout); 

$file_contents = curl_exec($ch); 

curl_close($ch); 

$rsp_arr = explode('&',$file_contents); 

print "<pre>";

print_r($rsp_arr); die;

?>

This will return you the following output :

Array

(

    [0] => oauth_callback_confirmed=true

    [1] => oauth_token=72157629276100562-4e2af5338eb15b36

    [2] => oauth_token_secret=5f943a1134aca412

)

Make a note that oauth_token is a crucial part of API and would be used 

to get Access token of users.

Note : $hashkey is a combination of secret key and oauth_token_secret 

concatenated with &. As at this step we are not having any  

oath_token_secret available so second part is empty.

$hashkey         = $cc_secret."&";

4)    Getting the User Authorization :

After getting request token now the app is ready to represent in front of it’s users. It’s done through Flickr Authorization page.

An application should never request more permissions than it needs to operate. The permissions field is a string, representing the permission level. Each level implies the level below it. Possible permissions are:

• read - permission to read private information
• write - permission to add, edit and delete photo metadata (includes 'read')
• delete - permission to delete photos (includes 'write' and 'read')

For example, the permission w allows an application to read and write on behalf of the user.
We are making request for read operation so I have used perms=read
Request Flow :

 

Use the above retrieved request token to make the request:

http://www.flickr.com/services/oauth/authorize

?oauth_token=72157629276100562-4e2af5338eb15b36&perms=read

Following screen will appear:

User will provide access credentials and would move to the next screen.

 
Click on ‘OK, I’LL Authorize IT’ and it will redirect the user to callback url we had mentioned in step 2, with two parameters oauth_token and oauth_verifier as follow :

http://www.techaviator.com/shiv/flickr/callback.php?

oauth_token=72157629276100562-4e2af5338eb15b36&oauth_verifier=8def44af662a7909

5)  Exchanging the Request Token for an Access Token :  

After the user authorizes your application, you can exchange the approved Request Token  for an Access Token. This Access Token should be stored by your application, and used to make authorized requests to Flickr.

This is only step where we are going to use request token and request token secret to get access token and access token secret. Afterwards we will use only  Access Token and Access Token Secret to get user information.

Flow :

 

You will use the parameters oauth_token and oauth_token_secret got in step 3 

and oauth_verifier got in step 4.  

You can use the following code snippet to make access token request.

<?php

…………………………………

………………………………..

$request_token_url = ‘http://www.flickr.com/services/oauth/access_token’;

$basestring = "oauth_consumer_key=".$cc_key."&oauth_nonce=".$nonce."&oauth_signature_method=".$sig_method."&oauth_timestamp=".$timestamp."&oauth_token=".$oauth_token."&oauth_verifier=".$oauth_verifier."&oauth_version=".$oversion;

$basestring = "GET&".urlencode($request_token_url)."&".urlencode($basestring);

$hashkey = $cc_secret."&".$oauth_token_secret;

$oauth_signature = base64_encode(hash_hmac('sha1', $basestring, $hashkey, true));

$fields = array(

           'oauth_nonce'=>$nonce,

           'oauth_timestamp'=>$timestamp,

           'oauth_verifier'=>$oauth_verifier,

           'oauth_consumer_key'=>$cc_key,

           'oauth_signature_method'=>$sig_method,

           'oauth_version'=>$oversion,

           'oauth_token' => $oauth_token,

           'oauth_signature'=>$oauth_signature 

     );

 $fields_string = "";

 foreach($fields as $key=>$value)    

           $fields_string .= "$key=".urlencode($value)."&";

 $fields_string = rtrim($fields_string,'&');

  

 $url = $request_token_url."?".$fields_string;

 ……………………………………

 ……………………………………

?>

If I will show the output in array, in my case, it will return following :

Array

(

    [0] => fullname=Shiv%20Modi

    [1] => oauth_token=72157629284623082-8dacad4ddbdc3fa2

    [2] => oauth_token_secret=4395d8b77ac3ee29

    [3] => user_nsid=63219840%40N08

    [4] => username=Modi%27s%20Screen

)

Here oauth_token is acess_token and oauth_token_secret is acces_token_secret. 

Store them in database for future reference and to access private data of users.

6)  Calling the Flickr API with OAuth (using access token) :

All authorization process is complete or you can say crucial part of authentication is over, a big relief!!!. Now we will use access_token, api_key and other credentials and parameters to get contact list, photo list, upload photos etc. Flickr requires HMAC-SHA1 encryption because all requests are being made insecurely using HTTP.

This is the last step of the whole process.

Here we are going to make a request to get contact list of the user.

Function : flickr.contacts.getList

I am using json format to get output in json itself.

Use following code to make request.

<?php
     ………………………………..
     ………………………………...
     $oauth_token_secret = "4395d8b77ac3ee29";
     $oauth_token        = "72157629284623082-8dacad4ddbdc3fa2";
     $basestring = "format=json&method=flickr.contacts.getList&nojsoncallback=1&oauth_consumer_key=".$cc_key."&oauth_nonce=".$nonce."&oauth_signature_method=".$sig_method."&oauth_timestamp=".$timestamp."&oauth_token=".$oauth_token."&oauth_version=".$oversion;
     $basestring = "GET&".urlencode($request_token_url)."&".urlencode($basestring);
     $hashkey    = $cc_secret."&".$oauth_token_secret;
     $oauth_signature = base64_encode(hash_hmac('sha1', $basestring, $hashkey, true));
     $fields = array(
           'method'=>'flickr.contacts.getList',
           'oauth_nonce'=>$nonce,
           'oauth_timestamp'=>$timestamp,
           'oauth_consumer_key'=>$cc_key,
           'oauth_signature_method'=>$sig_method,
           'oauth_version'=>$oversion,
           'oauth_token' => $oauth_token,
           'oauth_signature'=>$oauth_signature,
           'format'=>'json',
           'nojsoncallback'=>'1'
     );
     $fields_string = "";
     foreach($fields as $key=>$value) {
           $fields_string .= "$key=".urlencode($value)."&";
     }
     $fields_string = rtrim($fields_string,'&');
     $url           = $request_token_url."?".$fields_string;
     …………………………………
     ………………………………….
?>

If you will print the output, it would appear just like this :

{"contacts":{"page":1, "pages":1, "per_page":1000, "perpage":1000, "total":2, "contact":[{"nsid":"@user_id", "username":"@username", "iconserver":"0", "iconfarm":0, "ignored":0, "realname":"", "friend":"0", "family":"0", "path_alias":null, "location":""}, {"nsid":"@user_id", "username":"@username", "iconserver":"0", "iconfarm":0, "ignored":0, "realname":"Friend", "friend":"0", "family":"0", "path_alias":null, "location":""}]}, "stat":"ok"}

 
Congrats!!! The process gets complete.

If you wanna go in more detail, check here :

http://www.wackylabs.net/2011/12/oauth-and-flickr-part-1/
http://www.wackylabs.net/2011/12/oauth-and-flickr-part-2

written by Sam Judson, an OAuth expert.


Errors : 


1) oauth_problem=timestamp_refused (check that your time is the Unix epoch time, in seconds, and that it’s UTC, not your local time)

2) oauth_problem=nonce_used (each request to Flickr should have a unique random string identifier), or oauth_problem=signature_invalid&debug_sbs=GET&http%3A%2F%2Fwww.flickr.com...

3) signature invalid is one of the most common error you may face or i would say you will definitely face, while implementing OAuth API. If you get the signature invalid error, it means that your request is generally correct but the signature is wrong. This is a tough problem since any tiny error in the base string algorithm will completely spoil the signature. To help resolving this issue, Flickr provides its own version of the base string, which you can compare to yours. I usually compare them in a Notepad by pasting the two strings one below another.

OAuth signature looks like a random string so it’s hard to debug. Therefore before searching for other problems in your code, make sure that your signature generation algorithm works correctly.

Note : 1) Alternatively, one can obtain the response in the JSON format, using two additional parameters: format=json and nojsoncallback = 1.

2) Use proper hashkey.


At any time, if you find any problem with OAuth process, feel free to comment here. I would try to solve your problem as soon as possible.

Thanks!!!!!!!!!!! Enjoy Programming :)