<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<chapter id="flickcurl-auth">

<title>Authenticating Flickcurl for OAuth</title>

<section id="flickcurl-auth-intro">

<title>Introduction</title>

<para>
This section describes the <emphasis>supported</emphasis>
Flickr authentication - the legacy authentication was deprecated at
the start of August 2012 and should not be used for new applications.
</para>

</section>

<section id="flickcurl-auth-build">

<title>Build Flickcurl library and <command>flickcurl(1)</command> utility</title>

<programlisting>
  $ ./configure
  $ make
</programlisting>

<para>
Add the utils directory to your shell search path:
</para>
<programlisting>
  $ PATH=`pwd`/utils:$PATH
on bourne shells such as Bash or
  $ setenv PATH `pwd`/utils:$PATH
on c shells such as tcsh
</programlisting>

<para>
You should get an error if you now try the utility:
</para>
<programlisting>
  $ flickcurl photos.getInfo 1234567
  flickcurl: Configuration file /Users/dajobe/.flickcurl.conf not found.

  ...
</programlisting>

<para>
This is because there is no configuration set for the library.  For
the <command>flickcurl(1)</command> utility, it reads the configuration from a file
<filename>~/.flickcurl.conf</filename> which contains 4 parameters used
for authentication: Client Key, Client Secret, Access Token and
Access Token Secret.  This section describes how those parameters are
obtained.
</para>

</section>


<section id="flickcurl-auth-register">

<title>Register application to get Client Key and Client Secret</title>

<para>NOTE: In the pictures below, the Flickr web site is shown in
English and the screenshots are valid as of August 2012.  Flickr
upgrade the web site now and then so these instructions may not match
the latest look.  Hopefully you can figure it out!</para>


<para>
Start by navigating to the Flickr <emphasis>App Garden</emphasis> at
<ulink url="http://www.flickr.com/services/">http://www.flickr.com/services/</ulink>
and follow the link 'Create an App' taking you to 
<ulink url="http://www.flickr.com/services/apps/create/">http://www.flickr.com/services/apps/create/</ulink>
</para>

<mediaobject>
<imageobject>
<imagedata fileref="appgarden-get-your-api-key.png" format="PNG" scale="80" align="center"/>
</imageobject>
<caption><para>Flickr App Garden - Get your API Key</para></caption>
</mediaobject>

<para>
Select the link 'Request an API Key' taking you to
<ulink url="http://www.flickr.com/services/apps/create/apply/">http://www.flickr.com/services/apps/create/apply/</ulink>
</para>

<mediaobject>
<imageobject>
<imagedata fileref="appgarden-commercial-picker.png" format="PNG" scale="80" align="center"/>
</imageobject>
<caption><para>Flickr App Garden - Commercial / Non-Commercial</para></caption>
</mediaobject>

<para>
Select either of the two buttons:
'Apply for a Non-Commercial Key' or 'Apply for a Commercial Key'
as appropriate.
</para>

<mediaobject>
<imageobject>
<imagedata fileref="appgarden-tell-us-about-your-app.png" format="PNG" scale="80" align="center"/>
</imageobject>
<caption><para>Flickr App Garden - Describe application</para></caption>
</mediaobject>

<para>
Fill in the form fields and submit it via the 'Submit' button.  
</para>

<mediaobject>
<imageobject>
<imagedata fileref="appgarden-new-api-key-secret.png" format="PNG" scale="80" align="center"/>
</imageobject>
<caption><para>Flickr App Garden - Key and Secret</para></caption>
</mediaobject>

<para>Flickr will return a page containing both the
API <emphasis>Key</emphasis> that looks something like:
</para>
<programlisting>
   0123456789abcdef0123456789abcdef
</programlisting>
<para>and <emphasis>Secret</emphasis> which looks something like:</para>
<programlisting>
   fedcba9876543210
</programlisting>

<para>
These strings should be used for the values of the Client Key
(<code>oauth_client_key</code>) and Client Secret
(<code>oauth_client_secret</code>) keys in either
the <filename>~/.flickcurl.conf</filename> if used with the <command>flickcurl(1)</command> utility
or in code, with the
<link linkend="flickcurl-set-oauth-client-key">flickcurl_set_oauth_client_key()</link>
and
<link linkend="flickcurl-set-oauth-client-secret">flickcurl_set_oauth_client_secret()</link>
functions.
</para>

<para>
You may need to change the key to be of type mobile since no callback
URL is usually appropriate for a command-line application or library.
This step is probably no longer needed since the callback is
specified in a later step.
</para>

<para>
Click the 'Edit auth flow for this app' link below the
<emphasis>Key</emphasis> and <emphasis>Secret</emphasis>
</para>


<mediaobject>
<imageobject>
<imagedata fileref="appgarden-edit-auth-flow.png" format="PNG" scale="80" align="center"/>
</imageobject>
<caption><para>Flickr App Garden - Edit authentication flow</para></caption>
</mediaobject>

<para>Change the 'App Type' to 'Mobile Application'
then set the 'Mobile Permissions' to 'Read', 'Write' Or 'Delete' as
appropriate.
</para>

<mediaobject>
<imageobject>
<imagedata fileref="appgarden-edit-auth-flow-mobile.png" format="PNG" scale="80" align="center"/>
</imageobject>
<caption><para>Flickr App Garden - Edit authentication flow: mobile</para></caption>
</mediaobject>

<para>
This sequence will make the new key 'Auth mode Mobile'
and an <emphasis>authentication URL</emphasis> will be shown on the
same page something like
<code>http://www.flickr.com/auth-11111111111111111</code>.
This URL should <emphasis>NOT</emphasis> be used and is only for
the legacy Flickr authentication flow.
</para>

<para>Finish with the 'Save Changes' button to confirm and return
you to the application page.</para>

<mediaobject>
<imageobject>
<imagedata fileref="appgarden-test-app-page.png" format="PNG" scale="80" align="center"/>
</imageobject>
<caption><para>Flickr App Garden - Application page</para></caption>
</mediaobject>

<para>
If you ever need to alter or view the authentication, use the link
'Edit the authentication flow' on right-hand side of the application page.
</para>

<para>All your Flickr applications are linked from
<ulink url="http://www.flickr.com/services/apps/by/me">http://www.flickr.com/services/apps/by/me</ulink>
</para>

</section>


<section id="flickcurl-auth-authenticate">

<title>Getting Authentication Token from Client Key and Client Secret</title>

<para>
If using the flickcurl command line tool, create a file
<filename>~/.flickcurl.conf</filename> with the two values found in
the previous section - API becomes <code>oauth_client_key</code>
and the Shared Secret becomes <code>oauth_client_secret</code> like this:
</para>

<programlisting>
  [flickr]
  oauth_client_key=0123456789abcdef0123456789abcdef
  oauth_client_secret=fedcba9876543210
</programlisting>

<para>Next the <emphasis>Request Token</emphasis>, <emphasis>Request
Token Secret</emphasis> need to be created and the
<emphasis>Authentication URL</emphasis> generated from them.
</para>

<para>The request token is created using the API request:
<link linkend="flickcurl-oauth-create-request-token">flickcurl_oauth_create_request_token()</link>
which takes an optional <emphasis>Callback URL</emphasis> argument,
that can be used for the browser to redirect to, if required.
Otherwise use <code>"oob"</code> or <code>NULL</code>.  It creates
and sets the Request Token and Request Token Secret in
the <code>flickcurl</code> object, which can be returned with:
<link linkend="flickcurl-get-oauth-request-token">flickcurl_get_oauth_request_token()</link>
and
<link linkend="flickcurl-get-oauth-request-token-secret">flickcurl_get_oauth_request_token_secret()</link>.
</para>

<programlisting>
   rc = flickcurl_oauth_create_request_token(fc, callback);
   request_token = flickcurl_get_oauth_request_token(fc);
   request_token_secret = flickcurl_get_oauth_request_token_secret(fc);
   uri = flickcurl_oauth_get_authorize_uri(fc);
</programlisting>

<para>The <command>flickcurl(1)</command> utility can also perform this
sequence with:</para>
<programlisting>
  $ flickcurl oauth-create
</programlisting>
<para>which will print the request token, request token secret and
Authentication URL.  This command takes an optional callback URL
argument.
</para>

<para>The resulting request token and secret will look like
<code>72157626737672178-022bbd2f4c2f3432</code> and
<code>fccb68c4e6103197</code> respectively.
</para>

<para>
The Authentication URL should then be used to prompt the user a web
browser to validate the request.
</para>

<para>Flickr will return a page that says something like:</para>
<programlisting>
  "[APP NAME] wants to link to your Flickr account"
</programlisting>
<para>with more information and two buttons.  Click the button
with the text:</para>
<programlisting>
  [OK, I'LL AUTHORIZE IT]
</programlisting>

<mediaobject>
<imageobject>
<imagedata fileref="appgarden-mobile-auth-page.png" format="PNG" scale="80" align="center"/>
</imageobject>
<caption><para>Flickr App Garden - Mobile Auth</para></caption>
</mediaobject>


<para>Flickr will then return the
9-digit <emphasis>Verifier</emphasis> that looks
like <code>123-456-789</code> In one of two ways depending if a
callback URL was given:</para>

<orderedlist>
    <listitem><para>Callback URL: Returns a redirect to
    the <emphasis>Callback URL</emphasis> with a query
    parameter <code>oauth_verifier</code> whose value is the
    Verifier.  The application has to extract that value and pass it
    to the flickcurl library.
    </para></listitem>

    <listitem><para>No callback URL: Will display a page that shows the 
    <emphasis>Verifier</emphasis>.  This will require the user to
    type it into the application.
    </para></listitem>
</orderedlist>

<para>
Now the Request Token, Request Token Secret and Verifier can be used
to generate the <emphasis>Access Token</emphasis> and
<emphasis>Access Token Secret</emphasis>.
</para>

<programlisting>
  /* These are required to be set for this call */
  flickcurl_set_oauth_request_token(fc, request_token);
  flickcurl_set_oauth_request_token_secret(fc, request_token_secret);

  rc = flickcurl_oauth_create_access_token(fc, verifier);
</programlisting>

<para>This sets the Access Token and Access Token Secret in
the <code>flickcurl</code> object, which can be returned with:
<link linkend="flickcurl-get-oauth-token">flickcurl_get_oauth_token()</link>
and
<link linkend="flickcurl-get-oauth-token-secret">flickcurl_get_oauth_token_secret()</link>.
The application should then store these values for use in making API
calls along with the Client Key and Client Secret.
</para>

<para>The <command>flickcurl(1)</command> utility can also perform this
verification with:</para>
<programlisting>
  $ flickcurl oauth-verify 72157626737672178-022bbd2f4c2f3432 fccb68c4e6103197 123-456-789
  flickcurl: OAuth access token returned token '72157626737672178-022bbd2f4c2f3432' secret token 'fccb68c4e6103197'
  flickcurl: Updated configuration file /Users/NAME/.flickcurl.conf with authentication token
</programlisting>

<para>It writes the resulting Access Token and Access Token Secret to
the <filename>~/.flickcurl.conf</filename> configuration file as the
<code>oauth_token</code> and <code>oauth_token_secret</code> fields
to give something like:</para>

<programlisting>
  $ cat ~/.flickcurl.conf
  [flickr]
  oauth_token=12345678901234567-abcdef0123456789
  oauth_token_secret=abcdef9876543210
  oauth_client_key=0123456789abcdef0123456789abcdef
  oauth_client_secret=fedcba9876543210
</programlisting>

<para>
At this stage, the <command>flickcurl(1)</command> utility or library is
authenticated and ready to use.
</para>

</section>


<section id="flickcurl-auth-use">

<title>Use Flickcurl</title>

<para>Now the configuration has been created and authentication
completed, the library and the <command>flickcurl(1)</command> utility will
work.
</para>

<programlisting>
  $ flickcurl photos.getInfo 1234567
  flickcurl: Found photo with URI http://www.flickr.com/photos/yogi/1234567/ ID 1234567 and 1 tags
  ...
</programlisting>

</section>

<section id="flickcurl-auth-upgrade">

<title>Upgrading from legacy Flickr authentication</title>

<para>
The <link linkend="flickcurl-auth-oauth-getAccessToken">flickcurl_auth_oauth_getAccessToken()</link>
function turns an existing legacy-authenticated application and
updates it to use OAuth.  After this call, the legacy authentication
tokens will expire within 24hrs (according to Flickr) so should no
longer be used.
</para>

<programlisting>
  rc = flickcurl_auth_oauth_getAccessToken(fc);
</programlisting>

<para>The OAuth access token and access token secret are then
saved to the <code>flickcurl</code> object and can be read via
<link linkend="flickcurl-get-oauth-token">flickcurl_get_oauth_token()</link>
and
<link linkend="flickcurl-get-oauth-token-secret">flickcurl_get_oauth_token_secret()</link>
and saved along with the Client Key (was API) and Client Secret (was
Shared Secret).
</para>

<para>The <command>flickcurl(1)</command> utility can also perform
this upgrade with:</para>
<programlisting>
  $ flickcurl oauth-upgrade
</programlisting>

<para>It writes the resulting Access Token and Access Token Secret to
the <filename>~/.flickcurl.conf</filename> configuration file as the
<code>oauth_token</code> and <code>oauth_token_secret</code> and
rewrites the <code>api_key</code> (API Key) and <code>secret</code>
(Shared Secret fields) as <code>oauth_client_key</code> (Client Key)
and <code>oauth_client_secret</code> (Client Secret) respectively.
.</para>

</section>

</chapter>

<!--
Local variables:
mode: sgml
sgml-parent-document: ("flickcurl-docs.xml" "book" "part")
End:
-->
