OAuthPractical Implementation

• Pownce launched (June 2007)

• developers wanted an API

• became involved with OAuth (Aug 2007)

• public read-only API (Oct 2007)

• full API with OAuth (Mar 2008)

• 200+ apps built on Pownce API

Pownce and OAuth

• an author of the specification

• wrote first library (Python)

• maintain Python library

• maintain Pownce API OAuth implementation

Me and OAuth

What is OAuth?

A simple open standard for secure API authentication.

http://oauth.net

The (API) Love Triangle

End User

“Service Provider” “Consumer Application”

Web Service 3rd Party App

Pownce AIM bot

• Authentication

Need to log in to access parts of a website

ex: bookmark a link, post a photo, add a friend, view

a private message

• Token-based Authentication

Logged-in user has a unique token used to access

data from the site

Specifically OAuth is...

Just like...

• Flickr Auth

• Google’s AuthSub

• Yahoo’s BBAuth

• Facebook Auth

• and others...

http://flickr.com/photos/bees/2504039638/

Who is involved?

• Service Providers - have an web API that needs authorization for certain functions

• Consumers - want to use an API that requires (or encourages) OAuth

Who is it for?

Be Simple

Goals:

• standard for website API authentication

• consistent for developers

• easy for end users to understand *

* this is hard

Be Secure

Goals:

• secure for end users

• easy to implement security features for

website developers

• 3rd party developers don’t have access to

passwords

• balance security with ease of use

Be Open

Goals:

• any website can implement OAuth

• any 3rd party developer can use OAuth

• open source client libraries

• community-designed technical specifications

Be Flexible

Goals:

• authentication method agnostic

• users don’t need a username and password

• can use OpenID (or not!)

• whatever auth works best for the service

• 3rd party developers don’t handle auth

Is OAuth different from OpenID?

Yes.

(short answer)

Is OAuth different from OpenID?

(medium answer)

OpenID - user identification by provider URL, login on provider site.

OAuth - API authorization and permissions, any form of user identification, login on

provider site.

Is OAuth different from OpenID?

(long answer)

http://www.pointy-stick.com/blog/2008/03/13/explanation-difference-between-openid-and-oauth/

I’d like to search my Ma.gnolia bookmarks via social search

engine Nsyght.

What the end user sees...

Web Consumer

Ma.gnolia and Nsyght

OMG! Need to log in!

Login with service provider

alternative login methodnot username/password

service provider’s site!

Authorize

Done!

Web flow

Nsyght

asks forrequest token

returnsrequest token

Ma.gnolia

...

Request Token!

API calls

Nsyght

user sentto ma.gnolia withrequest token in

URL user logs inand/or authorizes

nsyght

Ma.gnolia

...redirected back

to nsyghtwith (authorized)

request token

Authorize!

...

http redirect

Nsyght

ask for accesstoken withauthorized

request tokenrequest tokenexchanged foraccess token

Ma.gnolia

Access Token!

nsyght storesaccess token

API calls

use the access token...

by Blaine Cook

What the end user sees...

Desktop Consumer

I’d like to get alerts about new Pownce notes via AIM.

Pownce and PownceAIM

OMG! Need to log in!

Login with service provider

service provider’s site!

Authorize

click “Okay!”

Authorized!Return to

desktop app.

Desktop flow

PownceAIM

asks forrequest token

returnsrequest token

Pownce

...

Request Token!

API calls

PownceAIM

user sentto Pownce withrequest token in

URL user logs inand/or authorizes

PownceAIM

Pownce

...user tells

PownceAIMthat auth iscomplete

Authorize!

...

user follows link

PownceAIM

ask for accesstoken withauthorized

request tokenrequest tokenexchanged foraccess token

Pownce

Access Token!

PownceAIM storesaccess token

API calls

1. Obtain request token

2. User authorizesrequest token

3. Exchange request tokenfor access token

4. Use access token toobtain protected resources

Basic Authorization Process

OAuth Setup

• Service provider gives documentation of

authorization URLs and methods

• Consumer registers an application with the

service provider

Service Provider Documentation

• Request token endpoint

• Authorization endpoint

• Access token endpoint

• Accepted request method(s) (GET, POST, PUT, etc...)

• Signature method(s)

• Extra parameters (non-oauth)

• Any specific notes about OAuth for that provider

Pownce API Documentation

https://pownce.pbwiki.com/API%20Documentation2-0#VerifyAuth

Register a Consumer Application

• Consumer gives service provider data

about the application (name, creator, url

etc...)

• Service provider assigns the application a

consumer key and consumer secret

Registering aFire Eagle Application

consumer app sign up page

https://fireeagle.yahoo.net/developer/create

Registering a Fire Eagle Application

Done!

oooh!

https://fireeagle.yahoo.net/developer/manage

OAuth Objects - Consumer

consumer key

• assigned during consumer registration• passed as a request parameter

consumer secret

• assigned during consumer registration• used for signing (e.g. HMAC-SHA1)

OAuth Objects - Consumer

OAuth Objects - Token

token key

token secret

• unique string granted by service provider• passed as a request parameter• same variable name (oauth_token_key) for both request and access type tokens

• also granted by service provider• same variable name (oauth_token_secret) for both request and access type tokens

OAuth Objects - Token

OAuth Parameters

• oauth_consumer_key

• oauth_token

• oauth_signature

• oauth_signature_method

• oauth_timestamp

• oauth_nonce

• oauth_version

Where is this information passed?

• HTTP Authorization header

• HTTP POST request body (form params)

• URL query string parameters

(in order of preference)

Timestamp and Nonce

• seconds since Unix epoch (unless otherwise specified by service provider)

• must be equal or greater than previous request

oauth_timestamp

• random string per timestamp / request

• attempt to stop replay attacks

oauth_nonce

Signing Requests

• HMAC-SHA1

• RSA-SHA1

• PLAINTEXT

oauth_signature_method

• string constructed according to the chosen signature method

oauth_signature

Signing Requests

Signature Methods

• construct the signature base string by joining the following with a ‘&’:

1. http request method (e.g. GET)

2. http url (endpoint url)

3. normalized request parameters (sorted by name)

• key = encoded consumer secret and token secret separated by an ‘&’

HMAC-SHA1

Signature Methods

HMAC-SHA1

GET&http%3A%2F%2Fapi.pownce.com%2Fauth%2Fverify.xml&oauth_consumer_key%3Dnbe958225r999a706d1u4qgwx2nx9e8j%26oauth_nonce%3DD81FBEDC-1050-40EE-B899-21A1E07C4EC5%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1211254098%26oauth_token%3D0qic7f318nj42ogm%26oauth_version%3D1.0

Signature Methods

HMAC-SHA1Example base string:

Example signature:

oauth_signature="UFHiNYSf++3N18oTZ864IAGlvxU%3D"

Signature Methods

PLAINTEXT

• should be used over a secure channel (SSL)

• no base string

• url-encoded consumer secret and token secret separated by an ‘&’

Signature Methods

PLAINTEXT

Ex:

oauth_signature=djr9rjt0jd78jf88%26jjd999tj88uiths3

Signature Methods

RSA-SHA1

• sign with Consumer’s RSA private key and the signature base string

• verify with Consumer’s RSA public key

• same signature base string as HMAC-SHA1

• still in development for most OAuth libraries

Big Fatty Example

PownceAIM and Pownce

warning: screen shots might not match text.

PownceAIM

asks forrequest token

returnsrequest token

PownceAPI call

Authorization: OAuth realm="http://api.pownce.com/",oauth_consumer_key="nbe958225r999a706d1u4qgwx2nx9e8j",oauth_signature_method="HMAC-SHA1",oauth_signature="7A4blmAxXMDPmCQuTBR4CocpdNo%3D",oauth_timestamp="1211257266",oauth_nonce="9BD703ED-EBA0-4B79-B9F2-AA09C9945D4B",oauth_version="1.0"

oauth_token_secret=f23dzf5l79o2q23y&oauth_token=3fjay66o4x78j4c8

user sentto Pownce withrequest token in

URL

user logs inand/or authorizes

PownceAIM

user follows link

PownceAIM Pownce

http://api.pownce.com/oauth/authorize?oauth_token=3fjay66o4x78j4c8

click “Okay!”

let’s pretend the user is logged in to the Pownce site

user tellsPownceAIMthat auth iscomplete

PownceAIM

cue to PownceAIM thatrequest token has been

authorized

ask for accesstoken withauthorized

request token

request tokenexchanged foraccess token

PownceAIM storesaccess token

API callsPownceAIM Pownce

Authorization: OAuth realm="http://api.pownce.com/",oauth_consumer_key="nbe958225r999a706d1u4qgwx2nx9e8j",oauth_token="3fjay66o4x78j4c8",oauth_signature_method="HMAC-SHA1",oauth_signature="6A87eXJ8MimMnCHfRM1hedEPHG4%3D",oauth_timestamp="1211258114",oauth_nonce="F85482A6-B1BC-4580-95B2-0E51300CBEF7",oauth_version="1.0"

oauth_token_secret=3w6z92eb1s86a48t&oauth_token=oixvd0538vmw3hm2

ask forprotected resource

(note list)

return APIdata

API callsPownceAIM Pownce

<?xml version="1.0" encoding="utf-8"?><notes> <note> <body>Check out my website Leah!</body> <permalink>http://pownce.com/iamcal/notes/2211344/</permalink> <sender> <user> <username>iamcal</username> ...

Authorization: OAuth realm="http://api.pownce.com/",oauth_consumer_key="nbe958225r999a706d1u4qgwx2nx9e8j",oauth_token="oixvd0538vmw3hm2",oauth_signature_method="HMAC-SHA1",oauth_signature="YXQ%2Fq3B1ZR4XOQf8bwSMh+tcSL8%3D",oauth_timestamp="1211258746",oauth_nonce="DE648679-003B-42B5-806A-F185D0714EEB",oauth_version="1.0"

Managing Tokens

• request token expiration

• access token expiration

• end user token management

Token Management

http://pownce.com/settings/applications

HTTP Errors

• 400 Bad Request

• unsupported parameter

• unsupported signature method

• missing required parameter

• duplicate OAuth parameter

• 401 Unauthorized

• invalid consumer key

• invalid / expired token

• invalid signature (signature does not match)

• invalid / used nonce

Common Errors

• signature does not match

• providers can show expected base string

• token is invalid

• expired? wrong type of token?

• request token unauthorized

• user needs to login to authorize the request token

Testing Tools

• web-based test server and client by Andy Smith (http://term.ie/oauth/example)

• Endpointr, mac desktop app by Jon Crosby

Issues

• service provider documentation

• files

• granular permissions

• timestamp and nonce verification

• vague token expiration, consumers check for expired tokens

Current Status• OAuth Core 1.0 Final (Dec 2007)

• OAuth Discovery 1.0 Draft 2

• Libraries:• coldfusion• csharp• java• javascript• maven• obj-c• obj-c1• perl• php• python• ruby

Service ProviderImplementations

• 88 Miles

• Google Contacts API

• Ma.gnolia

• Pownce

• Thmbnl

• Yahoo! Fire Eagle

http://wiki.oauth.net/ServiceProviders

More Info

• main site: http://oauth.net

• spec: http://oauth.net/core/1.0

• code: http://code.google.com/p/oauth

• mailing list: http://groups.google.com/group/oauth

• wiki: http://wiki.oauth.net

• Pownce API: http://pownce.com/api

Thanks!

ugly logo!