OAuth 2.0 Token Introspection
draft-ietf-oauth-introspection-11

[Ballot comment]
Thanks for addressing my DISCUSS and most of my comments.  The important comment that still remains is this:

-- Section 3.1 --
I'd REALLY like to see us stop trying to tell IANA how to handle review by designated experts.  This should be re-cast as instructions to the DE (to make sure that the mailing list is consulted), and IANA should be left to handle the expert review with their existing process, which works fine.

While we're at it, it would be nice to have some further instruction to the DEs about what they should be looking at when deciding whether to approve a request.  There's some very minimal instruction under "name" in the template, but that's all.  Is there nothing more to say?

For the spop document, I suggested the text change below.  Something similar for this document would be great:

For the spop document, not this one!:
OLD


NEW
  Additional code_challenge_method types for use with the authorization
  endpoint are registered using the Specification Required policy
  [RFC5226], which includes review of the request by one or more
  Designated Experts.  The DEs will ensure there is at least a two-week
  review of the request on the oauth-ext-review@ietf.org mailing list,
  and that any discussion on that list converges before they respond to
  the request.  To allow for the allocation of values prior to
  publication, the Designated Expert(s) may approve registration once
  they are satisfied that an acceptable specification will be published.

  Discussion on the oauth-ext-review@ietf.org mailing list should use
  an appropriate subject, such as "Request for PKCE
  code_challenge_method: example").

  The Designated Expert(s) should consider the discussion on the
  mailing list, as well as <> when evaluating
  registration requests.  Denials should include an explanation
  and, if applicable, suggestions as to how to make the request
  successful.
END

[Ballot comment]
Lionel Morand reviewed for the ops directorate



I have reviewed this document as part of the Operational directorate's ongoing effort to review all IETF documents being processed by the IESG.  These comments were written with the intent of improving the operational aspects of the

IETF drafts. Comments that are not addressed in last call may be included in AD reviews during the IESG review.  Document editors and WG chairs should treat these comments just like any other last call comments.



This document is well-written, clear and almost ready to be published. I have however some comments:



1/ I share the comment from Barry regarding "MUST support POST, and MAY support GET" in section 2.1.

2/ Sorry if it is obvious but there is no indication on how the protected resources discover the introspection endpoint to which send the request. It might be explained in some other documents but we could find this information in this document as well (or at least a reference).



Minors comments:



sect 2.1:



  The endpoint MAY allow other parameters to provide further context to

  the query.  For instance, an authorization service may need to know

  the IP address of the client accessing the protected resource in

  order to determine the appropriateness of the token being presented.



Which endpoint are you referring to at the beginning of the sentence? introspection endpoint, Authorization endpoint, token endpoint, other ? I guess it is the first one but please clarify.



In the second sentence, I think it is "authorization server" instead of "authorization service"



Regards,



Lionel

_________________________________________________________________________________________________________________________

Ce message et ses pieces jointes peuvent contenir des informations confidentielles ou privilegiees et ne doivent donc
pas etre diffuses, exploites ou copies sans autorisation. Si vous avez recu ce message par erreur, veuillez le signaler
a l'expediteur et le detruire ainsi que les pieces jointes. Les messages electroniques etant susceptibles d'alteration,
Orange decline toute responsabilite si ce message a ete altere, deforme ou falsifie. Merci.

This message and its attachments may contain confidential or privileged information that may be protected by law;
they should not be distributed, used or copied without authorisation.
If you have received this email in error, please notify the sender and delete this message and its attachments.
As emails may be altered, Orange is not liable for messages that have been modified, changed or falsified.
Thank you.



_______________________________________________
OPS-DIR mailing list
OPS-DIR@ietf.org
https://www.ietf.org/mailman/listinfo/ops-dir

[Ballot discuss]
After initial discussion, I'm moving this to a DISCUSS point:

-- Section 2.1 --
The server MUST support POST, and MAY support GET.  What's the value in that?  I don't see any way for a client (I mean HTTP client, not Oauth client, here) to know, so all clients will have to send POST to be sure it will work.  Are you really expecting to have clients that want to ask this, but that can't send POST?  Given that you call out privacy concerns with GET, I don't see why it's there at all.

In initial discussion Justin says that GET is "a deployment optimization that some servers will offer", and "The OAuth client might know through configuration (assuming a tighter coupling than defined by the interoperable protocol)," to which I responded thus:

1. Why is GET an optimization?  It has privacy disadvantages, and I don't see any advantages.

2. This "tight coupling" thing is something that I think weakens the interoperability of the OAuth protocol in general, and I've never liked it.  In this case, in particular, I don't see any advantage to it, and I don't understand why it's useful to have an option that only works if you have inside knowledge, for no benefit.

Why is it ever good to have clients that only work with certain servers, when it's just as easy to make sure that all clients work with all servers?

[Ballot comment]
All of the stuff below is fairly minor and isn't blocking... but I would like to discuss with you any items that you disagree with, please.

-- Section 1 --

   This specification defines an interoperable web API

How is that different from, "This specification defines an API"?  I don't know why a web API differs from any other kind of API, nor what makes an API particularly interoperable.  That said, this document appears not to be defining an API at all... it seems to be defining a protocol.  Why do you think it's an API?

-- Section 2 --

   The introspection endpoint MUST be protected by a transport-layer
   security mechanism as described in Section 4.

I know what it means for a communication path to be protected by TLS, but I don't know what it means for an endpoint to be.  Can you explain that?

-- Section 2.2 --
The definition of "scope" is odd, because I think you mean that it's a single JSON string, and that the content of the string is a space-separated list of scope values... it's not actually multiple JSON strings, right?

-- Section 3.1 --
I'd REALLY like to see us stop trying to tell IANA how to handle review by designated experts.  This should be re-cast as instructions to the DE (to make sure that the mailing list is consulted), and IANA should be left to handle the expert review with their existing process, which works fine.

While we're at it, it would be nice to have some further instruction to the DEs about what they should be looking at when deciding whether to approve a request.  There's some very minimal instruction under "name" in the template, but that's all.  Is there nothing more to say?

-- References --
Because many of the items in the response are defined in RFC 7519, I think that RFC should be a normative reference.

[Ballot comment]
I concur with Alissa's discuss. 

Additional comments:

-- There is no reference to RFC 2119, but there seems to be lots of capitalized 2119 keywords. If those are intended to have the 2119 meaning, please add the usual reference. (I assume that these are intended as 2119 keywords for the remainder of the review.)

-- 2.1, first paragraph:

If the server MAY support GET, how does a client know to use it? Would you expect them to try and fail?

-- 3

Is there a reason not to use a more standard IANA procedure? (I.e. let people request registrations to IANA, and have them forward the requests to the DE?)

--3.1, under "Name"

The MUST seems unnecessary, as that's the whole point of a registry.

-- 4:
The security considerations have a lot of restated 2119 keywords. If you want to reinforce those here, it would be better to do so with descriptive language, rather than having multiple occurrences of the same normative language.  Redundant normative language is error prone, especially for future updates.

-- 4, bullet list:


It seems odd to have 2119 keywords in a "For instance" section.

--4, 6th paragraph from end

The reference to [TLS.BCP] should probably be normative.

-- 4, last two paragraphs:

"An authorization server offering token introspection MUST be able to understand the token values being presented to it during this call." and "the authorization server MUST be able to decrypt and validate the token in order to access this information."

These seem more like statements of fact than normative language.

[Ballot discuss]
= Section 2.1 =
"The endpoint MAY allow other parameters to provide further context to
  the query.  For instance, an authorization service may need to know
  the IP address of the client accessing the protected resource in
  order to determine the appropriateness of the token being presented."

How does the protected resource know whether it needs to include such additional parameters or not? What is meant by the "appropriateness" of the token?

In general if we're talking about a piece of data that could be sensitive like client IP address, it would be better for there to be specific guidelines to direct protected resources as to when this information needs to be sent. I note that Section 5 basically says such considerations are out of scope, but if this specific example is to be provided here then they seem in scope to me.

= Section 5 =
"One way to limit disclosure is to require
  authorization to call the introspection endpoint and to limit calls
  to only registered and trusted protected resource servers."

I thought Section 2.1 made authorization to call the introspection endpoint mandatory. This makes it sound like it's optional. Which is it?

[Ballot comment]
= Section 1.1 =
There is no reference to RFC2119 here, which may be okay but most documents include it if they use normative language (I think).

= Section 2 =
"The
  definition of an active token is up to the authorization server, but
  this is commonly a token that has been issued by this authorization
  server, is not expired, has not been revoked, and is within the
  purview of the protected resource making the introspection call."

Is "within the purview" a term of art for OAuth 2.0? Is there a more specific way to describe what is meant here? Also, I note that in the description of the "active" member in Section 2.2, this criterion is not listed. It seems like these should be aligned.

= Section 2.2 =
"Note that in order to avoid disclosing too much of the
  authorization server's state to a third party, the authorization
  server SHOULD NOT include any additional information about an
  inactive token, including why the token is inactive."

Seems like this should be a MUST NOT unless there's some reason for providing anything other than active set to false. Same comment applies in Section 4.

= Section 2.3 =
It seems like there is another error condition and I'm wondering if its handling needs to be specified. Per my question in Section 2.1, if it's possible that the request is properly formed but is missing some additional information that the authorization server needs to evaluate it, should there be an error condition specified for that case?

[Ballot comment]
All of the stuff below is fairly minor and isn't blocking... but I would like to discuss with you any items that you disagree with, please.

-- Section 1 --

   This specification defines an interoperable web API

How is that different from, "This specification defines an API"?  I don't know why a web API differs from any other kind of API, nor what makes an API particularly interoperable.  That said, this document appears not to be defining an API at all... it seems to be defining a protocol.  Why do you think it's an API?

-- Section 2 --

   The introspection endpoint MUST be protected by a transport-layer
   security mechanism as described in Section 4.

I know what it means for a communication path to be protected by TLS, but I don't know what it means for an endpoint to be.  Can you explain that?

-- Section 2.1 --
The server MUST support POST, and MAY support GET.  What's the value in that?  I don't see any way for a client (I mean HTTP client, not Oauth client, here) to know, so all clients will have to send POST to be sure it will work.  Are you really expecting to have clients that want to ask this, but that can't send POST?  Given that you call out privacy concerns with GET, I don't see why it's there at all.

-- Section 2.2 --
The definition of "scope" is odd, because I think you mean that it's a single JSON string, and that the content of the string is a space-separated list of scope values... it's not actually multiple JSON strings, right?

-- Section 3.1 --
I'd REALLY like to see us stop trying to tell IANA how to handle review by designated experts.  This should be re-cast as instructions to the DE (to make sure that the mailing list is consulted), and IANA should be left to handle the expert review with their existing process, which works fine.

While we're at it, it would be nice to have some further instruction to the DEs about what they should be looking at when deciding whether to approve a request.  There's some very minimal instruction under "name" in the template, but that's all.  Is there nothing more to say?

-- References --
Because many of the items in the response are defined in RFC 7519, I think that RFC should be a normative reference.

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

IANA has reviewed draft-ietf-oauth-introspection-08.  Authors should review the comments and/or questions below.  Please report any inaccuracies and respond to any questions as soon as possible.

We received the following comments/questions from the IANA's reviewer:

IANA has a question about one of the actions requested in the IANA Considerations section of this document.

IANA understands that, upon approval of this document there is a single action which needs to be completed.

IANA understands that a new registry is to be created called the OAuth Token Introspection Response registry. This new registry would be managed using Specification Required as defined in RFC 5226. IANA understands that a template for further maintenance of the registry has been placed in section 3.1.1 of the current document.

IANA QUESTION -> Where should this new registry be located? Is it a néw registry on the IANA Matrix
(http://www.iana.org/protocols) or is it a subregistry of an existing registry? If it is a subregistry of an existing registry, in which registry will it be contained?  Is the new registry under this existing
heading OAuth Parameters located at http://www.iana.org/protocols? 

In the located to be determined at a later time (see above question), there will be twelve initial registrations in the new registry as follows:

Name: active
Description: Token active status
Change Controller: IESG
Specification Document(s): Section 2.2 of [ RFC-to-be ]

Name: username
Description: User identifier of the resource owner
Change Controller: IESG
Specification Document(s): Section 2.2 of [ RFC-to-be ]

Name: client_id
Description: Client identifier of the client
Change Controller: IESG
Specification Document(s): Section 2.2 of [ RFC-to-be ]

Name: scope
Description: Authorized scopes of the token
Change Controller: IESG
Specification Document(s): Section 2.2 of [ RFC-to-be ]

Name: token_type
Description: Type of the token
Change Controller: IESG
Specification Document(s): Section 2.2 of [ RFC-to-be ]

Name: exp
Description: Expiration timestamp of the token
Change Controller: IESG
Specification Document(s): Section 2.2 of [ RFC-to-be ]

Name: iat
Description: Issuance timestamp of the token
Change Controller: IESG
Specification Document(s): Section 2.2 of [ RFC-to-be ]

Name: nbf
Description: Timestamp which the token is not valid before
Change Controller: IESG
Specification Document(s): Section 2.2 of [ RFC-to-be ]

Name: sub
Description: Subject of the token
Change Controller: IESG
Specification Document(s): Section 2.2 of [ RFC-to-be ]

Name: aud
Description: Audience of the token
Change Controller: IESG
Specification Document(s): Section 2.2 of [ RFC-to-be ]

Name: iss
Description: Issuer of the token
Change Controller: IESG
Specification Document(s): Section 2.2 of [ RFC-to-be ]

Name: jti
Description: Unique identifier of the token
Change Controller: IESG
Specification Document(s): Section 2.2 of [ RFC-to-be ]

IANA understands that this is the only action that needs 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 only to confirm what actions will be performed.

The following Last Call announcement was sent out:

From: The IESG
To: IETF-Announce
CC:
Reply-To: ietf@ietf.org
Sender:
Subject: Last Call:  (OAuth 2.0 Token Introspection) to Proposed Standard


The IESG has received a request from the Web Authorization Protocol WG
(oauth) to consider the following document:
- 'OAuth 2.0 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 2015-06-01. 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 defines a method for a protected resource to query
  an OAuth 2.0 authorization server to determine the active state of an
  OAuth 2.0 token and to determine meta-information about this token.
  OAuth 2.0 deployments can use this method to convey information about
  the authorization context of the token from the authorization server
  to the protected resource.





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

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


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

Shepherd writeup for "OAuth 2.0 Token Introspection"

 

As required by RFC 4858, this is the current template for the Document
Shepherd Write-Up.

(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?


Standards Track

(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

  The "OAuth 2.0 Token Introspection" specification defines a method
  for a protected resource to query an OAuth 2.0 authorization server
  to determine the active state of an OAuth 2.0 token and to determine
  meta-information about this token. OAuth 2.0 deployments can use
  this method to convey information about the authorization context
  of the token from the authorization server to the protected resource.
 
Working Group Summary

  Was there anything in WG process that is worth noting? For
  example, was there controversy about particular points or
  were there decisions where the consensus was particularly
  rough?

There was no controversy. When the specification was brought
to the working group the concept was already well established and
in use.

 
Document Quality

  Are there existing implementations of the protocol? Have a
  significant number of vendors indicated their plan to
  implement the specification? Are there any reviewers that
  merit special mention as having done a thorough review,
  e.g., one that resulted in important changes or a
  conclusion that the document had no substantive issues? If
  there was a MIB Doctor, Media Type or other expert review,
  what was its course (briefly)? In the case of a Media Type
  review, on what date was the request posted?

There are multiple implementations of this specification:

* MITREid Connect:
https://github.com/mitreid-connect/OpenID-Connect-Java-Spring-Server/

* WSO2 suite:
http://pzf.fremantle.org/2013/11/oauth2-introspection-with-wso2-esb-and.html

* PHP AS:
https://github.com/fkooman/php-oauth-as

As well as any compliant UMA implementation (so, CloudIdentity, Gluu oxAuth, etc.).
 
Personnel

  Who is the Document Shepherd? Who is the Responsible Area
  Director?

Hannes Tschofenig is the document shepherd and Kathleen Moriarty is
the responsible area director.
 
(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 shepherd has reviewed the document and posted review comments
to the mailing list. Those comments have been addressed.

(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 regarding the depth and breadth
of the reviews.

(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.

Review from the IETF security community would be appreciated but no
other particular review activities are otherwise necessary.

(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.

There are no concerns with this document.

(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.

Justin Richer, the document author, has confirmed full conformance with the
provisions of BCP 78 and BCP 79:
https://www.ietf.org/mail-archive/web/oauth/current/msg14106.html

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

No IPR disclosures have been filed.

(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? 

The working group has consensus to publish this document as a
Standards Track specification.

(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 appeal / extreme discontent has been raised.


(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.

The shepherd checked nits.

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

No such formal reviews are needed.

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

Yes; references are separated into informative and normative.

(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?

All normative references are published RFC documents / W3C specifications.

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

There no downward normative references. There is only a reference to
a W3C document, namely HTML5.

(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.

This document does not change the status 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 consideration section defines a new registry, called
"OAuth Token Introspection Response Registry", and populates this
registry with 12 values. The IANA consideration section is
consistent with the main body of the document.


(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.

The OAuth Token Introspection Response Registry is a new registry
and it requires expert review. The following persons would be
adequate experts for this registry: Mike Jones, Brian Campbell,
John Bradley, and Justin Richer.

(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 shepherd has verified the JSON code with JSONLint.