Subject: [OAUTH-WG] Feedback on normative issues in OAuth2 draft 11 from implementers of draft 10

From: Mike Jones <[email-masked]>
Date: Mon, 10 Jan 2011 16:47:50 +0000

Our implementers of draft 10 have raised the following issues with draft 11.  Please address them before publishing a draft 12.   I'll send editorial feedback in a separate message.

6.2 etc.:  Specification MUST permit parameter extensibility

There will be uses of OAuth2 where additional parameters need to be passed in the messages.  While some messages implicitly permit extensibility through language like 4.1's "the client constructs the request URI by adding the following parameters to the end-user authorization endpoint URI query component" others do not.  In particular, the BNF for the WWW-Authenticate Response in 6.2 appears to permit only a fixed set of parameters (scope, error, error-desc, error-uri, token).  This must be addressed.

Please add language to 6.2 that explicitly allows for other arguments to be added to the response and mandates that they be ignored if not recognized.  Also, define an IANA registration process for registering new parameter values for all messages.

In particular, even if the following request to add an optional "resource" parameter is not adopted, it must be possible to add one to all relevant messages so that a "resource" parameter can be added as a legal extension.

4.1, 4.2, 4.3.1, 5, 5.2, 5.3.1, 6.2, 6.2.1:  "Scope" parameter should be paired with complimentary "resource" parameter

It is desirable to be able to have a single service protecting multiple resources.  To achieve that, there needs to be a parameter specifying what the desired resource being accessed is.  This is different than scope.  At least as we're using it, "scope" would be a space-separated list of kinds of access requested.  For instance you might be requesting read access to someone's calendar free/busy times and the right to post new calendar requests.  Those would be scope statements and would use URIs specifying those rights.

Therefore, we request that an additional optional "resource" parameter be added to the specification in the same places that "scope" appears.  "Resource" would be the URI (probably a URL) of the resource being protected by the service.

5.1.3 etc.:  The name client_credentials is confusing

The name client_credentials does not refer to the same concept as the uses of the term "Client Credentials" in 1.4.3, 3, 5.1.3, and other locations in the document.  It would be far better to rename this parameter "none" or "implicit", to indicate that no explicit credentials are being passed in the protocol.  It might also clarify this concept if you added an example.

6.2:  Token_type needed for WWW-Authenticate Response

An optional token_type parameter should be added to the WWW-Authenticate Response.  This, paired with adding this parameter to the authenticated token requests in the bearer token spec, will complete the ability to communicate token type information for all legs of the protocol.

TBDs

And of course, we're very interested in seeing the write-ups for adding token types in 6.1 and new credential types in 7.1

                                                                Thanks,
                                                                -- Mike

---

From: "Richer, Justin P." <[email-masked]>
Date: Mon, 10 Jan 2011 11:49:45 -0500

> The name client_credentials does not refer to the same concept as the uses of the term “Client Credentials” in 1.4.3, 3, 5.1.3, and other locations in the document.  It would be far better to rename this parameter “none” or “implicit”, to indicate that no explicit credentials are being passed in the protocol.  It might also clarify this concept if you added an example.

There are explicit credentials here -- the client id and secret. Naming it "none" or "implicit" would be even more confusing, IMHO, since that implies that you're just handing out tokens to whoever asks. I agree that it needs to be called out more in the document, though, and an example would go a long way to this. 

 -- Justin

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Mon, 10 Jan 2011 10:58:41 -0700

> -----Original Message-----
> From: Mike Jones [mailto:[email-masked]]
> Sent: Monday, January 10, 2011 8:48 AM
> To: Eran Hammer-Lahav
> Cc: [email-masked]
> Subject: Feedback on normative issues in OAuth2 draft 11 from
> implementers of draft 10
> 
> Our implementers of draft 10 have raised the following issues with draft
> 11.  Please address them before publishing a draft 12.   I'll send editorial
> feedback in a separate message.
> 
> There will be uses of OAuth2 where additional parameters need to be
> passed in the messages.  While some messages implicitly permit extensibility
> through language like 4.1's "the client constructs the request URI by adding
> the following parameters to the end-user authorization endpoint URI query
> component" others do not.  In particular, the BNF for the WWW-
> Authenticate Response in 6.2 appears to permit only a fixed set of
> parameters (scope, error, error-desc, error-uri, token).  This must be
> addressed.

'token' is an ABNF term, not access-token. It means you can add anything you want (at least according to the ABNF).

> Please add language to 6.2 that explicitly allows for other arguments to be
> added to the response and mandates that they be ignored if not
> recognized.  Also, define an IANA registration process for registering new
> parameter values for all messages.

I'm confused. You mean section 7.3?

> In particular, even if the following request to add an optional "resource"
> parameter is not adopted, it must be possible to add one to all relevant
> messages so that a "resource" parameter can be added as a legal extension.

What in section 7 is missing, preventing you from doing this?

> It is desirable to be able to have a single service protecting multiple
> resources.  To achieve that, there needs to be a parameter specifying what
> the desired resource being accessed is.  This is different than scope.  At least
> as we're using it, "scope" would be a space-separated list of kinds of access
> requested.  For instance you might be requesting read access to someone's
> calendar free/busy times and the right to post new calendar requests.  Those
> would be scope statements and would use URIs specifying those rights.
> 
> Therefore, we request that an additional optional "resource" parameter be
> added to the specification in the same places that "scope"
> appears.  "Resource" would be the URI (probably a URL) of the resource
> being protected by the service.

Already rejected by the WG due to lack of consensus. I suggest you draft an extension and see where it goes.
 
> The name client_credentials does not refer to the same concept as the uses
> of the term "Client Credentials" in 1.4.3, 3, 5.1.3, and other locations in the
> document.  It would be far better to rename this parameter "none" or
> "implicit", to indicate that no explicit credentials are being passed in the
> protocol.  It might also clarify this concept if you added an example.

Both none and implicit were rejected. The current name has consensus.

> An optional token_type parameter should be added to the WWW-
> Authenticate Response.  This, paired with adding this parameter to the
> authenticated token requests in the bearer token spec, will complete the
> ability to communicate token type information for all legs of the protocol.

We don't have consensus to add support for requesting a specific token type (by the client), or to advertise discovery information (which token types are supported, and available for the client to request). This is not trivial. I suggest publishing an extension defining this and see where it goes.

As a general note, both the 'resource' and 'token_type' requests lack sufficient detail to be added to the specification at this late stage. We have a very stable draft that is almost ready for last-call. Adding significant new functionality should only be permitted if the protocol will not be useable otherwise.  This is, of course, just a general principal, but if something can be defined as an extension, it should to avoid delaying the framework spec.

EHL