OAuth

OAuth (Open Authorization) is an open standard for authorization. It allows users to share their private resources (e.g. photos, videos, contact lists) stored on one site with another site without having to hand out their credentials. OAuth 1.0 is defined in RFC 5849

Our apis use OAuth to allow the user to give 3rd party site access to their profile information.

Getting started

The end result when using OAuth is that the requests will have an Authentication header. But before you can do that there are a few things you have to do. To generate an appropriate header for your request you need:

  1. Client credentials - you can obtain these by logging in and going to the OAuth signup page.

  2. Token credentials - to obtain these you need to interact with the end user.

    Our OAuth endpoints are:

    1. http://profile.vtt.fi/api/oauth/initiate
    2. http://profile.vtt.fi/api/oauth/authorize
    3. http://profile.vtt.fi/api/oauth/token

    Your site also needs to implement a "ready" callback URL. When the end user accepts that you'll be given the requested information, this URL will be called (with appropriate params, see the RFC).

    You'll probably wan't to use a library to do the OAuth requests. A few libraries are linked from http://oauth.net/code/. We're using the Jersey OAuth contrib package. To get that (with svn and maven installed):

    svn co https://svn.java.net/svn/jersey~svn/trunk/trunk/jersey/contribs
    cd trunk/jersey/contribs
    mvn package
    

    Then find the jars in the target dir (next to relevant src).

  3. An URL on your site that will work as callback URL for the OAuth requests.

Check out this profile api example or this low level OAuth example.

OAuth flow

[profile.vtt.fi]                                       [consumer.example.org]

  === A: obtain client credentials for the consumer.example.org application. ===

  Happens out of band (http://profile.vtt.fi/w/oauth_account/)
  
  === B: obtain token credentials for the consumer.example.org application
        to access stuff for user X ===

[profile.vtt.fi]                                       [consumer.example.org]

            <-- 1. server side call to /initiate
                    * consumer states callback url

            --> 2. request token + token secret
                    * both sides store these...  
            
            <-- 3. send end user to /authorize
                    * consumer states verifier and keeps track on who the verifier is for
            
            <--> ... wait ... 
            
            Once end user accepts the request the callback is executed
            --> 4. http://consumer.example.org/<callback>?oauth_verifier=xxx
            
            <-- 5. server side call to /token

            --> 6. access token + token secret
                    * both side store these...  associated with the user (known to consumer from step 3.)
                    
  === C: use access token to access resouces on profile.vtt.fi ===

[profile.vtt.fi]                                       [consumer.example.org]
  
            <-- 7. "Authorization: OAuth..." header set including
                   the necessary stuff
                   
            --> 8. The data requested for user X.