2-legged OAuth System Tutorial

Use Cases:

(1) A user wants to grant data access priviledges to a third-party application.
  Here three parties are involved:
  User
    the end user
  Third-Party application
    It wants to manipulate user's data on behalf of the user.
  Service Provider
    a remote application that provides the real service.

  The procedure of granting priviledges:
  (I) complete steps described in section
      (Provider side) > (For regular users)
  (II) complete steps described in section
      (Consumer side) > (For regular users)
  Note: the public key uploaded in step (I) and private key uploaded in
  step (II) must match.

(2) A user wants to develop a third-party application for our service.
  (I) Register the application by completing steps described in section
      (Provider side) > (For thrid-party application developers)
  Now, the application can use the service.

  (II) To make use of built-in third-party application, complete steps
    described in section
      (Consumer side) > (For application manager)

(3) A user wants to use a deployed and configured third-party application.
  (I) Go to http://yourhost:yourport/oauthConsumer-0.1
  (II) Login with existing account and you will be directed to page 'account.jsp'
  (III) All supported third-party applications are listed under section
  (Available service providers). Click a link to use the corresponding
  application.

 

Consumer side

For regular users

Steps
  (1) Go to http://yourhost:yourport/oauthConsumer-0.1
  (2) Register a new account or log in with existing account
  (3) Go to account.jsp (you should be automatically directed to this page)
  (4) If it is the first time for the user to request an OAuth protected
      service via client application, the user should do some configurations.
      Click the link "Private Key Binding And Service Provider Setting"
  (5) On this page, user can do some configurations
    (5.1) UserId binding
      This setting binds local user Id to user Id used by remote service.
      For example, if a user wants to access remote Yahoo flickr service
      through a third-party app, the local user Id is the user id used by the
      third-party app and it is bound to the user Id used by Yahoo Flickr.
    (5.2) Private key setting
      Possession of private key makes the third-party app be able to access
      remote service on behalf of the user.

For application manager

Actually, only administrators should have the priviledge to manage third-party
application registry. But currently user management system is simple and all
users have the same priviledges.
Steps
  (1) Go to http://yourhost:yourport/oauthConsumer-0.1
  (2) Register a new account or log in with existing account
  (3) Go to account.jsp (you should be automatically directed to this page)
  (4) Click the link "Attributes of available service providers"
  (5) Now, the user can register a new third-party app, remove an existing
      registration and modify existing registration information.

Provider side

Currently, only one service is offered - echo service.

For regular users

Steps
  (1) Go to http://yourhost:yourport/oauthServer-0.1
  (2) Register a new account or log in with existing account
  (3) Go to account.jsp (you should be automatically directed to this page)
  (4) Click the link "Certificate Setting"
  (5) On this page, user can do some configurations
    (5.1) Third-party app priviledge setting
      Users can specify which third-party applications are allowed to access
      their data.
    (5.2) Certificate upload
      Upload your X.509 certificate (of PEM format).

For thrid-party application developers

Steps
  (1) Go to http://yourhost:yourport/oauthServer-0.1
  (2) Register a new account or log in with existing account
  (3) Go to account.jsp (you should be automatically directed to this page)
  (4) Click the link "Developer Account"
  (5) Type information of the third-party application that is to be registered.
      A consumer key/secret pair is generated as well.

Use of Public/Private key pair

There are two types of private/public key pair:
(1)
    One is used to guarantee integrity of messages transmissioned between
  third-party application and service provider.
    So for service provider, the public key is published. If a third-party
  application wants to access the service, it should use the published public
  key to sign outbound messages.
(2)
    The other is owned and deployed by end user. The goal is to provide a way so
  that third-party application can use backend service on behalf of user
  without user involvement.
    So this pair is owned by end user. To deploy the key pair:
  (*) upload the public key to service provider
  (*) upload the private key to third-party application
    Then the third-party application uses the private key to sign part of the
  message (The whole message is signed using pub/priv key pair described in
  bullet 1).

OAuth message

    ___________________________________________________________
   |                                                           |
   |     _________________________________________________     |
   |    |   ___________________________________________   |    |
   |    |  |  ______________       _________________   |  |    |
   |   P|  | |              |     |                 |  |  |    |
   |   a|  | | Payload 2    |     |  Signature (2)  |  |  |    |
   |   y|  | |______________|     |_________________|  |  |    |
   |   l|  |___________________________________________|  |    |
   |   o|                                                 |    |
   |   a|   ___________________________________________   |    |
   |   d|  |                                           |  |    |
   |    |  |                Other parts                |  |    |
   |   1|  |___________________________________________|  |    |
   |    |_________________________________________________|    |
   |     _________________________________________________     |
   |    |                                                 |    |   
   |    |       Signature (1)                             |    |
   |    |_________________________________________________|    |
   |                                                           |
   |___________________________________________________________|

In above figure, <Signature (1)> is calculated using key described in bullet 1. <Signature (2)> is calculated using key described in bullet 2.