Subject: [OAUTH-WG] JSON Web Token (JWT) Specification Draft

From: Mike Jones <[email-masked]>
Date: Fri, 24 Sep 2010 00:22:19 +0000

Recognizing that there is substantial interest in representing sets of claims in JSON tokens, Yaron Goland and I have put together a draft JSON Web Token (JWT) spec for that purpose.

To answer the obvious question, while this was produced independently of Dirk's JSON token proposal<http://balfanz.github.com/jsontoken-spec/draft-balfanz-jsontoken-00.html>, both of us agree that we should come up with a unified spec.  Consider this an additional point in the possible design space from which to start discussions and drive consensus.  (If you read the two proposals, I think you'll find that there's already a lot in common, which is great.)

Thanks to those of you who have already given us feedback to improve the draft prior to this point.

                                                            Cheers,
                                                            -- Mike

---

From: "Manger, James H" <[email-masked]>
Date: Mon, 27 Sep 2010 11:29:06 +1000

<http://peoplesearch.in.telstra.com.au/peoplesearch/UserDetail.aspx?Employee
Number=3799878> James Manger
 <mailto:[email-masked]> [email-masked]
Chief Technology Office - Telstra
Phone: +61 3 8649 2442
Mobile: +61 4 1754 1870
Web: blogs.cto.in.telstra.com.au/security/

The information contained in this e-mail is confidential. It is only
intended for the recipient/s named above. If you are not an intended
recipient any unauthorised use is prohibited. If you have received this
e-mail in error, please notify the sender so that arrangements can be made
for its retrieval or destruction. Telstra Corporation Limited ABN 33 051 775
556.

From: [email-masked] [mailto:[email-masked]] On Behalf Of
Mike Jones
Sent: Friday, 24 September 2010 10:22 AM
To: [email-masked]
Subject: [OAUTH-WG] JSON Web Token (JWT) Specification Draft

Recognizing that there is substantial interest in representing sets of
claims in JSON tokens, Yaron Goland and I have put together a draft JSON Web
Token (JWT) spec for that purpose.

To answer the obvious question, while this was produced independently of
Dirk
<http://balfanz.github.com/jsontoken-spec/draft-balfanz-jsontoken-00.html>
's JSON token proposal, both of us agree that we should come up with a
unified spec.  Consider this an additional point in the possible design
space from which to start discussions and drive consensus.  (If you read the
two proposals, I think you'll find that there's already a lot in common,
which is great.)

Thanks to those of you who have already given us feedback to improve the
draft prior to this point.

                                                            Cheers,

                                                            -- Mike

---

From: "Manger, James H" <[email-masked]>
Date: Mon, 27 Sep 2010 13:57:58 +1000

Mike,

A couple of comments on JWT: (I had to send something after accidentally sending an empty message to the list ;-)

Section 4.1 "Reserved claim names"

There isn't a JSON "integer" type, just a "number" type.

The examples use a string value for "exp", while I expected a number (I expected "exp":1300752001 instead of "exp":"1300752001").

StringAndURI might be better named StringOrURI.

Section 5 "General rules for creating and validating a JWT"

  "5. When used in a security-related context, the JWT Claim Segment MUST be validated to only include claims whose syntax and semantics are both understood and supported."

Validation step 5 is very nasty towards future enhancements. It basically says a JWT with unrecognized claims must be rejected. A future-friendly alternative would be to ignore unrecognized claims.

I like Ben Laurie's note that the IETF's golden rule to "be liberal in what you accept" has "proved to be a less-than-great idea, particularly in protocols where you care about security, which is to say, all of them" [http://www.ietf.org/mail-archive/web/tls/current/msg04688.html]. Is this the sentiment behind step 5? I would agree with this sentiment for rejecting malformed JSON, but not for rejecting well-formed but unrecognized claims.

Perhaps the concern is that an unrecognized claim might change the meaning of another claim (eg qualify it to a limited context). That would be bad design of the claims, however.

A JWT used to access 2 apps may need some claims that only 1 app needs that the other has no need to recognize.

Section 7 "Signing JWTs with cryptographic algorithms"

It is a pity yet another set of names are required for algorithms that have been around for a while, eg "HS256", instead of "HmacSHA256" (Java's name) or "hmac-sha256" (fragment from XML digital signatures) or "HMAC-SHA256" (mimicking OAuth1). If we really want to save bytes, we could use "alg":"H" and use the length of the signature to distinguish between SHA-256/384/512.

Section 7.1 "Signing a JWT with HMAC SHA-256"

Drop "SHA-256" from the section name as it specifies signing with HMAC SHA-384 and HMAC SHA-512 as well.

Similarly rename sections 7.2 to "Signing a JWT with RSA" and section 7.3 to "Signing a JWT with ECDSA".

Section 3.1 "Example unsigned JWT"

The base64url encoding of the example doesn't include a '-' or '_' character, which would be helpful as these are the important differences from normal base64. Changing ".../is_root" to ".../~is_root" adds a "-" to the encoding.

--

James Manger

From: [email-masked] [mailto:[email-masked]] On Behalf Of Mike Jones
Sent: Friday, 24 September 2010 10:22 AM
To: [email-masked]
Subject: [OAUTH-WG] JSON Web Token (JWT) Specification Draft

                                                            Cheers,

                                                            -- Mike

---

From: Dick Hardt <[email-masked]>
Date: Sun, 26 Sep 2010 21:17:06 -0700

Did you intentionally decide not to support encrypting the token?

On 2010-09-23, at 5:22 PM, Mike Jones wrote:

> To answer the obvious question, while this was produced independently of Dirk’s JSON token proposal, both of us agree that we should come up with a unified spec.  Consider this an additional point in the possible design space from which to start discussions and drive consensus.  (If you read the two proposals, I think you’ll find that there’s already a lot in common, which is great.)
>  
> <jwt.html><jwt.xml>_______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth

---

From: Mike Jones <[email-masked]>
Date: Mon, 27 Sep 2010 04:20:44 +0000

I'd be open to a proposal for also supporting encryption.  The draft was intended to be a starting point for productive discussion - not a finished product.

Your thoughts?

                                                            -- Mike

From: Dick Hardt [mailto:[email-masked]]
Sent: Sunday, September 26, 2010 9:17 PM
To: Mike Jones
Cc: [email-masked]
Subject: Re: [OAUTH-WG] JSON Web Token (JWT) Specification Draft

                                                            Cheers,
                                                            -- Mike

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

---

From: Dick Hardt <[email-masked]>
Date: Sun, 26 Sep 2010 21:55:38 -0700

Don't put the signature information in the token, put it in a separate component (an envelope) that describes how the token is either signed or encrypted. See discussion from June:

http://www.ietf.org/mail-archive/web/oauth/current/msg03211.html

On 2010-09-26, at 9:20 PM, Mike Jones wrote:

> I’d be open to a proposal for also supporting encryption.  The draft was intended to be a starting point for productive discussion – not a finished product.
>  
> Your thoughts?
>  
>                                                             -- Mike
>

---

From: David Recordon <[email-masked]>
Date: Mon, 27 Sep 2010 06:55:30 -0700

I thought the discussion from June had most people not
needing encryption and an extra envelope. Given how Mike wrote this spec is
seems like supporting encryption with an extra envelope is possible, but
shouldn't be required if all you're doing is signing.

On Sun, Sep 26, 2010 at 9:55 PM, Dick Hardt <[email-masked]> wrote:

> Don't put the signature information in the token, put it in a separate
> component (an envelope) that describes how the token is either signed or
> encrypted. See discussion from June:
>
> I’d be open to a proposal for also supporting encryption.  The draft was
> intended to be a starting point for productive discussion – not a finished
> product.
>
> Your thoughts?
>
>                                                             -- Mike
>
> *From:* Dick Hardt [mailto:[email-masked]]
> *Sent:* Sunday, September 26, 2010 9:17 PM
> *To:* Mike Jones
> *Cc:* [email-masked]
> *Subject:* Re: [OAUTH-WG] JSON Web Token (JWT) Specification Draft
>
> To answer the obvious question, while this was produced independently of Dirk’s
> JSON token proposal<http://balfanz.github.com/jsontoken-spec/draft-balfanz-jsontoken-00.html>,
> both of us agree that we should come up with a unified spec.  Consider this
> an additional point in the possible design space from which to start
> discussions and drive consensus.  (If you read the two proposals, I think
> you’ll find that there’s already a lot in common, which is great.)
>
> _______________________________________________
> OAuth mailing list
> [email-masked]

---

From: Dick Hardt <[email-masked]>
Date: Mon, 27 Sep 2010 07:03:30 -0700

If you don't have an envelope, you don't have a standard way of looking at what the contents might be. It is like HTTP headers vs the body of the message. Fairly standard architectural practice that makes extensions easy instead of a hack.

There are many use cases where encryption is needed. People that need it are not participating in the WG now -- but the requirement was stated by numerous people at IIW a year ago when we presented WRAP. It is needed if you want higher LOA.

A common envelope makes it much easier, and makes supporting alternative signing mechanisms easier to deploy without busting existing code. 

History has shown time and time again that near sighted architectural approaches lead to pain later when something needs to be changed or added. Of course, over architected approaches never get deployed. I see adding an envelope a nice balance where one does not need to have figured everything out, but there is an clear extension mechanism separated from the payload.

On 2010-09-27, at 6:55 AM, David Recordon wrote:

> I thought the discussion from June had most people not needing encryption and an extra envelope. Given how Mike wrote this spec is seems like supporting encryption with an extra envelope is possible, but shouldn't be required if all you're doing is signing.
>

---

From: Mike Jones <[email-masked]>
Date: Tue, 28 Sep 2010 00:44:31 +0000

Thanks for the detailed comments, James.  I'll take them into account when producing the next draft.

Yes, the motivation behind Section 5, Rule 5 is exactly motivated by the sentiments that Ben so ably expressed and you elaborated upon.  Note that there *is* a caveat in place "When used in a security-related context".  If the token isn't being used in a security-related context, you are free to ignore not-understood claims (but not mal-formed tokens).  But if it's being used to make an access or authorization decision, it's a best practice that SOME layer of the software processing the token must fully understand what the token is intended to mean.

                                                                Thanks again,
                                                                -- Mike

From: Manger, James H [mailto:[email-masked]]
Sent: Sunday, September 26, 2010 8:58 PM
To: Mike Jones; [email-masked]
Subject: RE: JSON Web Token (JWT) Specification Draft

Mike,

--
James Manger

                                                            Cheers,
                                                            -- Mike