Subject: [OAUTH-WG] Facebook's experience with OAuth2.0 signatures

From: Paul Tarjan <[email-masked]>
Date: Mon, 26 Jul 2010 22:18:45 +0000

Facebook released an early version of the proposed signature method, with the aim of getting real-life implementation experience. We are not currently using this for protected resource requests, but rather more like if the authorization server returned signed data as part of the access token response. 

It was generally a success with many people really liking the scheme. 

Our main takeaway is that MANY developers used normal base64 instead of base64url encoding either because they didn't read the spec thoroughly or just recognized the scheme and started decoding it. This caused weird errors which they weren't ready for (sometimes working when - and _ weren't present, sometimes cutting off some json characters when their language needed padding =, etc). 

We created an open source set of examples that developers have found helpful, and which could be incorporated into the OAuth example set: http://github.com/ptarjan/base64url

So, I suggest to keep the signature scheme, but message the fact that it isn't normal base64 VERY loudly and clearly in the spec, and to use examples that will fail hard with normal base64.

Our implementation followed the OAuth2.0 signature scheme except for 4 changes:
* signature came before payload
* not_after was renamed expires
* not all required parameters were present given the difference in use case
* the parameter was called signed_request instead of signed_token

You can read our docs here: http://developers.facebook.com/docs/authentication/canvas

Here is a few snippets of developer feedback that we had about them not understanding to use base64url instead of base64 encoding:

	---
	We're seeing bogus JSON in the new parameter. It looks like a few characters
	are being left off the end.

	---
	Imcompatible Base64 Encoding between PHP and Java (sun.misc.Base64Encoder)

	The problem was, I get an extra byte at the end of the Base64 Decoded Sig,
	comparing to the result I got from Hashing the Payload with my app secret.

	My guess is that PHP is not encoding base64 strictly following the Base64
	convention, or, Facebook has removed the tailing "=" from Sig which is required
	in most Java Base64 implementations.

	The sun.misc.Base64Decoder decoded the sig with a tailing ">", while another
	example I found from Internet tail with "0x00".
	
	---
	Isn't this just turning into a total mess - telling people that they need to
	refer to Wiki articles to use specific Base64 encode and decode functions and
	having to post chunks of code in order to try to get it working.
	
	---
	The problem is actually that there library is buggy and others actually follow
	the spec. Base64 is well defined. URLencoding is well defined. Unpadded base64
	with several character substitutions is now well defined :)

Then people started posting code to each other, some got it wrong:

	> # Ruby
	> 
	> def base64_url_decode(str) 
	>     return Base64.decode64(str.tr('-_', '+/'))
	> end
	> 

	that does not account for missing padding.  

Then someone actually read the spec:

	Facebook is following RFC. http://www.faqs.org/rfcs/rfc3548.html -
	Section 4. 
	
	That said, I don't really agree with the use of the "filename safe" style. I'd
	implement base64 with the protocol and/or filesystem specific encoding
	separated, because I don't think the spec should be concerned with that. Also,
	not many people use this style, so most libraries don't have support for it.
	But hey, I'm just one of those well-read ruby hipsters, what do I know?

We got lots of positive feedback about it:

	---
	I'm a fan *cough* of the new auth mechanism;
	
	---
	I agree that this is much cleaner. I like allowing the original request method
	to be used. I just wish things followed the actual specification or had their
	differences documented. As a library maintainer, I would also like to know
	before things like this are released.

	---
	I'm also perfectly happy with the direction FB is going here.
	
	---
	I have to say too, I'm also a big fan of the new authentication system, thank
	you. It has cut out a lot of code for us, and it's a lot easier to debug. This
	is a good verification system too.

---

From: Dick Hardt <[email-masked]>
Date: Mon, 26 Jul 2010 16:56:38 -0700

Thanks for sharing Paul!

On 2010-07-26, at 3:18 PM, Paul Tarjan wrote:

> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth

---

From: Nat Sakimura <[email-masked]>
Date: Wed, 28 Jul 2010 08:10:18 +0900

Thanks for sharing!

One question: Was there a particular reason for having signature first
instead of the payload?

On Tue, Jul 27, 2010 at 7:18 AM, Paul Tarjan <[email-masked]> wrote:
>        > # Ruby
>        >
>        > def base64_url_decode(str)
>        >     return Base64.decode64(str.tr('-_', '+/'))
>        > end
>        >
>

-- 
Nat Sakimura (=nat)
http://www.sakimura.org/en/
http://twitter.com/_nat_en

---

From: Paul Tarjan <[email-masked]>
Date: Wed, 28 Jul 2010 19:27:11 +0000

From

http://developers.facebook.com/docs/authentication/canvas

Why is the signature first?
Doing a left split is usually easier than a right one. It also allows us to pursue other encodings, like hex for the signature and percent encoding for the payload.
Why is it called signed_request?
It's the part of the HTTP request that is signed. You can remember the signature comes first in both the name of the parameter and the parameter itself.
:)
Paul

On Jul 27, 2010, at 4:10 PM, Nat Sakimura wrote:

Thanks for sharing!

On Tue, Jul 27, 2010 at 7:18 AM, Paul Tarjan <[email-masked]<mailto:[email-masked]>> wrote:
Facebook released an early version of the proposed signature method, with the aim of getting real-life implementation experience. We are not currently using this for protected resource requests, but rather more like if the authorization server returned signed data as part of the access token response.

       ---

       ---

       ---

       ---

Then people started posting code to each other, some got it wrong:

       >     return Base64.decode64(str.tr<http://str.tr>('-_', '+/'))
       > end
       >

       ---

       ---

       ---

       ---
[email-masked]<mailto:[email-masked]>