Subject: [OAUTH-WG] Feedback on JSON Web Token (JWT) draft -01

From: Jeff Lindsay <[email-masked]>
Date: Thu, 6 Jan 2011 19:29:14 -0800

Hi everyone!

I'm really excited about this spec (and OAuth2), as are others here at
Twilio. I've been watching it since Paul implemented an early version at
Facebook. We also implemented it in an early iteration of a product we're
working on, but now we're coming back to it as a means of authentication
that would be key to the entire Twilio API... and since our API *is* our
product, we're very touchy about the details.

I've only been glancing at its progress since the early drafts as various
versions were integrated and issues sorted out. I was afraid that it was
going to have gotten a lot more complicated, but looking at this I'm pretty
happy to see most of the additions are optional.

Like Paul, I'm not a fan of the short names. However, I've sort of accepted
it, especially since as reserved keys they are less likely to conflict with
keys we want to put in.

The big problem we have, though, is that the header is required. We're
debating going with JWT or our own method that is loosely based on JWT, but
doesn't use JSON and results in smaller tokens and a simpler process (for
example, you only do one base64url encoding of the final string). We think
we'd gain better room for additions to our payload, and better readability
(therefore learnability/usability) by using JSON, that it might be worth the
tradeoff in token size and several encoding steps. At that point, we'd
basically be JWT except for the fact we really don't need the header.

Facebook's implementation and one of the original proposals let the
algorithm key live in the payload. Since this is the only thing required in
the header, allowing it as an optional key in the payload would allow the
entire header to be optional. This would really help us out since we need a
process that is as simple as humanly possible.

If you need to detect if a JWT has a header, you can just check for the
number of periods in the JWT. But I really think the header should be
optional if you specify the alg in the payload. There may have been some
issues reserving the key "algorithm", but I think if we go with short names,
"alg" is much less likely to cause conflicts.

--
Jeff Lindsay

On Tue, Jan 4, 2011 at 6:31 PM, Mike Jones <[email-masked]>wrote:

>  Draft -01 of the JSON Web Token (JWT) specification<http://self-issued.info/docs/draft-jones-json-web-token.html>is now available.  This version incorporates the consensus decisions reached
> at the Internet Identity Workshop.  The remaining open issues and to-do
> items are documented in Section 12<http://self-issued.info/docs/draft-jones-json-web-token-01.html#TBD>.
> As a reminder, the suggested pronunciation of JWT is the same as the English
> word "jot".
>
>
>
> The draft is available at these locations:
>
>   - http://www.ietf.org/internet-drafts/draft-jones-json-web-token-01.txt
>
>   - http://www.ietf.org/internet-drafts/draft-jones-json-web-token-01.xml
>
>   - http://self-issued.info/docs/draft-jones-json-web-token-01.html
>
>   - http://self-issued.info/docs/draft-jones-json-web-token-01.txt
>
>   - http://self-issued.info/docs/draft-jones-json-web-token-01.xml
>
>   - http://self-issued.info/docs/draft-jones-json-web-token.html (will
> point to new versions as they are posted)
>
>   - http://self-issued.info/docs/draft-jones-json-web-token.txt (will
> point to new versions as they are posted)
>
>   - http://self-issued.info/docs/draft-jones-json-web-token.xml (will
> point to new versions as they are posted)
>
>   - http://svn.openid.net/repos/specifications/json_web_token/1.0/(Subversion repository, with html, txt, and html versions available)
>
>
>
> The decisions reached at IIW are documented here:
>
>   - JSON Token Spec Results at IIW:  http://self-issued.info/?p=361
>
>   - JSON Token Encryption Spec Results at IIW:
> http://self-issued.info/?p=378
>
>   - JSON Token Naming Spec Results at IIW:  http://self-issued.info/?p=386
>
>   - JSON Public Key Spec Results at IIW:  http://self-issued.info/?p=390
>
>
>
> This announcement is also posted here:
>
>   - http://self-issued.info/?p=446
>
>
>
> Thanks to all who provided the input that led to this draft!  Feedback is
> highly welcome.
>
>
>
>                                                                 -- Mike
>
>
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth
>
>

---

From: Dick Hardt <[email-masked]>
Date: Fri, 7 Jan 2011 10:42:23 -0800

Hi Jeff

Thanks for the feedback. A healthy debate is how we optimize a spec!

Will a slightly shorter token be significant for you?  Is the rest of the message so short that a smaller token will have a significant impact?

The hope is that if we standardize JWT, that libraries will be developed so that the average developer does not need to deal with the details. 

We are having to balance between a generalized solution and a simple, specific solution. 

Too specific and the spec does not solve a broad enough set of people's needs, libraries don't get developed, or if they do, the code coverage is nominal and they are not well maintained. This leads to more security risks and higher barrier to deployment.

Too generic and the complexity in the library adds more security risks, less likely someone will implement a library and deploy.

The header makes it easy for a generic library to quickly see what the rest of the token is, enables support for encrypted payloads (can't do that if the crypto info is in the payload), and provides a simple path for extensions / expansion.

While I can appreciate doing less encodings operations, the encoding is already being used, so this is a slight additional computational overhead. Your suggestion for checking the number of periods may actually add back the computational overhead, and a separate code path to be tested leading to less secure code. Happy to elaborate more if that was not clear and compelling!

-- Dick

On 2011-01-06, at 7:29 PM, Jeff Lindsay wrote:

> Hi everyone!
> 
> I'm really excited about this spec (and OAuth2), as are others here at Twilio. I've been watching it since Paul implemented an early version at Facebook. We also implemented it in an early iteration of a product we're working on, but now we're coming back to it as a means of authentication that would be key to the entire Twilio API... and since our API *is* our product, we're very touchy about the details.  
> 
> I've only been glancing at its progress since the early drafts as various versions were integrated and issues sorted out. I was afraid that it was going to have gotten a lot more complicated, but looking at this I'm pretty happy to see most of the additions are optional. 
> 
> Like Paul, I'm not a fan of the short names. However, I've sort of accepted it, especially since as reserved keys they are less likely to conflict with keys we want to put in. 
> 
> The big problem we have, though, is that the header is required. We're debating going with JWT or our own method that is loosely based on JWT, but doesn't use JSON and results in smaller tokens and a simpler process (for example, you only do one base64url encoding of the final string). We think we'd gain better room for additions to our payload, and better readability (therefore learnability/usability) by using JSON, that it might be worth the tradeoff in token size and several encoding steps. At that point, we'd basically be JWT except for the fact we really don't need the header.
> 
> Facebook's implementation and one of the original proposals let the algorithm key live in the payload. Since this is the only thing required in the header, allowing it as an optional key in the payload would allow the entire header to be optional. This would really help us out since we need a process that is as simple as humanly possible. 
> 
> If you need to detect if a JWT has a header, you can just check for the number of periods in the JWT. But I really think the header should be optional if you specify the alg in the payload. There may have been some issues reserving the key "algorithm", but I think if we go with short names, "alg" is much less likely to cause conflicts. 
> 
> --
> Jeff Lindsay
> 
> On Tue, Jan 4, 2011 at 6:31 PM, Mike Jones <[email-masked]> wrote:
> Draft -01 of the JSON Web Token (JWT) specification is now available.  This version incorporates the consensus decisions reached at the Internet Identity Workshop.  The remaining open issues and to-do items are documented in Section 12.  As a reminder, the suggested pronunciation of JWT is the same as the English word "jot".
> 
>  
>   - http://self-issued.info/docs/draft-jones-json-web-token.html (will point to new versions as they are posted)
> 
>   - http://self-issued.info/docs/draft-jones-json-web-token.txt (will point to new versions as they are posted)
> 
>   - http://self-issued.info/docs/draft-jones-json-web-token.xml (will point to new versions as they are posted)
> 
>   - http://svn.openid.net/repos/specifications/json_web_token/1.0/ (Subversion repository, with html, txt, and html versions available)
> 
>  
>   - JSON Token Encryption Spec Results at IIW:  http://self-issued.info/?p=378
> 
> Thanks to all who provided the input that led to this draft!  Feedback is highly welcome.
> 
>  
>                                                                 -- Mike
> 
> 
>

---

From: Jeff Lindsay <[email-masked]>
Date: Mon, 10 Jan 2011 12:09:27 -0800

Dick, thanks for the response.

I think I'm behind everything you've said. Perhaps the crux is in library vs
user/developer implementation. I'm interested in less steps not for
computational overhead, but for mental overhead and usability. I would love
to have (and even contribute) standard libraries in various languages (we'll
have to anyway if we do adopt this), but for now because we're an API (like
Facebook) and our docs are about using our API. They assume all you need are
the standard libraries in most programming environments.

Right now, that means users implementing JWTs by hand. While we have
libraries for our APIs, we have to design the API so that you don't *have*
to use these libraries... otherwise, we might as well be a SOAP web
service.

So I'm wondering what people's idea are on how to start using/implementing
this now without standard libraries, assuming we don't want to make the
process any easier. My hypothesis is the response from you all will be,
"just have the JWT process in your docs, it's easy enough. We're not worried
about this odd phase of early adoption with no standard library."

-jeff

On Fri, Jan 7, 2011 at 10:42 AM, Dick Hardt <[email-masked]> wrote:

> Will a slightly shorter token be significant for you?  Is the rest of the
> message so short that a smaller token will have a significant impact?
>
> The hope is that if we standardize JWT, that libraries will be developed so
> that the average developer does not need to deal with the details.
>
> Too specific and the spec does not solve a broad enough set of people's
> needs, libraries don't get developed, or if they do, the code coverage is
> nominal and they are not well maintained. This leads to more security risks
> and higher barrier to deployment.
>
> Too generic and the complexity in the library adds more security risks,
> less likely someone will implement a library and deploy.
>
> The header makes it easy for a generic library to quickly see what the rest
> of the token is, enables support for encrypted payloads (can't do that if
> the crypto info is in the payload), and provides a simple path for
> extensions / expansion.
>
> While I can appreciate doing less encodings operations, the encoding is
> already being used, so this is a slight additional computational overhead.
> Your suggestion for checking the number of periods may actually add back the
> computational overhead, and a separate code path to be tested leading to
> less secure code. Happy to elaborate more if that was not clear and
> compelling!
>
> -- Dick
>

---

From: Dick Hardt <[email-masked]>
Date: Mon, 10 Jan 2011 12:24:09 -0800

Hi Jeff

FWIW: 1.5 yrs ago when I  was at Microsoft working on OAuth WRAP, I hacked up some Perl code to generate and crack JWTs using HMAC as the signing mechanism. It was only about 10-15 lines of code. 

From my experience in building XML-DSIG libraries for Perl/Python/PHP/Ruby -- normalization and canonicalization were the pain points. From an implementation point of view, key management is a pain point.

JWT solves the serialization / normalization / canonicalization problem. Having one standard way to assemble and disassemble a token using standard serialization is a HUGE plus.

-- Dick

On 2011-01-10, at 12:09 PM, Jeff Lindsay wrote:

> I think I'm behind everything you've said. Perhaps the crux is in library vs user/developer implementation. I'm interested in less steps not for computational overhead, but for mental overhead and usability. I would love to have (and even contribute) standard libraries in various languages (we'll have to anyway if we do adopt this), but for now because we're an API (like Facebook) and our docs are about using our API. They assume all you need are the standard libraries in most programming environments. 
> 
> Right now, that means users implementing JWTs by hand. While we have libraries for our APIs, we have to design the API so that you don't *have* to use these libraries... otherwise, we might as well be a SOAP web service. 
> 
> So I'm wondering what people's idea are on how to start using/implementing this now without standard libraries, assuming we don't want to make the process any easier. My hypothesis is the response from you all will be, "just have the JWT process in your docs, it's easy enough. We're not worried about this odd phase of early adoption with no standard library."
> 
> -jeff
>

---

From: Paul Tarjan <[email-masked]>
Date: Tue, 11 Jan 2011 05:26:22 +0000

I wrote code in the 4 biggest web languages for our signed_request. I'm
sure it is a very small change to support JWTs.

https://github.com/ptarjan/signed-request

On 1/10/11 12:24 PM, "Dick Hardt" <[email-masked]> wrote:

>Hi Jeff
>FWIW: 1.5 yrs ago when I  was at Microsoft working on OAuth WRAP, I
>hacked up some Perl code to generate and crack JWTs using HMAC as the
>signing mechanism. It was only about 10-15 lines of code.
>
>From my experience in building XML-DSIG libraries for
>Perl/Python/PHP/Ruby -- normalization and canonicalization were the pain
>points. From an implementation point of view, key management is a pain
>point.
>
>JWT solves the serialization / normalization / canonicalization problem.
>Having one standard way to assemble and disassemble a token using
>standard serialization is a HUGE plus.
>
>-- Dick
>
>I think I'm behind everything you've said. Perhaps the crux is in library
>vs user/developer implementation. I'm interested in less steps not for
>computational overhead, but for mental overhead and usability. I would
>love to have (and even contribute) standard libraries in various
>languages (we'll have to anyway if we do adopt this), but for now because
>we're an API (like Facebook) and our docs are about using our API. They
>assume all you need are the standard libraries in most programming
>environments. 
>
>libraries for our APIs, we have to design the API so that you don't
>*have* to use these libraries... otherwise, we might as well be a SOAP
>web service. 
>
>So I'm wondering what people's idea are on how to start
>using/implementing this now without standard libraries, assuming we don't
>want to make the process any easier. My hypothesis is the response from
>you all will be, "just have the JWT process in your docs, it's easy
>enough. We're not worried about this odd phase of early adoption with no
>standard library."
>
>-jeff
>
>The hope is that if we standardize JWT, that libraries will be developed
>so that the average developer does not need to deal with the details.
>
>nominal and they are not well maintained. This leads to more security
>risks and higher barrier to deployment.
>
>The header makes it easy for a generic library to quickly see what the
>rest of the token is, enables support for encrypted payloads (can't do
>that if the crypto info is in the payload), and provides a simple path
>for extensions / expansion.
>
>already being used, so this is a slight additional computational
>overhead. Your suggestion for checking the number of periods may actually
>add back the computational overhead, and a separate code path to be
>tested leading to less secure code. Happy to elaborate more if that was
>not clear and compelling!
>
>-- Dick
>
>going to have gotten a lot more complicated, but looking at this I'm
>pretty happy to see most of the additions are optional.
>
>Like Paul, I'm not a fan of the short names. However, I've sort of
>accepted it, especially since as reserved keys they are less likely to
>conflict with keys we want to put in.
>
>debating going with JWT or our own method that is loosely based on JWT,
>but doesn't use JSON and results in smaller tokens and a simpler process
>(for example, you only do one base64url encoding of the final string). We
>think we'd gain better room for additions to our payload, and better
>readability (therefore learnability/usability) by using JSON, that it
>might be worth the tradeoff in token size and several encoding steps. At
>that point, we'd basically be JWT except for the fact we really don't
>need the header.
>
>algorithm key live in the payload. Since this is the only thing required
>in the header, allowing it as an optional key in the payload would allow
>the entire header to be optional. This would really help us out since we
>need a process that is as simple as humanly possible.
>
>issues reserving the key "algorithm", but I think if we go with short
>names, "alg" is much less likely to cause conflicts.
>
>--
>Jeff Lindsay
>
>Draft -01 of the JSON Web Token (JWT) specification
><http://self-issued.info/docs/draft-jones-json-web-token.html> is now
>available.  This version incorporates the consensus decisions reached at
>the Internet Identity Workshop.
> The remaining open issues and to-do items are documented in
>Section 12 
><http://self-issued.info/docs/draft-jones-json-web-token-01.html#TBD>.
>As a reminder, the suggested pronunciation of JWT is the same as the
>English word "jot".
>
> 
>
>  - 
>http://www.ietf.org/internet-drafts/draft-jones-json-web-token-01.txt
><http://www.ietf.org/internet-drafts/draft-jones-json-web-token-01.txt>
>  - 
>http://www.ietf.org/internet-drafts/draft-jones-json-web-token-01.xml
><http://www.ietf.org/internet-drafts/draft-jones-json-web-token-01.xml>
>  - 
>http://self-issued.info/docs/draft-jones-json-web-token-01.html
><http://self-issued.info/docs/draft-jones-json-web-token-01.html>
>  - 
>http://self-issued.info/docs/draft-jones-json-web-token-01.txt
><http://self-issued.info/docs/draft-jones-json-web-token-01.txt>
>  - 
>http://self-issued.info/docs/draft-jones-json-web-token-01.xml
><http://self-issued.info/docs/draft-jones-json-web-token-01.xml>
>  - 
>http://self-issued.info/docs/draft-jones-json-web-token.html
><http://self-issued.info/docs/draft-jones-json-web-token.html> (will
>  - 
>http://self-issued.info/docs/draft-jones-json-web-token.txt
><http://self-issued.info/docs/draft-jones-json-web-token.txt> (will point
>to new versions as they are posted)
>  - 
>http://self-issued.info/docs/draft-jones-json-web-token.xml
><http://self-issued.info/docs/draft-jones-json-web-token.xml> (will point
>to new versions as they are posted)
>  - 
>http://svn.openid.net/repos/specifications/json_web_token/1.0/
><http://svn.openid.net/repos/specifications/json_web_token/1.0/>
>(Subversion repository, with html, txt, and html versions available)
> 
>
>  - JSON Token Spec Results at IIW:
>http://self-issued.info/?p=361 <http://self-issued.info/?p=361>
>http://self-issued.info/?p=378 <http://self-issued.info/?p=378>
>  - JSON Token Naming Spec Results at IIW:
>http://self-issued.info/?p=386 <http://self-issued.info/?p=386>