OAUTH WORKFLOW

This document describes using Oauth protocol for accessing the api methods at
flashcardexchange.com. This protocol is defined in RFC 5849
(http://tools.ietf.org/html/rfc5849) and allows owners of protected resources
at some websites delegate authorized, restricted and controlled access to these
resources.

RFC 5849 uses following terminology for describing Oauth protocol:

   client
         An HTTP client (per [RFC2616]) capable of making OAuth-
         authenticated requests.

   server
         An HTTP server (per [RFC2616]) capable of accepting OAuth-
         authenticated requests.

   protected resource
         An access-restricted resource that can be obtained from the
         server using an OAuth-authenticated request.

   resource owner
         An entity capable of accessing and controlling protected
         resources by using credentials to authenticate with the server.

   credentials
         Credentials are a pair of a unique identifier and a matching
         shared secret.  OAuth defines three classes of credentials:
         client, temporary, and token, used to identify and authenticate
         the client making the request, the authorization request, and
         the access grant, respectively.

   token
         A unique identifier issued by the server and used by the client
         to associate authenticated requests with the resource owner
         whose authorization is requested or has been obtained by the
         client.  Tokens have a matching shared-secret that is used by
         the client to establish its ownership of the token, and its
         authority to represent the resource owner.

In these terms flashcardexchange.com is a server, registered users of
flashcardexchange.com are resource owners and third-party website or services
that need access to the users resources are clients. Clients are identified at
the server with their own credentials (key and secret in oauth terminology).

An oauth server has to configure three protocol endpoints. For
flashcardexchange.com these are:
- Temporary Credential Request -
     https://secure.flashcardexchange.com/oauth_request_token;
- Resource Owner Authorization -
     https://secure.flashcardexchange.com/oauth_login;
- Token Request -
     https://secure.flashcardexchange.com/oauth_access_token.

The RFC defines three locations where oauth parameters may be transmitted: the
HTTP "Authorixation" header, HTTP request entity-body and HTTP request URI
query. The only location tested and officially supported by the
flashcardexchange.com oauth server is "Authorization' header.

Also the RFC defines three methods of digitally signing oauth requests:
"HMAC-SHA1", "RSA-SHA1", and "PLAINTEXT". The only method tested and officially
supported by the flashcardexchange.com oauth server is "HMAC-SHA1".

Let's explain the oauth workflow at the following example. A user is registered
at flashcardexchange.com with login "username" and password "userpassword". He
wants to obtain some service at (fictional) website client.example.com/service.
To provide this service client.example.com needs to access some user's cards
from flashcardexchange.com. The client may access these cards using
'get_card_set' api call, but flashcardexchange.com should be sure that the user
(and the owner of the cards) has authorized this operation.

As shown in the sequence diagram this process consists of the following steps:

1. Service request. The user sends an http request to
client.example.com/service.

2. Temporary credential request. To provide the service required the client
needs to get some cards at the server. It initiates an oauth session and sends
an http POST request to the server to obtain temporary credentials. It provides
following information in the http header "Authorization":
- oauth_consumer_key - the client idendifier at the server;
- oauth_timestamp - unix time (seconds since epoch) of this request;
- oauth_nonce - a unique random string;
- oauth_callback - a url to which the resource owner will be redirected after
  successful authentication (see step 8);
- oauth_signature_method - a method used for hashing;
- oauth_signature - a hash of the above data and the client oauth secret,
  the exact hashing algorithm is described in RFC 5849.

3. Temporary credentials. The server generates the temporary credentials for
the client and return them in the body of the http response as 'oauth_token'
and 'oauth_token_secret' parameters. The RFC also requires setting up
'oauth_callback_confirmed' parameter to differentiate from previous versions of
the protocol.

4. Redirection to authorization. The resource owner has to authorize the client
to access his cards at the server. To do this the client redirects the user
browser to the resource owner authorization url at the server. The redirection
url contains the temporary credentials identifier as the http GET parameter
'oauth_token'.

5. Resource owner authorization. The resource owner sends an http GET request
to the server using the url obtained at the previous step. The server
associates this request with the client using 'oauth_token' parameter.

6. GUI to enter the resource owner credentials. The server generates a webpage
with indication of the client requested access to the user's cards and fields
to enter the original resource owner credentials at the server.

7. Resource owner credentials. The resource owner grants access to his cards to
the client by entering his original credentials and sending them to the server
in an http request. For flashcardexchange.com this is a POST request with the
resource owner credentials passed in the request body as 'user' and 'passwd'
parameters and the temporary credentials identifier passed in the url as
'oauth_token' GET parameter.

8. Redirection to client callback. The server verifies the credentials passed
by the resource owner and if they are correct it sends a redirection response
to the resource owner. The redirection url is the callback url the client
passed to the server at step 2 as 'oauth_callback' parameter appended with
these GET parameters: the temporary credentials identifier ('oauth_token'
parameter) and a randomly generated string('oauth_verifier' parameter).

9. Client callback request. The resource owner sends an http request to the
redirection url obtained at step 8.

10. Access token request. The server has been confirmed that the resource owner
had authorized the client access to his cards and the client is ready to ask
the server for another pair of credentials, access token credentials. These
credentials allow access to the user resources at the server (cards in case of
flashcardexchange.com). The client sends an http POST request to the server
token request url with the following parameters in 'Authorization' http header:
- oauth_consumer_key - the registered identifier of the client at the server;
- oauth_timestamp - unix time (seconds since epoch) of this request;
- oauth_nonce - a unique random string;
- oauth_token - the temporary credentials identifier;
- oauth_verifier - the random string generated by the server after
authenticating the resource owner at step 8.
- oauth_signature_method - a method used for hashing;
- oauth_signature - a hash of the above data and the temporary credentials
  secret, the exact hashing algorithm is described in RFC 5849.

11. Access token. The server generates the access token credentials and sends
them back to the client in the body of the http response with 'oauth_token' and
and 'oauth_token_secret' parameters.

12. Resource access. The client requires the resource owner cards using the
access token credentials. It sends an http request to the api url with
following parameters in 'Authorization' http header:
- oauth_consumer_key - the registered identifier of the client at the server;
- oauth_timestamp - unix time (seconds since epoch) of this request;
- oauth_nonce - a unique random string;
- oauth_token - the access token identifier;
- oauth_signature_method - a method used for hashing;
- oauth_signature - a hash of the above data and the access token secret, the
  exact hashing algorithm is described in RFC 5849.
This step may repeat until the access token credentials will expire.

13. Resource. The server sends the required cards to the client in the http
response.

14. Service. The client processes the obtained cards and sends the result to
the resource owner in response to the request sent at step 9.