Resource Indicators for OAuth 2.0
draft-ietf-oauth-resource-indicators-08

[Ballot comment]
Thank for for writing this document -- it is way outside my area of expertise, but I found it to be readable anyway :-)
Also, thanks to Shwetha Bhandari for the OpsDir review.

[Ballot comment]
Thank you for this easy-to-read-document -- reducing the risk of using
bearer tokens seems worthwhile, since they are not going away very
quickly.

Abstract

This seems to be a sentence fragment (maybe preface with "This document
specifies"?).

Section 1

                                                          When the
  authorization server is informed of the resource that will process
  the access token, it can restrict the intended audience of that token
  to the given resource such that the token cannot be used successfully
  at other resources.

(This mechanism is only effective if the other resources are
checking in some fashion, whether by direct inspection of a structured
token or by a backchannel to the AS or otherwise, but I hope that
checking 'aud' is standard practice by now!)

Section 2.1

  For authorization requests sent as a JWTs, such as when using JWT
  Secured Authorization Request [I-D.ietf-oauth-jwsreq], a single
  "resource" parameter value is represented as a JSON string while
  multiple values are represented as an array of strings.

jwsreq includes an example with "aud" in the request, yet this new
"resource" request parameter is also intended to influence the audience
of the resulting token.  I'm not sure whether we need to say anything
specifically about this in the document, but I'd like to have a better
understanding of how "aud" and "resource" would interact when both
present in the reqeust.
(This is presumably related to why the request parameter is called
"resource" and not "aud" or "audience", but unfortunately I seem to have
zoned out for that part of the WG discussion.)

  If the client omits the "resource" parameter when requesting
  authorization, the authorization server MAY process the request with
  no specific resource or by using a pre-defined default resource
  value.  [...]

Would/could this default value be global or on a per-scope basis or some
other finer granularity than global?

                                                                    The
  authorization server might use this data to inform the user about the
  resources the client is going to access on her behalf, to meet policy
  decision (e.g. refuse the request due to unknown resources), and
  determine the set of resources that can be used in subsequent access
  token requests.

nits: comma after "e.g.", and maybe s/meet policy decision/apply policy/
(or similar), and "to" before "determine" for parallelism.

In Figure 1 we URL-encode the '.'s in "client.example.org" but not in
"api.example.com" in the request URL; should we be consistent?  (This
seems to be recurring throughout the examples.)

Section 2.2

  needs to know.  This further improves privacy as scope values give an
  indication of what services the resource owner uses and downscoping a
  token to only that which is needed for a particular service can limit
  the extent to which such information is revealed across different
  services.  As specified in Section 5.1 of [RFC6749], the

(nit?) I suggest to s/scope values give an indication of what services
the resource owner uses and/a list of scope values is an indication that the
resource owner uses the multiple various services listed;/ since I
misparsed it the first time as-is.

Section 3

  An access token that is audience restricted to a protected resource
  that obtains that token legitimately cannot be used to access
  resources on behalf of the resource owner at other protected
  resources.  The "resource" parameter enables a client to indicate the

nit: This sentence has a pretty strange construction.  I think the
intent is to say that that a token, legitimately presented to a
resource, cannot then be taken by that resource server and
illegitimately present it somewhere else for access to other resources.
But with the current wording we seem to be missing part of the part
where some entity obtains the token with intent for illegitimate access.

  Some servers may host user content or be multi-tenant.  In order to
  avoid attacks that might confuse a client into sending an access
  token to a resource that is user controlled or is owned by a
  different tenant, it is important to use a specific resource URI
  including a path component.  This will cause any access token issued
  for accessing the user controlled resource to have an invalid
  audience if replayed against the legitimate resource API.

I'm not entirely sure what this is trying to say.  What is the
"legitimate resource API"?  Why would a token be issued for accessing a
user-controlled resource if that's something we're trying to avoid
having confused clients access?

  Although multiple occurrences of the "resource" parameter may be
  included in a request, using only a single "resource" parameter is
  encouraged.  A bearer token that has multiple intended recipients
  (audiences) indicating that the token is valid at more than one
  protected resource can be used by any one of those protected
  resources to access any of the other protected resources.  Thus, a
  high degree of trust between the involved parties is needed when
  using access tokens with multiple audiences.  Furthermore an
  authorization server may be unwilling or unable to fulfill a token
  request with multiple resources.

Do we want to contrast this with an authorization code/refresh token,
which may be more likely to be issued with a multiple-resource/audience
property?

[Ballot comment]
Many thanks to everyone who worked on this refinement to OAuth.
It seems like it will be a significant improvement over today's
ad-hoc system.

I agree with Barry and Alexey about the need for some language discussing
the privacy implications of explicitly signaling audience resources to
OAuth servers.

---------------------------------------------------------------------------

§2:

>  The client SHOULD use the base URI of the API
>  as the "resource" parameter value unless specific knowledge of the
>  resource dictates otherwise.  For example, the value
>  "https://api.example.com/" would be used for a resource that is the
>  exclusive application on that host, however, if the resource is one
>  of many applications on that host, something like
>  "https://api.example.com/app/" would be used as a more specific
>  value.  Another example, for an API like SCIM [RFC7644] that has
>  multiple endpoints such as "https://apps.example.com/scim/Users",
>  "https://apps.example.com/scim/Groups", and
>  "https://apps.example.com/scim/Schemas" The client would use
>  "https://apps.example.com/scim/" as the resource so that the issued
>  access token is valid for all the endpoints of the SCIM API.

This seems pretty intuitive in the examples given. It may be a little
less clear when applications are indicated by query parameter instead
of path prefixes. For example, if an endpoint is running two applications
distinguished thus:

https://example.com/apps/?app=app1
https://example.com/apps/?app=app2

...and in a form that allows for additional parameters:

https://example.com/apps/?darkmode=true&version=1.2&app=app2

...then the notion of the "most specific API" isn't quite as clear.
Intuitively, I think the idea would be that the resource for app2
would be . It may be useful
to include an example along these lines as an illustration.

---------------------------------------------------------------------------

§2.2:

>    &resource=https%3A%2F%2Fcontacts.example.com%2Fapp%2F
...
>        "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6Ijc3In0.eyJpc3MiOi
>        JodHRwOi8vYXV0aG9yaXphdGlvbi1zZXJ2ZXIuZXhhbXBsZS5jb20iLCJzdWI
>        iOiJfX2JfYyIsImV4cCI6MTU4ODQyMDgyNiwic2NvcGUiOiJjb250YWN0cyIs
>        ImF1ZCI6Imh0dHBzOi8vY29udGFjdHMuZXhhbXBsZS5jb20vIn0.5f4yhqazc
>        OSlJw4y94KPeWNEFQqj2cfeO8x4hr3YbHtIl3nQXnBMw5wREY5O1YbZED-GfH
>        UowfmtNaA5EikYAw",

The "aud" value here is "https://contacts.example.com/" rather than the
"https://contacts.example.com/app/" that I would expect -- that is, I would
expect them to match. Am I misunderstanding the intended relationship between
"resouce" and "aud"?

---------------------------------------------------------------------------

§3:

>  Some servers may host user content or be multi-tenant.  In order to
>  avoid attacks that might confuse a client into sending an access
>  token to a resource that is user controlled or is owned by a
>  different tenant, it is important to use a specific resource URI
>  including a path component.

Related to my comment about §2 above, "path component" isn't quite sufficient.
What you want is "including any portion of the URI that identifies the
resource, such as a path component."

[Ballot comment]
-- Section 2 --

  invalid_target
      The requested resource is invalid, unknown, or malformed.

For clarity, I suggest adding "missing" to the list, as specified in Section 2.1, '...and MAY fail requests that omit the parameter with an "invalid_target" error.'

  The authorization server SHOULD audience restrict issued access
  tokens to the resource(s) indicated by the "resource" parameter.

I can't parse this sentence.  I see "audience" as a verb, and don't understand.
AH.  I read later in the document and figured out my problem: I think it would help if you hyphenate "audience-restrict" (and "audience-restricted" later).  No?

[Ballot comment]
Thank you for the hard work put into this easy to read document.

Regards,

-éric

== COMMENTS ==

-- Section 1 --
"has uncovered a need, in some circumstances" (and similar sentences in section 1), it is rather vague for a standard track document... Please add some facts and data, this could be a companion document about requirements/use cases.
 
-- Section 2 --
It is rather a question of mine, why does the resource need to be a URI (which usually bears some visible semantics) rather than an opaque string known only by the resource owner/server ? This is similar to Mirja's comment about privacy.

[Ballot comment]
I agree with Alexey that it would be good to mention any privacy implications of providing this additional information to the auth server in the security consideration section; maybe also further advising clients on which resources to request when.

[Ballot comment]
I like this document.

Is tracking by authorization server a concern? I suspect on the balance it is less important than restricting token scope (and thus improving security of bearer tokens), but maybe this shoukd be mentioned in the Security Considerations.

(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
adds new parameter for requests sent by a Client to an Authorization Server.
The type of RFC is indicated in the title page header.

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

An extension to the OAuth 2.0 Authorization Framework defining request
parameters that enable a client to explicitly signal to an authorization server
about the identity of the protected resource(s) to which it is requesting
access.

Working Group Summary:

The document adds new parameter for requests sent by a Client to an
Authorization Server.
The document received many reviews and feedbacks from multiple WG members on the
mailing list and during the WG meetings.
The document was updated to reflect a late review to make sure that the document
makes it clear that the parameter might carry a location or an abstract identifier.


Document Quality:

The document has been implemented by the following:

* Ping has an implementation but with a different parameter name ("aud"):
https://documentation.pingidentity.com/pingfederate/pf92/index.shtml#adminGuide/tokenEndpoint.html

* Microsoft
https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-protocols-oauth-code

* Auth0 has an implementation but with a different parameter name ("audience"):
https://auth0.com/docs/api/authentication#authorize-application

* Node.JS Open Source oidc-provider implements the draft in full
https://github.com/panva/node-oidc-provider/blob/master/docs/configuration.md#featuresresourceindicators

* ARM has an implementation as pard of the Pelion Secure Device Access (SDA) product:
https://cloud.mbed.com/docs/v1.2/device-management/secure-device-access.html



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.
Brian: https://mailarchive.ietf.org/arch/msg/oauth/W7JJTWO-CZ0PlJmA5YKsTpvDrbs
John: https://mailarchive.ietf.org/arch/msg/oauth/hYALU3rRmTKvZvsUIN3j8BeHT_M
Hannes: https://mailarchive.ietf.org/arch/msg/oauth/4dZH9OrgUjCFko5Si3kgKKRxWZg



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

* Outdated reference of draft-ietf-oauth-jwsreq-16
* Section 1, first paragraph, last word: should be "the" instead of "The"
* Section 1, second paragraph, second last line: "the the" should be "the"


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

No such references.


(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 not complete yet.
There are two TODOs that depend on draft-ietf-oauth-token-exchange.


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

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

The IANA Functions Operator has completed its review of draft-ietf-oauth-resource-indicators-04. 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 two actions which we must complete.

First, in the OAuth Parameters registry located at:

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

a single, new registration will be made as follows:

Parameter name: resource
Parameter usage location: authorization request, token request
Change controller: IESG
Specification document(s): [ RFC-to-be ]

As this document requests registrations in a Specification Required (see RFC 8126) registry, the IESG-designated expert for the OAuth Parameters 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.

Second, in the OAuth Extensions Error Registry also on the OAuth Parameters registry page located at:

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

a single, new registration is to be made as follows:

Error name: invalid_target
Error usage location: implicit grant error response, token error response
Related protocol extension: resource parameter
Change controller: IESG
Specification document(s): [ RFC-to-be ]

As this also requests registrations in a Specification Required (see RFC 8126) registry, the IESG-designated expert for the OAuth Extensions Error 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.

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-05):

From: The IESG
To: IETF-Announce
CC: rdd@cert.org, Rifaat Shekh-Yusef , rifaat.ietf@gmail.com, oauth@ietf.org, draft-ietf-oauth-resource-indicators@ietf.org, oauth-chairs@ietf.org
Reply-To: ietf@ietf.org
Sender:
Subject: Last Call:  (Resource Indicators for OAuth 2.0) to Proposed Standard


The IESG has received a request from the Web Authorization Protocol WG
(oauth) to consider the following document: - 'Resource Indicators for OAuth
2.0'
  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-05. 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


  An extension to the OAuth 2.0 Authorization Framework defining
  request parameters that enable a client to explicitly signal to an
  authorization server about the identity of the protected resource(s)
  to which it is requesting access.




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

IESG discussion can be tracked via
https://datatracker.ietf.org/doc/draft-ietf-oauth-resource-indicators/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
adds new parameter for requests sent by a Client to an Authorization Server.
The type of RFC is indicated in the title page header.

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

An extension to the OAuth 2.0 Authorization Framework defining request
parameters that enable a client to explicitly signal to an authorization server
about the identity of the protected resource(s) to which it is requesting
access.

Working Group Summary:

The document adds new parameter for requests sent by a Client to an
Authorization Server.
The document received many reviews and feedbacks from multiple WG members on the
mailing list and during the WG meetings.
The document was updated to reflect a late review to make sure that the document
makes it clear that the parameter might carry a location or an abstract identifier.


Document Quality:

The document has been implemented by the following:

* Ping has an implementation but with a different parameter name ("aud"):
https://documentation.pingidentity.com/pingfederate/pf92/index.shtml#adminGuide/tokenEndpoint.html

* Microsoft
https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-protocols-oauth-code

* Auth0 has an implementation but with a different parameter name ("audience"):
https://auth0.com/docs/api/authentication#authorize-application

* Node.JS Open Source oidc-provider implements the draft in full
https://github.com/panva/node-oidc-provider/blob/master/docs/configuration.md#featuresresourceindicators

* ARM has an implementation as pard of the Pelion Secure Device Access (SDA) product:
https://cloud.mbed.com/docs/v1.2/device-management/secure-device-access.html



Personnel:

The document shepherd is Rifaat Shekh-Yusef.
The responsible Area Director is Eric Rescorla.


(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.
Brian: https://mailarchive.ietf.org/arch/msg/oauth/W7JJTWO-CZ0PlJmA5YKsTpvDrbs
John: https://mailarchive.ietf.org/arch/msg/oauth/hYALU3rRmTKvZvsUIN3j8BeHT_M
Hannes: https://mailarchive.ietf.org/arch/msg/oauth/4dZH9OrgUjCFko5Si3kgKKRxWZg



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

* Outdated reference of draft-ietf-oauth-jwsreq-16
* Section 1, first paragraph, last word: should be "the" instead of "The"
* Section 1, second paragraph, second last line: "the the" should be "the"


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

No such references.


(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 not complete yet.
There are two TODOs that depend on draft-ietf-oauth-token-exchange.


(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
adds new parameter for requests sent by a Client to an Authorization Server.
The type of RFC is indicated in the title page header.

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

An extension to the OAuth 2.0 Authorization Framework defining request
parameters that enable a client to explicitly signal to an authorization server
about the identity of the protected resource(s) to which it is requesting
access.

Working Group Summary:

The document adds new parameter for requests sent by a Client to an
Authorization Server.
The document received many reviews and feedbacks from multiple WG members on the
mailing list and during the WG meetings.
The document was updated to reflect a late review to make sure that the document
makes it clear that the parameter might carry a location or an abstract identifier.


Document Quality:

The document has been implemented by the following:

* Ping has an implementation but with a different parameter name ("aud"):
https://documentation.pingidentity.com/pingfederate/pf92/index.shtml#adminGuide/tokenEndpoint.html

* Microsoft
https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-protocols-oauth-code

* Auth0 has an implementation but with a different parameter name ("audience"):
https://auth0.com/docs/api/authentication#authorize-application

* Node.JS Open Source oidc-provider implements the draft in full
https://github.com/panva/node-oidc-provider/blob/master/docs/configuration.md#featuresresourceindicators

* ARM has an implementation as pard of the Pelion Secure Device Access (SDA) product:
https://cloud.mbed.com/docs/v1.2/device-management/secure-device-access.html



Personnel:

The document shepherd is Rifaat Shekh-Yusef.
The responsible Area Director is Eric Rescorla.


(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.
Brian: https://mailarchive.ietf.org/arch/msg/oauth/W7JJTWO-CZ0PlJmA5YKsTpvDrbs
John: https://mailarchive.ietf.org/arch/msg/oauth/hYALU3rRmTKvZvsUIN3j8BeHT_M
Hannes: https://mailarchive.ietf.org/arch/msg/oauth/4dZH9OrgUjCFko5Si3kgKKRxWZg



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

* Outdated reference of draft-ietf-oauth-jwsreq-16
* Section 1, first paragraph, last word: should be "the" instead of "The"
* Section 1, second paragraph, second last line: "the the" should be "the"


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

No such references.


(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 not complete yet.
There are two TODOs that depend on draft-ietf-oauth-token-exchange.


(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
adds new parameter for requests sent by a Client to an Authorization Server.
The type of RFC is indicated in the title page header.

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

An extension to the OAuth 2.0 Authorization Framework defining request
parameters that enable a client to explicitly signal to an authorization server
about the location of the protected resource(s) to which it is requesting
access.

Working Group Summary:

The document adds new parameter for requests sent by a Client to an
Authorization Server.
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:

* Ping has an implementation but with a different parameter name ("aud"):
https://documentation.pingidentity.com/pingfederate/pf92/index.shtml#adminGuide/tokenEndpoint.html

* Microsoft
https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-protocols-oauth-code

* Auth0 has an implementation but with a different parameter name ("audience"):
https://auth0.com/docs/api/authentication#authorize-application

* Node.JS Open Source oidc-provider implements the draft in full
https://github.com/panva/node-oidc-provider/blob/master/docs/configuration.md#featuresresourceindicators

* ARM has an implementation as pard of the Pelion Secure Device Access (SDA) product:
https://cloud.mbed.com/docs/v1.2/device-management/secure-device-access.html



Personnel:

The document shepherd is Rifaat Shekh-Yusef.
The responsible Area Director is Eric Rescorla.


(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.
Brian: https://www.ietf.org/mail-archive/web/oauth/current/msg18805.html
John: https://www.ietf.org/mail-archive/web/oauth/current/msg18803.html
Hannes: https://www.ietf.org/mail-archive/web/oauth/current/msg18804.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 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.

* Copyright should be changed to this year.
* Outdated reference of draft-ietf-oauth-jwsreq-16
* Section 1, first paragraph, last word: should be "the" instead of "The"
* Section 1, second paragraph, second last line: "the the" should be "the"
* Section 4.1, Parameter usage location: address the TODO
* Section 4.2, Error usage location: address the TODO


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

No such references.


(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 not complete yet.
There are two TODOs that depend on draft-ietf-oauth-token-exchange.


(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
adds new parameter for requests sent by a Client to an Authorization Server.
The type of RFC is indicated in the title page header.

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

An extension to the OAuth 2.0 Authorization Framework defining request
parameters that enable a client to explicitly signal to an authorization server
about the location of the protected resource(s) to which it is requesting
access.

Working Group Summary:

The document adds new parameter for requests sent by a Client to an
Authorization Server.
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:

* Ping has an implementation but with a different parameter name ("aud"):
https://documentation.pingidentity.com/pingfederate/pf92/index.shtml#adminGuide/tokenEndpoint.html

* Microsoft
https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-protocols-oauth-code

* Auth0 has an implementation but with a different parameter name ("audience"):
https://github.com/panva/node-oidc-provider


* ARM has an implementation as pard of the Pelion Secure Device Access (SDA) product:
https://cloud.mbed.com/docs/v1.2/device-management/secure-device-access.html



Personnel:

The document shepherd is Rifaat Shekh-Yusef.
The responsible Area Director is Eric Rescorla.


(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.
Brian: https://www.ietf.org/mail-archive/web/oauth/current/msg18805.html
John: https://www.ietf.org/mail-archive/web/oauth/current/msg18803.html
Hannes: https://www.ietf.org/mail-archive/web/oauth/current/msg18804.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 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.

* Copyright should be changed to this year.
* Outdated reference of draft-ietf-oauth-jwsreq-16
* Section 1, first paragraph, last word: should be "the" instead of "The"
* Section 1, second paragraph, second last line: "the the" should be "the"
* Section 4.1, Parameter usage location: address the TODO
* Section 4.2, Error usage location: address the TODO


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

No such references.


(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 not complete yet.
There are two TODOs that depend on draft-ietf-oauth-token-exchange.


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