JWT Response for OAuth Token Introspection
draft-ietf-oauth-jwt-introspection-response-12

[Ballot comment]
I still believe that using non 2119 language (i.e., "must" rather than "MUST") would be better for the privacy section, but won't block the document on this minor point.

[Ballot comment]
Thank you for addressing my Discuss (and Comment) points!

Just a couple final notes on the -11:

Section 4

Please double-check that describing the resource server as
"authenticating with a private-key JWT" is compatible with using the
urn:ietf;params:oauth:client-assertion-type:jwt-bearer assertion type.
I am not up-to-date on the precise semantics of that assertion type, offhand.

Section 5

          Token introspection response parameter names intended to be
          used across domains SHOULD be registered in the OAuth Token
          Introspection Response registry
          [IANA.OAuth.Token.Introspection] defined by [RFC7662].

I'm a bit surprised to see any normative terminology used on the
question of whether response parameter names are to be registered, since
RFC 7662 already has a requirement ("MUST") for this scenario.  If the
intent truly is to weaken the requirement from RFC 7662, it seems that
some additional clarification is in order that this is a change from the
existing specification and why it is a desirable change.
(The "MAY extend the token introspection response" in the preceding
paragraph, not quoted, is also already present in RFC 7662.)

[Ballot discuss]
Hi,

Thank you for this document.

I have a  couple of process related questions regarding the legal aspects considered in chapter 9 on privacy that I would like to discuss with the other ADs on the telechat (hence raising it as a Discuss).

My two questions are:

(1) Is it appropriate for an RFC to specifying requirements relating to legal issues and laws?  Note, I think that the guidance that is provides is really helpful and should be included in the document, but I'm a bit concerned as to whether a standards track RFC should be stating formal requirements/constraints related to enforcing legal requirements rather that providing non-normative guidance.

(2) Related to the first question, if the IESG believes believes that providing such requirements is okay, a further question is whether using RFC 2119 language is appropriate, or whether this should use regular English?

An example from section 9:

  The AS MUST ensure a
  legal basis exists for the data transfer before any data is released
  to a particular RS.  The way the legal basis is established might
  vary among jurisdictions and MUST consider the legal entities
  involved.

Regards,
Rob

[Ballot discuss]
Hi,

Thank you for this document.

I have a  couple of process related questions regarding the legal aspects considered in chapter 9 on privacy that I would like to discuss with the other ADs on the telechat (hence raising it as a Discuss).

My two questions are:

(1) Is it appropriate for an RFC to specifying requirements relating to legal issues and laws?  Note, I think that the guidance that is provides is really helpful and should be included in the document, but I'm a bit concerned as to whether a standards track RFC should be stating formal requirements/constraints related to enforcing legal requirements rather that providing non-normative guidance.

(2) Related to the first question, if the IESG believes believes that providing such requirements is okay, a further question is whether using RFC 2119 language is appropriate, or whether this should use regular English?

An examples from section 9:

  The AS MUST ensure a
  legal basis exists for the data transfer before any data is released
  to a particular RS.  The way the legal basis is established might
  vary among jurisdictions and MUST consider the legal entities
  involved.

Regards,
Rob

[Ballot comment]
Sections 11.1.1 and 11.2.1 each appear to contain three registration actions, but they all blend together in a common bullet list.  It might be nicer on IANA to separate them somehow, either into individual sub-subsections, or at least make them distinct lists.

[Ballot comment]
Sections 11.1.1 and 11.2.1 each appear to contain three registration actions, but they all blend together in a common bullet list.  It might be nice to separate them somehow, either into individual sub-subsections, or at least make them distinct lists.

[Ballot discuss]
We've made a lot of progress at unravelling the gnarly issues relating
to merging the introspection response and JWT claims namespaces, which
is good.  That said, I'd still like to discuss a little bit more the
behavior described in Section 5, where the "token_introspection" claim
in the response can also contain JWT claims (''' In addition, claims
from the JSON Web Token Claims registry [IANA.JWT] established by
[RFC7519] MAY be included as members in the "token_introspection"
claim.''')  That seems to be granting carte blanche to do the thing that
was deemed problematic, i.e., mix the namespaces.  As such, the current
formulation in the document, in the general case of independent
uncoordinated implementations, seems to admit the prospect of an AS
adding something to an introspection response under the guise of the JWT
claim exception that is interpreted by the recipient RS as a new
introspection response parameter (or, I think, vice versa).  Yes, this
would require conflicting registrations to occur, but we still don't
have a procedure in place that would prevent such conflicting
registrations from occurring in the future.  How can we add some
low-cost safety controls that mitigate the risk while still enabling the
desired functionality?

I have a couple thoughts on this: there is already an exception for
implementation/service-specific (unregistered) claims in the
introspection response, which could apply to JWT claims under the same
requisite conditions of administrative control, if that's going to cover
the scenarios in question.  One could also imagine a new registration
procedure for introspection response parameters whereby (for example)
any non-conflicting value already registered as a JWT claim can be
mechanically propagated into the introspection response registry
potentially just by IANA without even expert review.  Then we would just
require the contents to be registered introspection response parameters,
and someone who wants to use JWT claims can trivially get them
registered before using them.

[Ballot comment]
I'm not balloting this at a DISCUSS-level, because it may just be me
failing to understand the intended meaning (or being forgetful), but I'm having a hard time
seeing how we're self-consistent about the requirement for an RS to
authenticate and authorize a given RS for a given introspection
transaction.  In particular, in Section 3 we see that "the authorization
server MUST be able to identify, authenticate and authorize resource
servers" and that "[t]he authorization server MUST be able to determine
whether an RS is the audience for a particular access token and what
data it is entitled to receive, otherwise the RS is not authorized to
obtain data for the access token".  While I see that there is also some
discussion about using the "scope" parameter of the token being
introspected as an indicator of the RS it is to be used for (and thus
the identity of the RS that would legitimately be making an
introspection request), and I also see discussion of using an encrypted
introspection response as a way to ensure that the contents are only
viewable by the intended RS, I'm not sure how clearly either (or both)
mechanisms constitute "authentication" of the introspection request.
Since we already require a "strong two-way trust relationship", it's not
clear to me that it would be difficult to strongly authenticate the
actual introspection request itself or that there is much gained by
skipping such a check in favor of other mechanisms.  Several of my
inline comments touch on this topic (on the assumption that there is a
strong MUST for strong authentication); I left them in place to benefit
from the context of where they appear, rather than constructing a
laundry list of all of them.  That said, it will suffice to explain how
I'm wrong/confused just once; there's no need to repeat it at each place
I bring up the topic.

Section 3

  To support encrypted token introspection response JWTs, the
  authorization server MUST also be provided with the respective
  resource server encryption keys and algorithms.

That seems more of a descriptive than a normative "must", to me.

Section 4

  A resource server requests a JWT introspection response by including
  an "Accept" HTTP header "application/token-introspection+jwt" in the
  introspection request.

nit: "header field". and probably also something about "containing" or
"with body".

  The AS SHOULD authenticate the caller at the token introspection
  endpoint.  Authentication can utilize client authentication methods
  or a separate access token issued to the resource server.  Whether a
  resource server is required to authenticate is determined by the
  respective RS-specific policy at the AS.

I don't think this can be only a SHOULD-level requirement and be
consistent with the MUST-level requirements in the previous section
(most notably, "[AS] MUST be able to determine whether an RS is the
audience for a particular access token".  It is hard to believe that an
unauthenticated RS could have such authorization.

  The following is a non-normative example request with client
  authentication:

  POST /introspect HTTP/1.1
  Host: as.example.com
  Accept: application/token-introspection+jwt
  Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

(side note: "Authorization: Basic" makes me sad.)

Section 5

  The introspection endpoint responds with a JWT, setting the "Content-
  Type" HTTP header to "application/token-introspection+jwt" and the

nit: "header field" again.

          If possible, the AS MUST narrow down the "scope" value to the
          scopes relevant to the particular RS.

What's the difference between "if possible,  MUST" and " SHOULD"?

  The JWT MAY include other claims, including those from the "JSON Web
  Token Claims" registry established by [RFC7519].  The JWT SHOULD NOT
  include the "sub" and "exp" claims as an additional prevention
  against misuse of the JWT as an access token (see Section 8.1).

nit: I think a comma after "'exp' claims" would increase clarity.

  The JWT is cryptographically secured as specified in [RFC7662].

I think that this was intended to refer to 7519 (JWT), not 7662
(introspection)?

  Depending on the specific resource server policy the JWT is either
  signed, or signed and encrypted.  If the JWT is signed and encrypted
  it MUST be a Nested JWT, as defined in JWT [RFC7519].

  Note: If the resource server policy requires a signed and encrypted

(nit?) Just to confirm: the "resource server policy" here is a policy
that's applied at the AS on a per-resource-server basis?  If so, perhaps
writing it "resource-server-specific policy" would clarify.

  response and the authorization server receives an unauthenticated
  request containing an "Accept" header with content type other than
  "application/token-introspection+jwt", it MUST refuse to serve the
  request and return an HTTP status code 400.  This is done to prevent
  downgrading attacks to obtain token data intended for release to
  legitimate recipients only (see Section 8.2).

An unauthenticated request should be denied unconditionally, right?
Should this MUST apply to just requests containing the "Accept" header
(field) with other content-types?

  The example response JWT payload contains the following JSON
  document:
  [...]
    "token_introspection":
        {
          [...]
          "scope":"read write dolphin",

Is there any chance the minimizer that was run on this payload as input
to JWT generation also removed the spaces in the scope string?  I seem
to be having some unexpected behavior from my local tooling, but it is
looking like the claims set from the example HTTP payload lists
"scope":"readwritedolphin".

Section 8.2

  To prevent introspection of leaked tokens and to present an
  additional security layer against token guessing attacks the
  authorization server MAY require all requests to the token
  introspection endpoint to be authenticated.  As an alternative or as
  an addition to the authentication, the intended recipients MAY be set
  up for encrypted responses.

Isn't this ("require all requests to be authenticated") also a MUST now?

[Ballot comment]
To IESG: This is a returning item.  The change required to address a DISCUSS from the first round was significant enough that the document was brought back to the WG to confirm the consensus.  This change moved the data of the introspected token into a top-level JWT claim to allow for the separation of the carrier JWT claims from the actual
token introspection response claims.

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

The IANA Functions Operator has completed its review of draft-ietf-oauth-jwt-introspection-response-09. If any part of this review is inaccurate, please let us know.

The IANA Functions Operator understands that, upon approval of this document, there are four actions which we must complete.

First, in the OAuth Dynamic Client Registration Metadata registry on the OAuth Parameters registry page located at:

https://www.iana.org/assignments/oauth-parameters/

three, new registrations are to be made as follows:

Client Metadata Name: introspection_signed_response_alg
Client Metadata Description: String value indicating the client's desired introspection response signing algorithm.
Change Controller: IESG
Reference: [ RFC-to-be; Section 6 ]

Client Metadata Name: introspection_encrypted_response_alg
Client Metadata Description: String value specifying the desired introspection response content key encryption algorithm (alg value).
Change Controller: IESG
Reference: [ RFC-to-be; Section 6 ]

Client Metadata Name: introspection_encrypted_response_enc
Client Metadata Description: String value specifying the desired introspection response content encryption algorithm (enc value).
Change Controller: IESG
Reference: [ RFC-to-be; Section 6 ]

Note to authors: As this section requests registrations in a Specification Required (see RFC 8126) registry, the IESG-designated expert for the OAuth Dynamic Client Registration Metadata has asked that you send a review request to the mailing list described in [RFC7591]. This review must be completed before the document's IANA state can be changed to "IANA OK."

Second, in the OAuth Authorization Server Metadata registry on the OAuth Parameters registry page located at:

https://www.iana.org/assignments/oauth-parameters/

three, new registrations are to be made as follows:

Metadata name: introspection_signing_alg_values_supported
Metadata description: JSON array containing a list of algorithms supported by the authorization server for introspection response signing.
Change controller: IESG
Reference: [ RFC-to-be; Section 7 ]

Metadata name: introspection_encryption_alg_values_supported
Metadata description: JSON array containing a list of algorithms supported by the authorization server for introspection response content key encryption (alg value).
Change controller: IESG
Reference: [ RFC-to-be; Section 7 ]

Metadata name: introspection_encryption_enc_values_supported
Metadata description: JSON array containing a list of algorithms supported by the authorization server for introspection response content encryption (enc value).
Change controller: IESG
Reference: [ RFC-to-be; Section 7 ]

Note to authors: As this section requests registrations in a Specification Required (see RFC 8126) registry, the IESG-designated expert for the OAuth Parameters has asked that you send a review request to the mailing list described in [RFC8414]. This review must be completed before the document's IANA state can be changed to "IANA OK."

Third, in the application section of the Media Types registry located at:

https://www.iana.org/assignments/media-types/

a single, new registration will be made as follows:

Name: token-introspection+jwt
Template: [ TBD-at-Registration ]
Reference: [ RFC-to-be ]

Fourth, in the JSON Web Token Claims registry on the JSON Web Token (JWT) registry page located at:

https://www.iana.org/assignments/jwt/

a single, new registration will be made as follows:

Claim Name: token_introspection
Claim Description: Token introspection response
Change Controller: IESG
Reference: [ RFC-to-be ]

Note to authors: As this section requests registrations in a Specification Required (see RFC 8126) registry, the IESG-designated experts for the JSON Web Token Claims have asked that you send a review request to the mailing list described in [RFC7519]. This review must be completed before the document's IANA state can be changed to "IANA OK."

The IANA Functions Operator understands that these are the only actions required to be completed upon approval of this document.

Note:  The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is meant only to confirm the list of actions that will be performed.

Thank you,

Sabrina Tanamal
Senior IANA Services Specialist

The following Last Call announcement was sent out (ends 2020-09-04):

From: The IESG
To: IETF-Announce
CC: oauth-chairs@ietf.org, draft-ietf-oauth-jwt-introspection-response@ietf.org, rifaat.s.ietf@gmail.com, oauth@ietf.org, rdd@cert.org, Rifaat Shekh-Yusef
Reply-To: last-call@ietf.org
Sender:
Subject: Last Call:  (JWT Response for OAuth Token Introspection) to Proposed Standard


The IESG has received a request from the Web Authorization Protocol WG
(oauth) to consider the following document: - 'JWT Response for OAuth Token
Introspection'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
last-call@ietf.org mailing lists by 2020-09-04. Exceptionally, comments may
be sent to iesg@ietf.org instead. In either case, please retain the beginning
of the Subject line to allow automated sorting.

Abstract


  This specification proposes an additional JSON Web Token (JWT)
  secured response for OAuth 2.0 Token Introspection.




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-oauth-jwt-introspection-response/



No IPR declarations have been submitted directly on this I-D.

(1) What type of RFC is being requested (BCP, Proposed Standard, Internet
Standard, Informational, Experimental, or Historic)? Why is this the proper type
of RFC? Is this type of RFC indicated in the title page header?

This specification is proposed as a 'Standards Track' document. The document
defines a new response type to an introspection request in the form of a JWT.

(2) The IESG approval announcement includes a Document Announcement Write-Up.
Please provide such a Document Announcement Write-Up. Recent examples can be
found in the "Action" announcements for approved documents. The approval
announcement contains the following sections:

Technical Summary:

This draft proposes an additional JSON Web Token (JWT) based response for
OAuth 2.0 Token Introspection that allows for non-repudiation, and for
application level authenticity, integrity, and confidentiality.

Working Group Summary:

The document received many reviews and feedback from multiple WG members on the
mailing list and during the WG meetings.

The document was then submitted to the IESG, and during IESG review it had a
DISCUSS that required significant change that needed the attention and approval
of the WG. It was decided to send the document back to the WG to review the
change, and the authors presented the update during an IETF107 interim meeting
and got the support of the WG. The document then went through a WGLC during
which no objections were recorded to the proposed change.

The proposed change moves the data of the introspected token into a top-level
JWT claim to allow for the separation of the carrier JWT claims from the actual
token introspection response claims.


Document Quality:

The document has been implemented by the following:

* node.js OSS oidc-provider implements the document in full behind an optional feature toggle
https://github.com/panva/node-oidc-provider/blob/master/docs/README.md#featuresjwtintrospection

* connect2id has an implementation:
https://connect2id.com/products/server/docs/api/token-introspection

* ForgeRock:
https://github.com/ForgeRock/PSD2-Accelerators/tree/yes.com/openig/yes-openig-signed-introspect-filter



Personnel:

The document shepherd is Rifaat Shekh-Yusef.
The responsible Area Director is Roman Danyliw.


(3) Briefly describe the review of this document that was performed by the
Document Shepherd. If this version of the document is not ready for publication,
please explain why the document is being forwarded to the IESG.

The document shepherd has reviewed the document and feels the document is ready.


(4) Does the document Shepherd have any concerns about the depth or breadth of
the reviews that have been performed?

The document shepherd has no concerns with the level of reviews, as the document
was discussed and reviewed by many participants.


(5) Do portions of the document need review from a particular or from broader
perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or
internationalization? If so, describe the review that took place.

Security review is always needed and appreciated.


(6) Describe any specific concerns or issues that the Document Shepherd has with
this document that the Responsible Area Director and/or the IESG should be aware
of? For example, perhaps he or she is uncomfortable with certain parts of the
document, or has concerns whether there really is a need for it. In any event,
if the WG has discussed those issues and has indicated that it still wishes to
advance the document, detail those concerns here.

The document shepherd has no such concerns.


(7) Has each author confirmed that any and all appropriate IPR disclosures
required for full conformance with the provisions of BCP 78 and BCP 79 have
already been filed. If not, explain why?

Yes

Vladimir - https://mailarchive.ietf.org/arch/msg/oauth/N-m0lX-yFSN_WTHleZzXCeXjfDc
Torsten - https://mailarchive.ietf.org/arch/msg/oauth/gLlKNkBhs_8PCZnPehM6cGYdgaw



(8) Has an IPR disclosure been filed that references this document? If so,
summarize any WG discussion and conclusion regarding the IPR disclosures.

No such IPR disclosures.


(9) How solid is the WG consensus behind this document? Does it represent the
strong concurrence of a few individuals, with others being silent, or does the
WG as a whole understand and agree with it?

There is a solid support for this document from the WG.


(10) Has anyone threatened an appeal or otherwise indicated extreme discontent?
If so, please summarise the areas of conflict in separate email messages to the
Responsible Area Director. (It should be in a separate email because this
questionnaire is publicly available.)

No such threat or discontent.


(11) Identify any ID nits the Document Shepherd has found in this document.
(See http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist).
Boilerplate checks are not enough; this check needs to be thorough.

idnits 2.16.04

tmp/draft-ietf-oauth-jwt-introspection-response-09.txt:

  Checking boilerplate required by RFC 5378 and the IETF Trust (see
  https://trustee.ietf.org/license-info):
  ----------------------------------------------------------------------------

    No issues found here.

  Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
  ----------------------------------------------------------------------------

    No issues found here.

  Checking nits according to https://www.ietf.org/id-info/checklist :
  ----------------------------------------------------------------------------

    No issues found here.

  Miscellaneous warnings:
  ----------------------------------------------------------------------------

  -- The document date (April 25, 2020) is 71 days in the past.  Is this
    intentional?


  Checking references for intended status: Proposed Standard
  ----------------------------------------------------------------------------

    (See RFCs 3967 and 4897 for information about using normative references
    to lower-maturity documents in RFCs)

  == Outdated reference: draft-ietf-oauth-jwt-bcp has been published as RFC
    8725

  == Outdated reference: A later version (-15) exists of
    draft-ietf-oauth-security-topics-13


    Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--).

    Run idnits with the --verbose option for more detailed information about
    the items above.     


(12) Describe how the document meets any required formal review criteria,
such as the MIB Doctor, media type, and URI type reviews.

No such reviews are necessary.


(13) Have all references within this document been identified as either
normative or informative?

Yes.


(14) Are there normative references to documents that are not ready for
advancement or are otherwise in an unclear state? If such normative references
exist, what is the plan for their completion?

The document has a reference to the I-D.ietf-oauth-security-topics which is still
under discussion at the WG.

The document has a references to the I-D.ietf-oauth-jwt-bcp, which was already
published as RFC8725.


(15) Are there downward normative references (see RFC 3967)? If so, list these
downward references to support the Area Director in the Last Call procedure.

No such references.


(16) Will publication of this document change the status of any existing RFCs?
Are those RFCs listed on the title page header, listed in the abstract, and
discussed in the introduction? If the RFCs are not listed in the Abstract and
Introduction, explain why, and point to the part of the document where the
relationship of this document to the other RFCs is discussed. If this
information is not in the document, explain why the WG considers it unnecessary.

No status change of any existing RFCs.


(17) Describe the Document Shepherd's review of the IANA considerations section,
especially with regard to its consistency with the body of the document. Confirm
that all protocol extensions that the document makes are associated with the
appropriate reservations in IANA registries. Confirm that any referenced IANA
registries have been clearly identified. Confirm that newly created IANA
registries include a detailed specification of the initial contents for the
registry, that allocations procedures for future registrations are defined, and
a reasonable name for the new registry has been suggested (see RFC 5226).

The IANA section is complete and correct.


(18) List any new IANA registries that require Expert Review for future
allocations. Provide any public guidance that the IESG would find useful in
selecting the IANA Experts for these new registries.

No new IANA registries.


(19) Describe reviews and automated checks performed by the Document Shepherd to
validate sections of the document written in a formal language, such as XML
code, BNF rules, MIB definitions, etc.

The document contains JSON-based examples, and these were validated using
JSONLint.
There is one issue with the following JSON example in page 7, which is missing a
comma after the second kay-value pair:
{
    "typ": "token-introspection+jwt",
    "alg": "RS256"
    "kid": "wG6D"
}

(1) What type of RFC is being requested (BCP, Proposed Standard, Internet
Standard, Informational, Experimental, or Historic)? Why is this the proper type
of RFC? Is this type of RFC indicated in the title page header?

This specification is proposed as a 'Standards Track' document. The document
defines a new response type to an introspection request in the form of a JWT.

(2) The IESG approval announcement includes a Document Announcement Write-Up.
Please provide such a Document Announcement Write-Up. Recent examples can be
found in the "Action" announcements for approved documents. The approval
announcement contains the following sections:

Technical Summary:

This draft proposes an additional JSON Web Token (JWT) based response for
OAuth 2.0 Token Introspection that allows for non-repudiation, and for
application level authenticity, integrity, and confidentiality.

Working Group Summary:

The document received many reviews and feedback from multiple WG members on the
mailing list and during the WG meetings.

The document was then submitted to the IESG, and during IESG review it had a
DISCUSS that required significant change that needed the attention and approval
of the WG. It was decided to send the document back to the WG to review the
change, and the authors presented the update during an IETF107 interim meeting
and got the support of the WG. The document then went through a WGLC during
which no objections were recorded to the proposed change.

The proposed change moves the data of the introspected token into a top-level
JWT claim to allow for the separation of the carrier JWT claims from the actual
token introspection response claims.


Document Quality:

The document has been implemented by the following:

* node.js OSS oidc-provider implements the document in full behind an optional feature toggle
https://github.com/panva/node-oidc-provider/blob/master/docs/README.md#featuresjwtintrospection

* connect2id has an implementation:
https://connect2id.com/products/server/docs/api/token-introspection

* ForgeRock:
https://github.com/ForgeRock/PSD2-Accelerators/tree/yes.com/openig/yes-openig-signed-introspect-filter



Personnel:

The document shepherd is Rifaat Shekh-Yusef.
The responsible Area Director is Roman Danyliw.


(3) Briefly describe the review of this document that was performed by the
Document Shepherd. If this version of the document is not ready for publication,
please explain why the document is being forwarded to the IESG.

The document shepherd has reviewed the document and feels the document is ready.


(4) Does the document Shepherd have any concerns about the depth or breadth of
the reviews that have been performed?

The document shepherd has no concerns with the level of reviews, as the document
was discussed and reviewed by many participants.


(5) Do portions of the document need review from a particular or from broader
perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or
internationalization? If so, describe the review that took place.

Security review is always needed and appreciated.


(6) Describe any specific concerns or issues that the Document Shepherd has with
this document that the Responsible Area Director and/or the IESG should be aware
of? For example, perhaps he or she is uncomfortable with certain parts of the
document, or has concerns whether there really is a need for it. In any event,
if the WG has discussed those issues and has indicated that it still wishes to
advance the document, detail those concerns here.

The document shepherd has no such concerns.


(7) Has each author confirmed that any and all appropriate IPR disclosures
required for full conformance with the provisions of BCP 78 and BCP 79 have
already been filed. If not, explain why?

Yes

Vladimir - https://mailarchive.ietf.org/arch/msg/oauth/N-m0lX-yFSN_WTHleZzXCeXjfDc
Torsten - https://mailarchive.ietf.org/arch/msg/oauth/gLlKNkBhs_8PCZnPehM6cGYdgaw



(8) Has an IPR disclosure been filed that references this document? If so,
summarize any WG discussion and conclusion regarding the IPR disclosures.

No such IPR disclosures.


(9) How solid is the WG consensus behind this document? Does it represent the
strong concurrence of a few individuals, with others being silent, or does the
WG as a whole understand and agree with it?

There is a solid support for this document from the WG.


(10) Has anyone threatened an appeal or otherwise indicated extreme discontent?
If so, please summarise the areas of conflict in separate email messages to the
Responsible Area Director. (It should be in a separate email because this
questionnaire is publicly available.)

No such threat or discontent.


(11) Identify any ID nits the Document Shepherd has found in this document.
(See http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist).
Boilerplate checks are not enough; this check needs to be thorough.

idnits 2.16.04

tmp/draft-ietf-oauth-jwt-introspection-response-09.txt:

  Checking boilerplate required by RFC 5378 and the IETF Trust (see
  https://trustee.ietf.org/license-info):
  ----------------------------------------------------------------------------

    No issues found here.

  Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
  ----------------------------------------------------------------------------

    No issues found here.

  Checking nits according to https://www.ietf.org/id-info/checklist :
  ----------------------------------------------------------------------------

    No issues found here.

  Miscellaneous warnings:
  ----------------------------------------------------------------------------

  -- The document date (April 25, 2020) is 71 days in the past.  Is this
    intentional?


  Checking references for intended status: Proposed Standard
  ----------------------------------------------------------------------------

    (See RFCs 3967 and 4897 for information about using normative references
    to lower-maturity documents in RFCs)

  == Outdated reference: draft-ietf-oauth-jwt-bcp has been published as RFC
    8725

  == Outdated reference: A later version (-15) exists of
    draft-ietf-oauth-security-topics-13


    Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--).

    Run idnits with the --verbose option for more detailed information about
    the items above.     


(12) Describe how the document meets any required formal review criteria,
such as the MIB Doctor, media type, and URI type reviews.

No such reviews are necessary.


(13) Have all references within this document been identified as either
normative or informative?

Yes.


(14) Are there normative references to documents that are not ready for
advancement or are otherwise in an unclear state? If such normative references
exist, what is the plan for their completion?

The document has a reference to the I-D.ietf-oauth-security-topics which is still
under discussion at the WG.

The document has a references to the I-D.ietf-oauth-jwt-bcp, which was already
published as RFC8725.


(15) Are there downward normative references (see RFC 3967)? If so, list these
downward references to support the Area Director in the Last Call procedure.

No such references.


(16) Will publication of this document change the status of any existing RFCs?
Are those RFCs listed on the title page header, listed in the abstract, and
discussed in the introduction? If the RFCs are not listed in the Abstract and
Introduction, explain why, and point to the part of the document where the
relationship of this document to the other RFCs is discussed. If this
information is not in the document, explain why the WG considers it unnecessary.

No status change of any existing RFCs.


(17) Describe the Document Shepherd's review of the IANA considerations section,
especially with regard to its consistency with the body of the document. Confirm
that all protocol extensions that the document makes are associated with the
appropriate reservations in IANA registries. Confirm that any referenced IANA
registries have been clearly identified. Confirm that newly created IANA
registries include a detailed specification of the initial contents for the
registry, that allocations procedures for future registrations are defined, and
a reasonable name for the new registry has been suggested (see RFC 5226).

The IANA section is complete and correct.


(18) List any new IANA registries that require Expert Review for future
allocations. Provide any public guidance that the IESG would find useful in
selecting the IANA Experts for these new registries.

No new IANA registries.


(19) Describe reviews and automated checks performed by the Document Shepherd to
validate sections of the document written in a formal language, such as XML
code, BNF rules, MIB definitions, etc.

The document contains JSON-based examples, and these were validated using
JSONLint.
There is one issue with the following JSON example in page 7, which is missing a
comma after the second kay-value pair:
{
    "typ": "token-introspection+jwt",
    "alg": "RS256"
    "kid": "wG6D"
}

[Ballot discuss]
Thank you for the updates in the -08; they address the bulk of the
substantive issues!  I have a few points remaining on the -08 text but I
think there are more localized issues to resolve.

[media-type expert review is only suggested, not mandatory, for
IETF-stream standards actions]

It looks like we need to register 'active' as a JWT claim?

I don't think the new semantics for "jti" in the introspection response
are compatible with the RFC 7519 definition.  Specifically, we say that
"jti" will be tied to the input access token, but 7519 says that "jti"
has to change when the contents of the JWT change ("MUST be assigned in
a manner that ensures that there is a negligible probability that the
same value will be accidentally assigned to a different data object"),
and we admit at least the possibility of "active" and "iat" changing.

Section 5 says that:

  If the access token is considered active, it MUST contain the claims
  "iss" and "aud" in order to prevent misuse of the JWT as an ID or
  access token (see Section 8.1).

But I don't think the predicate is correct -- misuse is still possible
by services that do not check the "active" claim's value.  Shouldn't the
"iss"+"aud" requirements be unconditional?

[Ballot discuss]
Thank you for the updates in the -08; they address the bulk of the
substantive issues!  I have a few points remaining on the -08 text but I
think there are more localized issues to resolve.

Can IANA please confirm that the new allocations in the -08 have
received appropriate Expert (e.g., media type) review?  I see some
updates in the datatracker history relating to the -08 but nothing in
the email archives.

It looks like we need to register 'active' as a JWT claim?

I don't think the new semantics for "jti" in the introspection response
are compatible with the RFC 7519 definition.  Specifically, we say that
"jti" will be tied to the input access token, but 7519 says that "jti"
has to change when the contents of the JWT change ("MUST be assigned in
a manner that ensures that there is a negligible probability that the
same value will be accidentally assigned to a different data object"),
and we admit at least the possibility of "active" and "iat" changing.

Section 5 says that:

  If the access token is considered active, it MUST contain the claims
  "iss" and "aud" in order to prevent misuse of the JWT as an ID or
  access token (see Section 8.1).

But I don't think the predicate is correct -- misuse is still possible
by services that do not check the "active" claim's value.  Shouldn't the
"iss"+"aud" requirements be unconditional?

[Ballot comment]
[New comments on the added text in the diff from -07 to -08.]

Section 3

  To support encrypted token introspection response JWTs, the
  authorization server MUST also be provided with the respective
  resource server encryption keys and algorithms.

IIRC, based on some list discussion this text was going to be tweaked to
avoid implying that JWE is mandatory.  (Unfortunately, this is the
thread that evolved into "client certs and TLS Terminating Reverse
Proxies", so it's hard to be sure whether I saw any other followups.)

  The AS MUST restrict the use of client credentials by a RS to the
  calls it requires, e.g. the AS MAY restrict such a client to call the
  token introspection endpoint only.  How the AS implements this
  restriction is beyond the scope of this specification.

This should probably be clarified a bit more, in the context of "client
credentials tend to be used by privileged, fixed endpoints, and the
default may just be to allow them all access to all endpoints".  Right
now it's not clear what's being restricted (and who "it" is that
requires calls)

Section 5

  This specification registers the "application/token-
  introspection+jwt" media type, which is used as value of the "typ"
  header parameter of the JWT to indicate that the payload is a token
  introspection response.

Do we also want to note that checking 'jti' is not mandatory and so this
does not necessarily provide full protection?  (I guess Section 8.1
covers this in more detail.)

  The value of the "aud" claims MUST identify the resource server
  receiving the token introspection response.

We may want to dig into this a bit more: should there be any
relationship between this "aud" value and the "client_id" that an RS
might be using (as obtained from dynamic registration)?
Does this value need to be different from the audience that is used in
access tokens for which this RS is the audience?  (Should it be the
same?)  My instincts lean towards "different" but I would like broader
input.

  exp    The "exp" claim indicates when the access token passed in the
          introspection request will expire.

On the face of it this seems divergent from RFC 7519's "the expiration
time on or after which the JWT MUST NOT be accepted for processing",
though upon further examination the distinction is not quite so large.
That is, it's in effect saying that the introspection response should
not be accepted for processing after the base token has expired, which
usually makes sense.  There is a bit of a complication, though, in that
the "active" claim implies that we might still have RSes that plan to
use the introspection response after the "exp" date has passed, which
sounds a lot like a DISCUSS-level internal inconsistency.

  If possible, the AS MUST narrow down the "scope" value to the scopes
  relevant to the particular RS.

This sounds kind of like a "SHOULD"...

  The example response header contains the following JSON document:

I think this is the JOSE header in the HTTP response (body), not the
(HTTP) response header.

Section 8.1

  As an alternative approach, such an attack can be prevented like any
  other token substitution attack by restricting the audience of the

I'd suggest avoiding describing these as "alternatives"; they seem more
like complementary approaches as part of a defense-in-depth solution
(especially since we are basically mandating both of them).

  "aud" value set to the resource server's identifier.  Any recipient
  of an JWT MUST check these values in order to detect substitution
  attacks.

This "MUST" might be out of place -- this is a requirement from RFC
7519, and not an attempt by this document to make new requirements on
the behavior of all JWT consumers (if it was, that would be a DISCUSS
point!).

  Resource servers MUST additionally apply the countermeasures against
  replay as described in [I-D.ietf-oauth-security-topics], section 3.2.

In a similar vein, which set of resources servers is this normative
"MUST" intended to be binding upon?

Section 9

  In any case, the AS MUST ensure that the scope of the legal basis is
  enforced throughout the whole process.  The AS MUST retain the scope
  of the legal basis with the access token, e.g. in the scope value,
  and the AS MUST determine the data a resource server is allowed to
  receive based on the resource server's identity and suitable token
  data, e.g. the scope value.

I suspect I'm just being dense, but could you walk me through how the
access token "scope" value can encode the legal basis for data transfer?

[Ballot comment]
I am agreeing with what Alissa said:

I support Benjamin's DISCUSS point about the IESG being listed as the change controller for the registry entries. Overall I'd like to understand better the relationship between these registry entries and future updates to OpenID Connect (i.e., if the claims in the OpenID spec change, will this registry automatically need to change as well?).

I also support Adam's DISCUSS. How are claims like preferred_username currently used for the described use case of verifying person data to create certificates?

[Ballot comment]
I support Benjamin's DISCUSS point about the IESG being listed as the change controller for the registry entries. Overall I'd like to understand better the relationship between these registry entries and future updates to OpenID Connect (i.e., if the claims in the OpenID spec change, will this registry automatically need to change as well?).

I also support Adam's DISCUSS. How are claims like preferred_username currently used for the described use case of verifying person data to create certificates?

If the linkage with the OpenID Connect 1.0 claims remains in the document, I think it would be good to add a note in Section 1.1 or a new Section 1.2 to indicate that the document uses terminology as defined in that spec (e.g., "End-User," "Relying Party," etc.).

[Ballot discuss]
Thanks for the work the authors and other contributors have
put into creating this document.

I have a privacy concern that I think warrants text in the document.

Section 8.3.1 introduces a significant amount of personally-identifiable
information. While I understand that this is needed for the use case
cited in the introduction (issuing certificated for electronic signatures),
I think the document needs some treatment of the sensitivity of this
information, the basis that the server uses to decide whether to include
it, and how consent to disclose it might be obtained from the user.

I'm putting this in as a DISCUSS, because I really do think this is
a showstopper for publication. I am quite aware, however, that I might
simply be missing some important aspect of the solution that makes my
concerns moot. Please point me in the right direction if this is the
case, and I'll be happy to clear.

[Ballot comment]
§3:

>  The example response contains the following JSON document:
>
>  {
>    "sub": "Z5O3upPC88QrAjx00dis",
>    "aud": "https://protected.example.net/resource",
>    "scope": "read write dolphin",
>    "iss": "https://server.example.com/",
>    "active": true,
>    "exp": 1419356238,
>    "iat": 1419350238,
>    "client_id": "l238j323ds-23ij4",
>    "given_name": "John",
>    "family_name":"Doe",
>    "birthdate":"1982-02-01"
>  }

The example response actually contains the following JSON document:

{
  "sub":"Z5O3upPC88QrAjx00dis",
  "aud":"https:\/\/protected.example.net\/resource",
  "extension_field":"twenty-seven",
  "scope":"read write dolphin",
  "iss":"https:\/\/server.example.com\/",
  "active":true,
  "exp":1419356238,
  "iat":1419350238,
  "client_id":"l238j323ds-23ij4",
  "username":"jdoe"
}

Note the presence of "extension_field" and "username" fields, and the
absence of "given_name", "family_name", and "birthdate" fields. There's
also a bunch of unnecessarily escaped "/" characters in the document
in the JWT, but not the expanded example; and while these are semantically
insignificant, the discrepancy seems gratuitous.

It is probably worthwhile updating either the JWT or the expanded
example so that they match.

[Ballot discuss]
Per the ongoing discussion on the WG list, it's unclear that we can
retain the behaviors we describe and still comply with the requirements
of RFC 7519 requirements for being a JWT (e.g., regarding "jti", "iat",
etc.).  That is, in the present formulation, there are two "token"s
involved -- the input that is being introspected, and the "token" that
is the introspection response.  We are claiming that certain fields are
describing the input token, when they are defined to be statements about
the current (response) token.
Relaxing our statements to say that we merely use JWS as opposed to JWT
may be a workaround, though I have thought about it hard enough to have
an opinion on whether it is the best workaround.

I also think we need more clarity about the use of dynamic client
registration by a resource server as outlined in Section 4 (where it's
mentioned as "with a resource server posing as the client", without
reference to RFC 7591.  As far as I can tell this document/section is
introducing this use of dynamic client registration by an RS for the
first time, so we cannot easily just refer to some other document.
Specifically, are there any fields that MUST NOT be supplied?  Is a
human-readable client_name useful?  How does the supplied client_uri
need to relate to any existing AS representation of a resource in
audience, scope, etc. (e.g., for the "resource" request parameter from
draft-ietf-oauth-resource-indicators)?

Is this usage considered to be a "new use of JWTs"?  If so, it seems
that we should follow the recommendation of draft-ietf-oauth-jwt-bcp and
use explicit typing.

I think there are some missing links in the document between a RS
registring client policy and the resulting AS enforcement of encryption
of introspection reponses.  I think the intent is roughly that the
policy will be applied based on the audience of the token being
presented for introspection (as opposed to the identity of the
RS-as-client making the introspection request), but we don't seem to
explicitly say that.  Also, we'd need to say something about the
interaction of multiple RSs' policy when a given token has multiple
valid audiences.  There is a very brief discussion in Section 6.5, but
it seems to be more of a description of what is possible than mandating
particular forms of enforcement.

I think we should discuss whether we want some statement from the OpenID
Foundation or related bodies before we register claims that point to
their documents with the IESG listed as change controller.

[Ballot comment]
idnits notes that RFC 5646 is mentioned but not present in the
references section.

Section 1

We probably need to move the 7519 reference up here to where JWT is
first used.

  OAuth 2.0 Token Introspection [RFC7662] specifies a method for a
  protected resource to query an OAuth 2.0 authorization server to
  determine the state of an access token and obtain data associated
  with the access token.  This allows deployments to implement
  identifier-based access tokens in an interoperable way.

Does "identifier-based access tokens" mean "tokens that are opaque keys
to a (central) database lookup" or "access tokens that convey user
identity information" (or something else)?  We may want to tweak the
wording.

Section 3

Can we double-check the base64 form of the response in this example?  I
am seeing output that backslash-escapes the '/' characters in URLs,
which I did not think was needed in this context.
I also see an "extension_field" claim in the base64 but not the decoded
form of the example, and "given_name"/"family_name"/"birthdate" in the
decoded example vs. "username" in the base64 version.

  Note: If the resource server policy requires a signed and encrypted
  response and the authorization server receives an unauthenticated
  request containing an Accept header with content type other than
  "application/jwt", it MUST refuse to serve the request and return an
  HTTP status code 400.  This is done to prevent downgrading attacks to
  obtain token data intended for release to legitimate recipients only
  (see Section 6.2).

I'd suggest a forward-reference to section 4 for how the AS will know
the RS's policy.  Although, given that "unauthenticated request" is
included in the preconditions, perhaps we do not need the conditional on
"resource server policy" at all?

Section 4

  The authorization server determines what algorithm to employ to
  secure the JWT for a particular introspection response.  This
  decision can be based on registered metadata parameters for the
  resource server, supplied via dynamic client registration with the
  resource server posing as the client, as defined by this draft.

nit: I suggest s/posing as the/acting as a/, and s/by this draft/below/,
since it's right here in this section.

  introspection_encrypted_response_alg  OPTIONAL.  JWE [RFC7516]
          algorithm ("alg" value) as defined in JWA [RFC7518] for
          encrypting introspection responses.  If this is specified,
          the response will be encrypted using JWE and the configured
          algorithm.  The default, if omitted, is that no encryption is

This text is slightly confusing with respect to the interaction between
the introspection_encrypted_response_alg "alg" value and the
introspection_encrypted_response_enc "enc" value.  My understanding is
that the "enc" is a symmetric bulk encryption scheme that directly
protects the payload, whereas the "alg" is a key-wrap or key-agreement
mechanism used to establish the key used as input for the "enc" method.
So, while "algorithm ("alg value") for encrypting introspection
responses" and "the response will be encrypted using the confugred
["algo"] algorithm" are technically true, they're also a bit misleading,
since this is not what encrypts the "bulk" of the response.  Using the
term from RFC 7158, "key management algorithm", would probably alleviate
this confusion.

  Resource servers may register their public encryption keys using the
  "jwks_uri" or "jwks" metadata parameters.

Should we cite 7591 for these (or, really, the whole section)?  We don't
currently mention it until the IANA considerations.

Section 5

Is it worth a note that resource servers will fetch these metadata and
use them as input to their dynamic registrations in the previous section
(i.e., picking from the list of supported algorithms)?

  introspection_encryption_alg_values_supported  OPTIONAL.  JSON array
          containing a list of the JWE [RFC7516] encryption algorithms
          ("alg" values) as defined in JWA [RFC7518] supported by the
          introspection endpoint to encrypt the response.

Similarly to the above, some refined text about "key management
algorithm" used to encrypt the response, would probably be helpful.

Section 6

There seem to be notable privacy considerations about quite a few of the
claims registered in Section 8.3.

Section 6.1

I'm surprised to not see discussion of explicit typing (and, IIUC, how
it's not a reliable mitigation) here.

  JWT introspection responses and OpenID Connect ID Tokens are
  syntactically similar.  An attacker could therefore attempt to
  impersonate an end-user at a OpenID Connect relying party by passing
  the JWT as an ID token.

nit: "response JWT" or "JWT response"

  Such an attack can be prevented like any other token substitution
  attack.  The authorization server MUST include the claims "iss" and
  "aud" in each JWT introspection response, with the "iss" value set to
  the authorization server's issuer URL and the "aud" value set to the
  resource server's identifier.  [...]

Related to the Discuss point, how does this relate to the dynamic client
registration parameters?

  [OpenID.Core].  Relying parties SHOULD also use and check the "nonce"
  parameter and claim to prevent token and code replay.

Is this SHOULD just referring to the behavior already described in
OpenID.Core (and only applicable to OIDC implementations as opposed to
JWT-instrospection consumers)?  If so, maybe descriptive language is
more appropriate, like "Relying parties are also expected to use and
check [...]".

  Resource servers utilizing JWTs to represent self-contained access
  tokens could be susceptible to replay attacks.  Resource servers
  should therefore apply proper counter measures against replay as
  described in [I-D.ietf-oauth-security-topics], section 2.2.

I'm not sure what part of this is specific to the introspection case.
Is it supposed to be tied to the risk that JWT-instrospection produces a
new route for the generation of JWT objects that could be confused for
self-contained access tokens?
nit: "countermeasures" is valid as a single word.
nit: it looks like it's section 3.2, now.

Section 6.2

Please cite RFC 7525 as BCP 195 as well as RFC 7525 (e.g., "per BCP 195
[RFC7525]").

  To prevent introspection of leaked tokens and to present an
  additional security layer against token guessing attacks the
  authorization server may require all requests to the token
  introspection endpoint to be authenticated.  As an alternative or as
  an addition to the authentication, the intended recipients may be set
  up for encrypted responses.

Do we want to make either of these "may"s into normative recommendations
(or make a recommendation for prevention of introspection data leakage
even in the face of token leakage, which can be satisfied by either
mechanism)?

Also, we could say more about how configuring encryption for intended
recipients protects against unencrypted replies to unintended
recipients...

  In the latter case, confidentiality is ensured by the fact that only
  the legitimate recipient is able to decrypt the response.  An
  attacker could try to circumvent this measure by requesting a plain
  JSON response, using an Accept header with the content type set to,
  for example, "application/json" instead of "application/jwt".  To
  prevent this attack the authorization server MUST NOT serve requests
  with content type other than "application/jwt" if the resource server
  is set up to receive encrypted responses (see also Section 3).

...such as by saying that the introspection response will only be made
available to RSes that are intended recipients of (in the audience of?)
the access token being introspected.

Section 6.3

  Authorization servers with a policy that requires token data to be
  kept confidential from OAuth clients must require all requests to the
  token introspection endpoint to be authenticated.  As an alternative
  or as an addition to the authentication, the intended recipients may
  be set up for encrypted responses.

[this also seems to be assuming a link not stated between RS policy and
AS enforcement, but it seems unlikely that a fix would need to touch
this text]

Section 8.1.1

nit: using nested lists might make this more readable.

  o  Client Metadata Description: String value specifying the desired
      introspection response encryption algorithm (alg value).

[same bit about "key management algorithm"]

Section 8.2.1

  o  Metadata Description: JSON array containing a list of algorithms
      supported by the authorization server for introspection response
      encryption (alg value).

[and here]

Section 8.3

I think we should make some mention earlier in the document
(Introduction?) that we also register some common claim values that are
in use in the wild (or whatever text you feel is appropriate to describe
the claims in question).

The nested lists would be great here as well.

Is there any expectation that some combination of "given_name",
"middle_name", and "family_name" will produce identical content to the
full "name" claim?

  o  Name: "preferred_username"

  o  Description: Shorthand name by which the End-User wishes to be
      referred to at the RP, such as janedoe or j.doe.  This value MAY
      be any valid JSON string including special characters such as @,
      /, or whitespace.

It seems like there may be some security considerations about sanitziing
this field before using it in an application's logic.

  o  Name: "profile"

  o  Description:URL of the End-User's profile page.  The contents of
      this Web page SHOULD be about the End-User.

It's slightly surpising to see this claimed for the end-user's profile
when it might equally apply to a protocol profile or variant in use.
But I assume this is already deployed, so there's no real point in
objecting to its registration...

  o  Name: "birthdate"

  o  Description:Time the End-User's information was last updated.  Its
      value is a JSON number representing the number of seconds from
      1970-01-01T0:0:0Z as measured in UTC until the date/time.

This seems potentially confusable with the user's day/year of birth.
(Also, are leap seconds excluded?)

  o  Name: "zoneinfo"

  o  Description: String from zoneinfo [zoneinfo] time zone database
      representing the End-User's time zone.  For example, Europe/Paris
      or America/Los_Angeles.

We seem to be missing the actual reference entry for [zoneinfo].

[Ballot comment]
Thank you for the hard work put into this easy to read document. I have one single COMMENT (which is more a question)

Regards,

-éric

== COMMENTS ==

-- Section 1 --

"  ... However, there are
  use cases where the resource server requires stronger assurance that
  the authorization server issued the access token, including cases
  where the authorization server assumes liability for the token's
  content... "

C.1) The example given after the above text is not obvious to understand why this memo is required. While I am not an expert on OAuth, some more explanations would probably be useful.

[Ballot discuss]
This is a fine document. I only have one small issue that should be easy to resolve:

In 8.3.1:

  o  Name: "locale"

  o  Description: Time the End-User's information was last updated.
      Its value is a JSON number representing the number of seconds from
      1970-01-01T0:0:0Z as measured in UTC until the date/time.

The description doesn’t seem to match the name.

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

The IANA Functions Operator has completed its review of draft-ietf-oauth-jwt-introspection-response-05. If any part of this review is inaccurate, please let us know.

The IANA Functions Operator understands that, upon approval of this document, there are three actions which we must complete.

First, in the OAuth Dynamic Client Registration Metadata registry on the OAuth Parameters registry page located at:

https://www.iana.org/assignments/oauth-parameters/

three, new registrations are to be made as follows:

Client Metadata Name: "introspection_signed_response_alg"
Client Metadata Description: String value indicating the client's desired introspection response signing algorithm.
Change Controller: IESG
Specification Document(s): Section 4 of [ RFC-to-be ]

Client Metadata Name: "introspection_encrypted_response_alg"
Client Metadata Description: String value specifying the desired introspection response encryption algorithm (alg value).
Change Controller: IESG
Specification Document(s): Section 4 of [ RFC-to-be ]

Client Metadata Name: "introspection_encrypted_response_enc"
Client Metadata Description: String value specifying the desired introspection response encryption algorithm (enc value).
Change Controller: IESG
Specification Document(s): Section 4 of [ RFC-to-be ]

As this document requests registrations in a Specification Required (see RFC 8126) registry, the IESG-designated expert for the OAuth Dynamic Client Registration Metadata registry has asked that you send a review request to the mailing list oauth-ext-review@ietf.org (see RFC 7591). Expert review will need to be completed before your document can be approved for publication as an RFC.

Second, in the OAuth Authorization Server Metadata registry also on the OAuth Parameters registry page located at:

https://www.iana.org/assignments/oauth-parameters/

three, new registrations are to be made as follows:

Metadata Name: "introspection_signing_alg_values_supported"
Metadata Description: JSON array containing a list of algorithms supported by the authorization server for introspection response signing.
Change Controller: IESG
Specification Document(s): Section 5 of [ RFC-to-be ]

Metadata Name: "introspection_encryption_alg_values_supported"
Metadata Description: JSON array containing a list of algorithms supported by the authorization server for introspection response encryption (alg value).
Change Controller: IESG
Specification Document(s): Section 5 of [ RFC-to-be ]

Metadata Name: "introspection_encryption_enc_values_supported"
Metadata Description: JSON array containing a list of algorithms supported by the authorization server for introspection response encryption (enc value).
Change Controller: IESG
Specification Document(s): Section 5 of [ RFC-to-be ]

As this also requests registrations in a Specification Required (see RFC 8126) registry, the IESG-designated experts for the OAuth Dynamic Client Registration Metadata registry have asked that you send a review request to the mailing list oauth-ext-review@ietf.org. Expert review will need to be completed before your document can be approved for publication as an RFC. RFC 8414 provides guidance and a registration template for this registry.

Third, in the OAuth Token Introspection Response registry also on the OAuth Parameters registry page located at:

https://www.iana.org/assignments/oauth-parameters/

nineteen, new registrations are to be made as follows:

Name: "name"
Description: End-User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User's locale and preferences.
Change Controller: IESG
Specification Document(s):[OpenID.Core http://openid.net/specs/openid-connect-core-1_0.html], Section 5.1

Name: "given_name"
Description: Given name(s) or first name(s) of the End-User. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.
Change Controller: IESG
Specification Document(s):[OpenID.Core http://openid.net/specs/openid-connect-core-1_0.html], Section 5.1

Name: "family_name"
Description: Surname(s) or last name(s) of the End-User. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.
Change Controller: IESG
Specification Document(s):[OpenID.Core http://openid.net/specs/openid-connect-core-1_0.html], Section 5.1

Name: "middle_name"
Description: Middle name(s) of the End-User. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used.
Change Controller: IESG
Specification Document(s):[OpenID.Core http://openid.net/specs/openid-connect-core-1_0.html], Section 5.1

Name: "nickname"
Description: Casual name of the End-User that may or may not be the same as the given_name. For instance, a nickname value of Mike might be returned alongside a given_name value of Michael.
Change Controller: IESG
Specification Document(s):[OpenID.Core http://openid.net/specs/openid-connect-core-1_0.html], Section 5.1

Name: "preferred_username"
Description: Shorthand name by which the End-User wishes to be referred to at the RP, such as janedoe or j.doe. This value MAY be any valid JSON string including special characters such as @, /, or whitespace.
Change Controller: IESG
Specification Document(s):[OpenID.Core http://openid.net/specs/openid-connect-core-1_0.html], Section 5.1

Name: "profile"
Description:URL of the End-User's profile page. The contents of this Web page SHOULD be about the End-User.
Change Controller: IESG
Specification Document(s):[OpenID.Core http://openid.net/specs/openid-connect-core-1_0.html], Section 5.1

Name: "picture"
Description: URL of the End-User's profile picture. This URL MUST refer to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image. Note that this URL SHOULD specifically reference a profile photo of the End-User suitable for displaying when describing the End-User, rather than an arbitrary photo taken by the End-User.
Change Controller: IESG
Specification Document(s):[OpenID.Core http://openid.net/specs/openid-connect-core-1_0.html], Section 5.1

Name: "website"
Description: URL of the End-User's Web page or blog. This Web page SHOULD contain information published by the End-User or an organization that the End-User is affiliated with.
Change Controller: IESG
Specification Document(s):[OpenID.Core http://openid.net/specs/openid-connect-core-1_0.html], Section 5.1

Name: "email"
Description: End-User's preferred e-mail address. Its value MUST conform to the [RFC5322] "addr-spec" syntax.
Change Controller: IESG
Specification Document(s):[OpenID.Core http://openid.net/specs/openid-connect-core-1_0.html], Section 5.1

Name: "email_verified"
Description: True if the End-User's e-mail address has been verified; otherwise false. When this Claim Value is true, this means that the OP took affirmative steps to ensure that this e-mail address was controlled by the End-User at the time the verification was performed. The means by which an e-mail address is verified is context-specific, and dependent upon the trust framework or contractual agreements within which the parties are operating.
Change Controller: IESG
Specification Document(s):[OpenID.Core http://openid.net/specs/openid-connect-core-1_0.html], Section 5.1

Name: "gender"
Description:End-User's gender. Values defined by this specification are female and male. Other values MAY be used when neither of the defined values are applicable.
Change Controller: IESG
Specification Document(s):[OpenID.Core http://openid.net/specs/openid-connect-core-1_0.html], Section 5.1

Name: "birthdate"
Description:Time the End-User's information was last updated. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
Change Controller: IESG
Specification Document(s):[OpenID.Core http://openid.net/specs/openid-connect-core-1_0.html], Section 5.1

Name: "zoneinfo"
Description: String from zoneinfo [zoneinfo] time zone database representing the End-User's time zone. For example, Europe/Paris or America/Los_Angeles.
Change Controller: IESG
Specification Document(s):[OpenID.Core http://openid.net/specs/openid-connect-core-1_0.html], Section 5.1

Name: "locale"
Description: Time the End-User's information was last updated. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
Change Controller: IESG
Specification Document(s):[OpenID.Core http://openid.net/specs/openid-connect-core-1_0.html], Section 5.1

Name: "phone_number"
Description: End-User's preferred telephone number. E.164 [E.164] is RECOMMENDED as the format of this Claim, for example, +1 (425) 555-1212 or +56 (2) 687 2400. If the phone number contains an extension, it is RECOMMENDED that the extension be represented using the [RFC3966] extension syntax, for example, +1 (604) 555-1234;ext=5678.
Change Controller: IESG
Specification Document(s):[OpenID.Core http://openid.net/specs/openid-connect-core-1_0.html], Section 5.1

Name: "phone_number_verified"
Description: True if the End-User's phone number has been verified; otherwise false. When this Claim Value is true, this means that the OP took affirmative steps to ensure that this phone number was controlled by the End-User at the time the verification was performed. The means by which a phone number is verified is context-specific, and dependent upon the trust framework or contractual agreements within which the parties are operating. When true, the phone_number Claim MUST be in E.164 format and any extensions MUST be represented in [RFC3966] format.
Change Controller: IESG
Specification Document(s):[OpenID.Core http://openid.net/specs/openid-connect-core-1_0.html], Section 5.1

Name: "address"
Description: End-User's preferred postal address. The value of the address member is a JSON [RFC7159] structure containing some or all of the members defined in [OpenID.Core http://openid.net/specs/openid-connect-core-1_0.html], Section 5.1.1.
Change Controller: IESG
Specification Document(s):[OpenID.Core http://openid.net/specs/openid-connect-core-1_0.html], Section 5.1

Name: "updated_at"
Description: Time the End-User's information was last updated. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
Change Controller: IESG
Specification Document(s):[OpenID.Core http://openid.net/specs/openid-connect-core-1_0.html], Section 5.1

As this also requests registrations in a Specification Required (see RFC 8126) registry, the IESG-designated expert for the OAuth Token Introspection Response registry has asked that you send a review request to the mailing list oauth-ext-review@ietf.org. Expert review will need to be completed before your document can be approved for publication as an RFC. RFC 7662 provides instructions and a template for registration in this registry.

The IANA Functions Operator understands that these are the only actions required to be completed upon approval of this document.

Note:  The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is meant only to confirm the list of actions that will be performed.

Thank you,

Sabrina Tanamal
Senior IANA Services Specialist

The following Last Call announcement was sent out (ends 2019-08-07):

From: The IESG
To: IETF-Announce
CC: rdd@cert.org, Rifaat Shekh-Yusef , rifaat.ietf@gmail.com, oauth@ietf.org, oauth-chairs@ietf.org, draft-ietf-oauth-jwt-introspection-response@ietf.org
Reply-To: ietf@ietf.org
Sender:
Subject: Last Call:  (JWT Response for OAuth Token Introspection) to Proposed Standard


The IESG has received a request from the Web Authorization Protocol WG
(oauth) to consider the following document: - 'JWT Response for OAuth Token
Introspection'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
ietf@ietf.org mailing lists by 2019-08-07. Exceptionally, comments may be
sent to iesg@ietf.org instead. In either case, please retain the beginning of
the Subject line to allow automated sorting.

Abstract


  This draft proposes an additional JSON Web Token (JWT) based response
  for OAuth 2.0 Token Introspection.




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-oauth-jwt-introspection-response/

IESG discussion can be tracked via
https://datatracker.ietf.org/doc/draft-ietf-oauth-jwt-introspection-response/ballot/


No IPR declarations have been submitted directly on this I-D.

(1) What type of RFC is being requested (BCP, Proposed Standard, Internet
Standard, Informational, Experimental, or Historic)? Why is this the proper type
of RFC? Is this type of RFC indicated in the title page header?

This specification is proposed as a 'Standards Track' document. The document
defines a new response type to an introspection request in the form of a JWT.

(2) The IESG approval announcement includes a Document Announcement Write-Up.
Please provide such a Document Announcement Write-Up. Recent examples can be
found in the "Action" announcements for approved documents. The approval
announcement contains the following sections:

Technical Summary:

This draft proposes an additional JSON Web Token (JWT) based response for OAuth
2.0 Token Introspection.

Working Group Summary:

The document received many reviews and feedbacks from multiple WG members on the
mailing list and during the WG meetings.


Document Quality:

The document has been implemented by the following:

* node.js OSS oidc-provider implements the document in full behind an optional feature toggle
https://github.com/panva/node-oidc-provider/blob/master/docs/README.md#featuresjwtintrospection

* connect2id has an implementation:
https://connect2id.com/products/server/docs/api/token-introspection

* ForgeRock:
https://github.com/ForgeRock/PSD2-Accelerators/tree/yes.com/openig/yes-openig-signed-introspect-filter



Personnel:

The document shepherd is Rifaat Shekh-Yusef.
The responsible Area Director is Roman Danyliw.


(3) Briefly describe the review of this document that was performed by the
Document Shepherd. If this version of the document is not ready for publication,
please explain why the document is being forwarded to the IESG.

The document shepherd has reviewed the document and feels the document is ready.


(4) Does the document Shepherd have any concerns about the depth or breadth of
the reviews that have been performed?

The document shepherd has no concerns with the level of reviews, as the document
was discussed and reviewed by many participants.


(5) Do portions of the document need review from a particular or from broader
perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or
internationalization? If so, describe the review that took place.

Security review is always needed and appreciated.


(6) Describe any specific concerns or issues that the Document Shepherd has with
this document that the Responsible Area Director and/or the IESG should be aware
of? For example, perhaps he or she is uncomfortable with certain parts of the
document, or has concerns whether there really is a need for it. In any event,
if the WG has discussed those issues and has indicated that it still wishes to
advance the document, detail those concerns here.

The document shepherd has no such concerns.


(7) Has each author confirmed that any and all appropriate IPR disclosures
required for full conformance with the provisions of BCP 78 and BCP 79 have
already been filed. If not, explain why?

Yes

Vladimir - https://mailarchive.ietf.org/arch/msg/oauth/N-m0lX-yFSN_WTHleZzXCeXjfDc
Torsten - https://mailarchive.ietf.org/arch/msg/oauth/gLlKNkBhs_8PCZnPehM6cGYdgaw



(8) Has an IPR disclosure been filed that references this document? If so,
summarize any WG discussion and conclusion regarding the IPR disclosures.

No such IPR disclosures.


(9) How solid is the WG consensus behind this document? Does it represent the
strong concurrence of a few individuals, with others being silent, or does the
WG as a whole understand and agree with it?

There is a solid support for this document from the WG.


(10) Has anyone threatened an appeal or otherwise indicated extreme discontent?
If so, please summarise the areas of conflict in separate email messages to the
Responsible Area Director. (It should be in a separate email because this
questionnaire is publicly available.)

No such threat or discontent.


(11) Identify any ID nits the Document Shepherd has found in this document.
(See http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist).
Boilerplate checks are not enough; this check needs to be thorough.

  Miscellaneous warnings:
  ----------------------------------------------------------------------------

  == The document seems to lack the recommended RFC 2119 boilerplate, even if
      it appears to use RFC 2119 keywords.

      (The document does seem to have the reference to RFC 2119 which the
      ID-Checklist requires).
  -- The document date (May 21, 2019) is 13 days in the past.  Is this
      intentional?


  Checking references for intended status: Proposed Standard
  ----------------------------------------------------------------------------

      (See RFCs 3967 and 4897 for information about using normative references
      to lower-maturity documents in RFCs)

  == Missing Reference: 'RFC5322' is mentioned on line 461, but not defined

  == Missing Reference: 'RFC3966' is mentioned on line 527, but not defined

  == Missing Reference: 'RFC4627' is mentioned on line 553, but not defined

  ** Obsolete undefined reference: RFC 4627

  == Unused Reference: 'RFC2119' is defined on line 596, but no explicit
      reference was found in the text

  == Unused Reference: 'RFC2246' is defined on line 601, but no explicit
      reference was found in the text

  == Outdated reference: A later version (-05) exists of
      draft-ietf-oauth-jwt-bcp-04

  == Outdated reference: A later version (-12) exists of
      draft-ietf-oauth-security-topics-11

  ** Obsolete normative reference: RFC 2246


      Summary: 2 errors (**), 0 flaws (~~), 8 warnings (==), 1 comment (--).
     


(12) Describe how the document meets any required formal review criteria,
such as the MIB Doctor, media type, and URI type reviews.

No such reviews are necessary.


(13) Have all references within this document been identified as either
normative or informative?

Yes.


(14) Are there normative references to documents that are not ready for
advancement or are otherwise in an unclear state? If such normative references
exist, what is the plan for their completion?

The document has a reference to the I-D.ietf-oauth-security-topics which is still
under discussion at the WG.

The document also has a references to the I-D.ietf-oauth-jwt-bcp which should be
published soon.


(15) Are there downward normative references (see RFC 3967)? If so, list these
downward references to support the Area Director in the Last Call procedure.

No such references.


(16) Will publication of this document change the status of any existing RFCs?
Are those RFCs listed on the title page header, listed in the abstract, and
discussed in the introduction? If the RFCs are not listed in the Abstract and
Introduction, explain why, and point to the part of the document where the
relationship of this document to the other RFCs is discussed. If this
information is not in the document, explain why the WG considers it unnecessary.

No status change of any existing RFCs.


(17) Describe the Document Shepherd's review of the IANA considerations section,
especially with regard to its consistency with the body of the document. Confirm
that all protocol extensions that the document makes are associated with the
appropriate reservations in IANA registries. Confirm that any referenced IANA
registries have been clearly identified. Confirm that newly created IANA
registries include a detailed specification of the initial contents for the
registry, that allocations procedures for future registrations are defined, and
a reasonable name for the new registry has been suggested (see RFC 5226).

The IANA section is complete and correct.


(18) List any new IANA registries that require Expert Review for future
allocations. Provide any public guidance that the IESG would find useful in
selecting the IANA Experts for these new registries.

No new IANA registries.


(19) Describe reviews and automated checks performed by the Document Shepherd to
validate sections of the document written in a formal language, such as XML
code, BNF rules, MIB definitions, etc.

The document contains JSON-based examples, and these were validated using
JSONLint.

(1) What type of RFC is being requested (BCP, Proposed Standard, Internet
Standard, Informational, Experimental, or Historic)? Why is this the proper type
of RFC? Is this type of RFC indicated in the title page header?

This specification is proposed as a 'Standards Track' document. The document
defines a new response type to an introspection request in the form of a JWT.

(2) The IESG approval announcement includes a Document Announcement Write-Up.
Please provide such a Document Announcement Write-Up. Recent examples can be
found in the "Action" announcements for approved documents. The approval
announcement contains the following sections:

Technical Summary:

This draft proposes an additional JSON Web Token (JWT) based response for OAuth
2.0 Token Introspection.

Working Group Summary:

The document received many reviews and feedbacks from multiple WG members on the
mailing list and during the WG meetings.


Document Quality:

The document has been implemented by the following:

* node.js OSS oidc-provider implements the document in full behind an optional feature toggle
https://github.com/panva/node-oidc-provider/blob/master/docs/README.md#featuresjwtintrospection

* connect2id has an implementation:
https://connect2id.com/products/server/docs/api/token-introspection

* ForgeRock:
https://github.com/ForgeRock/PSD2-Accelerators/tree/yes.com/openig/yes-openig-signed-introspect-filter



Personnel:

The document shepherd is Rifaat Shekh-Yusef.
The responsible Area Director is Roman Danyliw.


(3) Briefly describe the review of this document that was performed by the
Document Shepherd. If this version of the document is not ready for publication,
please explain why the document is being forwarded to the IESG.

The document shepherd has reviewed the document and feels the document is ready.


(4) Does the document Shepherd have any concerns about the depth or breadth of
the reviews that have been performed?

The document shepherd has no concerns with the level of reviews, as the document
was discussed and reviewed by many participants.


(5) Do portions of the document need review from a particular or from broader
perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or
internationalization? If so, describe the review that took place.

Security review is always needed and appreciated.


(6) Describe any specific concerns or issues that the Document Shepherd has with
this document that the Responsible Area Director and/or the IESG should be aware
of? For example, perhaps he or she is uncomfortable with certain parts of the
document, or has concerns whether there really is a need for it. In any event,
if the WG has discussed those issues and has indicated that it still wishes to
advance the document, detail those concerns here.

The document shepherd has no such concerns.


(7) Has each author confirmed that any and all appropriate IPR disclosures
required for full conformance with the provisions of BCP 78 and BCP 79 have
already been filed. If not, explain why?

Yes

Vladimir - https://mailarchive.ietf.org/arch/msg/oauth/N-m0lX-yFSN_WTHleZzXCeXjfDc
Torsten - https://mailarchive.ietf.org/arch/msg/oauth/gLlKNkBhs_8PCZnPehM6cGYdgaw



(8) Has an IPR disclosure been filed that references this document? If so,
summarize any WG discussion and conclusion regarding the IPR disclosures.

No such IPR disclosures.


(9) How solid is the WG consensus behind this document? Does it represent the
strong concurrence of a few individuals, with others being silent, or does the
WG as a whole understand and agree with it?

There is a solid support for this document from the WG.


(10) Has anyone threatened an appeal or otherwise indicated extreme discontent?
If so, please summarise the areas of conflict in separate email messages to the
Responsible Area Director. (It should be in a separate email because this
questionnaire is publicly available.)

No such threat or discontent.


(11) Identify any ID nits the Document Shepherd has found in this document.
(See http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist).
Boilerplate checks are not enough; this check needs to be thorough.

  Miscellaneous warnings:
  ----------------------------------------------------------------------------

  == The document seems to lack the recommended RFC 2119 boilerplate, even if
      it appears to use RFC 2119 keywords.

      (The document does seem to have the reference to RFC 2119 which the
      ID-Checklist requires).
  -- The document date (May 21, 2019) is 13 days in the past.  Is this
      intentional?


  Checking references for intended status: Proposed Standard
  ----------------------------------------------------------------------------

      (See RFCs 3967 and 4897 for information about using normative references
      to lower-maturity documents in RFCs)

  == Missing Reference: 'RFC5322' is mentioned on line 461, but not defined

  == Missing Reference: 'RFC3966' is mentioned on line 527, but not defined

  == Missing Reference: 'RFC4627' is mentioned on line 553, but not defined

  ** Obsolete undefined reference: RFC 4627

  == Unused Reference: 'RFC2119' is defined on line 596, but no explicit
      reference was found in the text

  == Unused Reference: 'RFC2246' is defined on line 601, but no explicit
      reference was found in the text

  == Outdated reference: A later version (-05) exists of
      draft-ietf-oauth-jwt-bcp-04

  == Outdated reference: A later version (-12) exists of
      draft-ietf-oauth-security-topics-11

  ** Obsolete normative reference: RFC 2246


      Summary: 2 errors (**), 0 flaws (~~), 8 warnings (==), 1 comment (--).
     


(12) Describe how the document meets any required formal review criteria,
such as the MIB Doctor, media type, and URI type reviews.

No such reviews are necessary.


(13) Have all references within this document been identified as either
normative or informative?

Yes.


(14) Are there normative references to documents that are not ready for
advancement or are otherwise in an unclear state? If such normative references
exist, what is the plan for their completion?

The document has a reference to the I-D.ietf-oauth-security-topics which is still
under discussion at the WG.

The document also has a references to the I-D.ietf-oauth-jwt-bcp which should be
published soon.


(15) Are there downward normative references (see RFC 3967)? If so, list these
downward references to support the Area Director in the Last Call procedure.

No such references.


(16) Will publication of this document change the status of any existing RFCs?
Are those RFCs listed on the title page header, listed in the abstract, and
discussed in the introduction? If the RFCs are not listed in the Abstract and
Introduction, explain why, and point to the part of the document where the
relationship of this document to the other RFCs is discussed. If this
information is not in the document, explain why the WG considers it unnecessary.

No status change of any existing RFCs.


(17) Describe the Document Shepherd's review of the IANA considerations section,
especially with regard to its consistency with the body of the document. Confirm
that all protocol extensions that the document makes are associated with the
appropriate reservations in IANA registries. Confirm that any referenced IANA
registries have been clearly identified. Confirm that newly created IANA
registries include a detailed specification of the initial contents for the
registry, that allocations procedures for future registrations are defined, and
a reasonable name for the new registry has been suggested (see RFC 5226).

The IANA section is complete and correct.


(18) List any new IANA registries that require Expert Review for future
allocations. Provide any public guidance that the IESG would find useful in
selecting the IANA Experts for these new registries.

No new IANA registries.


(19) Describe reviews and automated checks performed by the Document Shepherd to
validate sections of the document written in a formal language, such as XML
code, BNF rules, MIB definitions, etc.

The document contains JSON-based examples, and these were validated using
JSONLint.