JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens
draft-ietf-oauth-access-token-jwt-13

Thank you for the work on this document. Please find some comments and clarifying questions below.

Francesca

1. -----

      registration.  If encryption was negotiated with the authorization
      server at registration time and the incoming JWT access token is
      not encrypted, the resource server SHOULD reject it.

FP: Why is this just SHOULD and not MUST? In which case does it make sense to accept a non-encrypted token when encryption was negotiated?

2. -----

Section 2.1:

   Section 4).  JWT access tokens MUST NOT use "none" as the signing
   algorithm.  See Section 4 for more details.

Section 4:

   For the purpose of facilitating validation data retrieval, it is here
   RECOMMENDED that authorization servers sign JWT access tokens with an
   asymmetric algorithm.

   ...

   o  The resource server MUST validate the signature of all incoming
      JWT access tokens according to [RFC7515] using the algorithm
      specified in the JWT alg Header Parameter.  The resource server


FP: It might be obvious, but I think it would be useful to have an explicit sentence stating that JWT MUST be signed. The quoted text from Section 2.1 seem to imply it. Section 4 only RECOMMENDS that the JWT is signed with and asymmetric algorithm. Later on, Section 4 implies that all JWT are signed. On the other hand I note that encryption can be negotiated (and is optional) from the followig point; in that case it is not clear that the token is still signed (so the nested JWT would be a JWE nested in a JWS), or only JWE is used. What I am looking for is simple clarifications to be added for example in the introduction.

     o  If the JWT access token is encrypted, decrypt it using the keys
      and algorithms that the resource server specified during
      registration.  If encryption was negotiated with the authorization

3. -----

On the same note, and depending on the previous answer, why is the media type registered and used "application/at+jwt" and not something like "application/at+jws"/"application/at+jwe" or rather "application/at+jose" to be compliant with https://www.rfc-editor.org/rfc/rfc7515.html#section-9.2.1 ? I think that the structure transported is in fact a JWS or a JWE, rather than the JWT, and if that's the case that should be made clear in the text (one example where this could be clarified is in the following sentence)

   Resource servers receiving a JWT access token MUST validate it in the
   following manner.

My co-AD pretty much nailed it.   I would go further and say that her comment about "Why is this only SHOULD?" applies to a lot of the SHOULDs in here.  SHOULD presents a choice; why might an implementer reasonably not do any of the SHOULD things in here?

For readability, I suggest that the three registrations packed into Section 7.2.1 be separated somehow, as right now they appear to be one continuous bullet list.  Separate subsections would work, or even just a line of prose before each would suffice.

The first half of the second paragraph of Section 6 seems much more like an interoperability issue than a privacy issue to me.

I've never used JWT, and have only made slight use of OAUTH, so, um, sure?

Thank for writing this - it was a good and easy read...

Thank you for the work put into this document. 

Minor regret about the doc shepherd's write-up as it does not include anything about the WG consensus/discussion.

Cosmetic suggestion/nit in section 2.2: expanding 'iss', 'exp', ... could be useful for readers (even if I could guess 'issue' , 'expiration', ...)

Regards

-éric

Section 2.1

   JWT access tokens MUST include this media type in the "typ" header
   parameter to explicitly declare that the JWT represents an access
   token complying with this profile.  Per the definition of "typ" in
   Section 4.1.9 of [RFC7515], it is RECOMMENDED that the "application/"
   prefix be omitted.  [...]

Just to check: is the reason this is only RECOMMENDED just because
that's the requirement level that RFC 7515 used?  AFAIK we can be more
stringent here and just always require it to appear as "at+jwt", to
simplify processing, if that is compatible with existing deployments (or
we are willing to declare them non-conformant).  (Section 4 would change
accordingly if this text changes.)

Section 2.2

Why does "iat" get an extra sentence describing the claim in addition to
"as defined in [reference]" but not iss/exp/jti/etc.?

Section 2.2.1

   response (e.g., via the implicit flow) or after one or more token
   exchanges (e.g., obtaining a fresh access token using a refresh
   token, or exchanging one access token for another via [RFC8693]).

nit: RFC 8693 doesn't effectuate token exchange; the protocol it
specifies does.  So "via the token exchange mechanism of [RFC8693]" or
"via [RFC8693] procedures" or such seems more grammatically correct.

Section 2.2.2

   Any additional identity attribute whose semantic is well described by
   an entry in the JSON Web Token (JWT) IANA registry introduced in
   [RFC7519] SHOULD be encoded using the corresponding claim name.  Note
   that the JWT IANA registry includes the claims found in Section 5.1
   of [OpenID.Core].

I assume that ths "SHOULD be encoded using the corresponding claim name"
just refers to the claim name used, and is not advising that all
identity attributes be always included.  If so, perhaps a few more words
would help clarify, such as "if that attribute is to be included in the
JWT access token" at the end of the sentence.  Semantically it would
also work to start the sentence with "when being included", but IMO that
would detract from the focus of the sentence.

   Authorization servers including resource owner attributes in JWT
   access tokens should exercise care and verify that all privacy
   requirements are met, as discussed in Section 6.

I'd suggest to s/should/need to/.

Section 2.2.3

   All the individual scope strings in the "scope" claim MUST have
   meaning for the resources indicated in the "aud" claim.  See
   Section 5 for more considerations about the relationship between
   scope strings and resources indicated by the "aud" claim.

["aud" vs "resource?]

Section 2.2.3.1

   An authorization server wanting to include such attributes in a JWT
   access token SHOULD use as claim types the "groups","roles" and
   "entitlements" attributes of the "User" resource schema defined by
   Section 4.1.2 of [RFC7643]).

I do see that we go on to clarify that we register JWT claims for
"groups", "roles", and "entitlements" and recommend encoding guidance
for the values of these claims, but I'm still stumbling over the phrase
"claim types" here.  What is a "claim type"?  I suspect from context
that it is meant to refer to a "claim name" as recorded in the JWT
Claims registry, but I'm not 100% certain.  It might also help
readability to split this into two sentences: "use as claims [list].
The semantic contents of these claims are desribed in their definitions
as attributes of [...]", since the current wording has me trying to use
"attributes" in a JWT context, but it's intended to clarify the RFC 7643
reference.

   Authorization servers SHOULD encode the corresponding claim values
   according to the guidance defined in [RFC7643].  In particular, a

Why is this only a "SHOULD"?  We are defining these JWT claims, so we
can nail down exactly what they contain.

   non-normative example of "groups" attribute can be found in
   Section 8.2 of [RFC7643].  No specific vocabulary is provided for
   "roles" and "entitlements".

Similarly, we may want to be more concrete about "roles" and
"entitlements" if we don't already later in this document.

Section 3

This section is titled "Requesting a JWT Access Token" but the contents
don't really seem to provide a procedure for specifically requesting a
JWT access token.

(nit) the "exp" claim in the example is from 2018; we might want to use
something a little more "current" to time of actual publication.

Is the provided "state" in the example sufficiently long to provide CSRF
protection (as is recommended by RFC 6749)?

Section 4

   Authorization servers SHOULD use OAuth 2.0 Authorization Server
   Metadata [RFC8414] to advertise to resource servers their signing
   keys via "jwks_uri" and what "iss" claim value to expect via the
   issuer metadata value.  Alternatively, authorization servers

(nit) please use consistent formatting and terminology for the
"jwks_uri" and "issuer" metadata values.

   o  If the JWT access token is encrypted, decrypt it using the keys
      and algorithms that the resource server specified during
      registration.  If encryption was negotiated with the authorization
      server at registration time and the incoming JWT access token is
      not encrypted, the resource server SHOULD reject it.

Why is this only a SHOULD and not a MUST?

   o  The resource server MUST validate the signature of all incoming
      JWT access tokens according to [RFC7515] using the algorithm
      specified in the JWT alg Header Parameter.  The resource server
      MUST reject any JWT in which the value of "alg" is "none".  The
      resource server MUST use the keys provided by the authorization
      server.

Would the algorithm verification of Sections 3.1 and 3.2 of RFC 8725 be
relevant here?  Also, might local policy decide in the future to blanket
reject (then-)weak algorithms that are not "none"?

   o  The current time MUST be before the time represented by the "exp"
      claim.

RFC 7519 talk about an optional small leeway, "usually no more than a
few minutes" to account for clock skew; are we taking a stance one way
or the other on such leeway?

   The resource server MUST handle errors as described in Section 3.1 of
   [RFC6750].  [...]

I'm not sure that I saw anything before now in this document that
limits its applicability to bearer tokens only.  Do we need to start
now?

Section 5

   Authorization servers should prevent scenarios where clients can
   affect the value of the "sub" claim in ways that could confuse
   resource servers.  For example, if the authorization server elects to
   use the client_id as the "sub" value for access tokens issued client
   credentials grant, the authorization server should prevent clients to

nit: missing word (maybe "using the client credentials grant"?)

   register an arbitrary client_id value, as this would allow malicious

nit: s/to register/from registering/

   To preventing cross-JWT confusion, authorization servers MUST use a

nit: s/preventing/prevent/

   Authorization servers should use particular care when handling
   requests that might lead to ambiguous authorization grants.  For
   example: if a request includes multiple resource indicators, the
   authorization server should ensure that each scope string included in
   the resulting JWT access token, if any, can be unambiguously
   correlated to a specific resource among the ones listed in the "aud"
   claim.  The details on how to recognize and mitigate this and other
   ambiguous situations is highly scenario-dependent, hence out of scope
   for this profile.

Only using single-valued "aud" would also help prevent this kind of
mix-up, right?  Do we have a recommendation for single-valued "aud" in
one of the BCPs that we could point to?

   Authorization servers should not rely on the use of different keys
   for signing OpenID Connect ID Tokens and JWT tokens as a method to

nit: maybe s/should not/cannot/, since this is just a statement of fact?

Section 6

   As JWT access tokens carry information by value, it now becomes
   possible for clients and potentially even end users to directly peek
   inside the token claims collection.

(nit?) "of unencrypted tokens"?

   token is visible to the client.  Whenever client access to the access
   token content presents privacy issues for a given scenario, the
   authorization server should take explicit steps to prevent it.

I suggest s/should/needs to/.

   In every scenario, the content of the JWT access token will
   eventually be accessible to the resource server.  It's important to
   evaluate whether the resource server gained the proper entitlement to
   have access to any content received in form of claims, for example
   through user consent in some form, policies and agreements with the
   organization running the authorization servers, and so on.

I feel like it might be helpful to call out here that claims like those
including information about RO authentication (Section 2.2.1), identity
claims (Section 2.2.2), and authorization claims (Section 2.2.3) are
ones that not all RSes should be entitled to access.  I'm not sure about
the best way to indicate this, but perhaps another sentence at the end
about "For example, a user might not wish to consent to granting a given
RS information about any of the non-mandatory claims enumerated in
Section 2.2 (and subsections)" would help.

Section 8.1

URLs for the OIDC documents would be helpful.

I think RFC 7523 does not need to be normative.

Section 8.2

Please include the draft name for [OAuth2.Security.BestPractices] (I
assume it's draft-ietf-oauth-security-topics).

We have a "MUST handle errors as described in Section 3.1 of [RFC6750]"
which would make RFC 6750 a normative reference (but one of my comments
suggests that we may not want to limit ourselves to just those
procedures).

(2.1) "...can use any signing algorithm." I presume there ought to be some qualifiers on allowed algorithms?

(4) and (5) "This specification
   does not provide a mechanism for identifying a specific key as the
   one used to sign JWT access tokens."

I don't understand; there's a key ID right there in the token header?

(4) I presume it's important that any resouree server rejection of the token should be constant-time. Is this somewhere in the RFC tree, or do we need to explicitly say it here and/or in Security Considerations?