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

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.

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.

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 <https://example.com/apps/?app=app2>. 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."

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.

I agree with Alexey and Mirja.

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

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?

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.