> Aah – I now see that this is the real misunderstanding.  The “string
 > representing a JSON object” is not the base64url encoded form – it’s the
 > string representation that’s parseable into a JSON object.

Thanks, yes, this is a key aspect of my difficulty in parsing the spec.

Though my misunderstanding is subtlety different than you characterized it above.

Rather, it's that my understanding from RFC4627 is that a "JSON object" /is a 
string/. Thus "string representing a JSON object" reads as "string representing 
a string", which implied to me that the base64-encoded form was implied.

Since you don't mean to imply that, then yes, my suggestions re terminology were 
somewhat incorrect (apologies).

However, I have these revised suggestions..

 > The reason for the syntactic construction “string representing a JSON object”
 > is that its string representation is distinct from the abstract JSON object
 > itself.

In RFC4627 there isn't an "abstract JSON object". It says..

    JavaScript Object Notation (JSON) is a text format for the
    serialization of structured data.
                   .
                   .
    A JSON text is a serialized object or array.


..from which I understand the latter to mean..

    A JSON text is a string-serialized abstract object or array.


Unfortunately, the overloaded term "JSON object" appears to be used in some 
contexts to refer to programmatic artifacts (eg the "window.JSON" javascript 
object implemented in browsers), and in other contexts (such as Section "8. 
Examples" in RFC4627) to refer to JSON texts.

So I suggest defining the term "JSON text object", which from nosing around 
seems to be also used in various other places/documents to refer to JSON texts 
that match the "object" ABNF production in RFC4627 "Sec 2.2. Objects" (note that 
by definition a JSON text is a "serialized object or array" [RFC4627])..

    JSON text object   A JSON text matching the "object" ABNF production
       in Section 2.2 of [RFC4627]. JSON text objects MUST UTF-8 encoded.


So instead of using the "string representing a JSON object" construct, the JW* 
specs could use "JSON text object" to refer to the non-base64-encoded things. 
Then you have..

    JWT Claims Set  A JSON text object containing a set of claims. ...

    JWT Header  A JSON text object describing the
       cryptographic operations applied to the JWT. ...


And just to sketch out "claim" et al..

    Claim:  an assertion of something as a fact. Here, claims are
       name and value pairs, consisting of a Claim Name and a
       Claim Value. A claim is expressed as a JSON text object
       member (see Section "2.2. Objects" of [RFC4627]).

    Claim Name  The name portion of a claim.

    Claim Value  The value portion of a claim.


Then the definitions for the encoded things become simply...

    Encoded JWT Header  A Base64url encoded JWT Header.


The "bytes of the UTF-8 representation of the JWT {Header,Claims Set}" phrasing 
becomes just "JWT {Header,Claims Set}".



 > I disagree with redefining the term “JWT” to not also include the signature.
 > The term “JWT” should continue to refer to the whole thing.

Ok, but by defining a “JWT” as being "signed or MACed and/or encrypted", then 
you have to go through extra contortions to define the so-called "Plaintext 
JWTs", which are ostensibly simply unsigned and unencrypted JWTs ("Plaintext" is 
sort of a misnomer). But perhaps you're doing this in order to encourage JWTs to 
be signed and/or encrypted by default, it's difficult to tell.

Overall, to me, having these three related specs -- JWT - JWE - JWS, defining 
three similar objects, and where a JWT is either..

   a profiled JWS, or profiled JWE, or           // "JWT"

   a profiled unsigned JWS, or                   // "Plaintext JWT"
I tend to think that defining a common base thing
   a JWS wrapping a JWT-profiled-JWE, or         // "nested JWT"

   a JWE wrapping a JWT-profiled-JWS             // "nested JWT"

..is confusing. Perhaps laying it out concisely like the above would help.


 > > Semantics, profiles and relationship to SAML:
 >
 > Can you suggest some language you’d like to see added about this?

the words I wrote the comments you were replying I trust will suffice to get you 
started.


 > However once you add an issuer and a principal, then you’re back to the JWT
 > being statements made by an entity about a subject.

sure, but note that what I was trying to say is that as defined in the JWT spec, 
a JWT has /no/ semantics. All semantics are supplied by specs profiling the JWT 
spec (eg draft-ietf-oauth-jwt-bearer-03).

It's just a difference, not necessarily an advantage or disadvantage.


 > > terminology is not alphabetised!
 >
 > No, it’s in a top-down descriptive order. Is there a requirement in IETF
 > specs that the terminology be alphabetized?

No there isn't AFAIK -- it's a personal preference (dunno about the RFC-editor, 
but IIRC I've seen RFCs with non-alphabetized terminology sections).  Given the 
way I read specs, non-alphabetized is harder for me.


 >> I found meager jwt comparison instructions at the very end of Section 7.
 >> it should probably be its own subsection. It should probably explicitly say
 >> that JWTs need to be parsed into their constituent components, and the
 >> latter must be individually examined/compared.
 >
 > We tried to cover this in the end of section 7, starting with the sentence
 > “Processing a JWT inevitably requires comparing known strings to values in the
 > token”, which says how these comparisons must be performed. I agree that this
 > should become its own subsection. I don’t understand your remark about
 > constituent components. Can you clarify?

i meant decoding from base64 (and decrypting as necessary) and parsing in order 
to obtain claim name and value pairs.

 > How about “Remove any JSON escaping from the input JSON string and convert
 > the string into a sequence of Unicode code points”?

fine.


HTH,

=JeffH