Add an authentication token fetching tool

I have created a very rough tool which I don't have time to post and explain until later. However, it works and I will appreciate feedback, particularly on ideal UI/workflow and any security concerns. :)

This implements the process described in the phpFlickr README. You don't have to use this, you can use the tool at http://www.phpflickr.com/tools/auth/ or run your own copy of it using PHP outside of Drupal and never need it again. This is an attempt to integrate it into the Flickr API module. I would really appreciate feedback from anyone who tries this out.

(The second patch I've attached is a merge of this tool with the authcode patch. It's probably the best one to grab if you actually want to set this code and not just generate it and have it printed to the page.)

Not sure about the workflow for this. It contains an unlock setting, which is needed to make the callback page world-readable. This is so that the Flickr auth process can hit the callback page you set. Remember to lock the utility again after using it. It should be safe from revealing the code to anonymous users. Would really appreciate some advice about what the risks are exposing this. It can probably be unlocked and locked by script anyway. As noted, it doesn't add the authentication code either, just displays it. You'll have to copy it from the screen and paste it into the settings form. Ideally it would be set automatically using variable_set().

I'm documenting how this currently works on a relevant thread rather than here. I've documented how this currently works for site admins in the next comment. It should probably end up in a README file.

And here's how I would like it all to work like a magic button. It seems possible. I haven't tried it because I only thought this through after I coded it and realised how clumsy it is, and I also want to get comments first. In particular, is there any risk this could be executed by an unauthorized user or used to get hold of a sensitive token?

Possible workflow with an easy UI:

1. The settings screen contains a button/link. It should provide instructions, a link, and a callback URL so the user knows exactly how and where to set the callback URL in flickr.com
2. The link/button takes the user to a page that runs the auth tool (currently admin/settings/flickrapi/authtool)
3. Users won't see that page, because they'll be redirected by it to Flickr
4. They'll allow the instance of the Drupal Flickr API module to receive a token
5. Flickr will return the user to a page which sets the variable (variable_set())
6. The user will be back at the module settings page where the authentication token will now be populated and ready to use.

Hmm, if I don't get comments on this I'll just code it up and see.

[The "thread" I planned to post this on was actually an issue for the Flickr module, so it seems more appropriate to explain it here. Sorry for the noise.]

The two patches merged (authtool+code, attached to comment #2) is your best option if you want to try this out, rather than review the code.

This is the official user documentation for the authtool patch. It's aimed at Drupal site admins, not necessarily the usual readers of issue queues :)

To use this tool, you have to understand some things first:

• the UX is rough, I keep saying it, that's why there are so many instructions below, but it's nothing like as difficult as understanding the process in the phpFlickr README. I want feedback in streamlining the UX, we should be able to get it to a few steps.
• it only shows the authentication token on the page, you'll need to copy it aside and then paste it into the module settings field (steps 2g-2i below)
• be careful trying it on a live site, you might unintentionally suddenly expose private photos
• I assume you've already set up an API Key on flickr.com for your Drupal Flickr API module and configured the module with it

There are two basic steps and some sub-steps:

1. Edit your flickr.com settings to use the callback page. You don't really even need to understand what that means. The setting is hard to find in Flickr and of course it may change with a UI redesign. There doesn't seem to be a direct URL I can point you to. If you are lucky, you might get straight to sub-step 1e by going to http://www.flickr.com/services/apps/by/<yourUserName> while logged in to Flickr (substitute "<yourUserName>" for your actual Flickr user name).
   a. log in to flickr.com if you already haven't
   b. select "Your Account" from the "You" dropdown menu near the top
   c. there are some "tabs" under the page heading, go to "Sharing & Extending"
   d. follow the API Keys link next to the heading "Your API Keys"
   e. select the correct API Key from the list of your API Keys - there might only be one
   * (there's every kind of UI selection device in these steps)
   f. there's a small menu called "Admin" on the right - choose "Edit the authentication flow"
   g. and now, to mix it up, a radio button menu under "App Type" - select "Web Application"
   h. type in your callback URL, which will be something like http://example.com/admin/settings/flickrapi/authtool/callback (substitute "example.com" for your site's domain or drupal installation root)
2. Get your authentication code using the tool I've built and paste it into Flickr API module settings:
   a. at your Drupal site, edit the Flickr API module settings (admin/settings/flickrapi)
   b. unlock the tool (checkbox)
   c. visit the tool at the path admin/settings/flickrapi/authtool
   d. you'll be thrown over to Flickr
   e. hopefully you're still logged in, if not log in again
   f. it will ask you to authorize the application - say "yes" please :)
   g. you'll be redirected back to your site, where you can copy your new authorization code off the page
   h. go back to Flickr API module settings (admin/settings/flickrapi)
   i. paste the code into the "Authorization token" field, re-lock the tool (checkbox) and save

That should be it. Test it by setting up a module/page with this sort of code in it:

  $flickr = flickrapi_phpFlickr();
  $photos = $flickr->people_getPhotos('me'); //should require auth
  $html = "<ul class=\"photos\">\n";
  foreach ($photos['photo'] as $photo) {
    $html .= "<li><img src=\"" . $photo['url_sq'] . "\" alt=\"" .  $photo['title'] . "\" /></li>\n";
  }
  $html .= "</ul>";

  //now go and output $html somehow

Comment #2 outlines how I'd prefer this to work from a UI point of view.

NB. I've realized I've interchangeably used "Authentication" and "Authorization" in here and possibly in the module UI. I know they're different and it's a big deal for some people. My brain can't cope with fixing it right now.