Subject: Re: [OAUTH-WG] Scope - Coming to a Consensus

From: Eve Maler <[email-masked]>
Date: Sat, 1 May 2010 05:36:26 -0700

On 30 Apr 2010, at 11:00 PM, Torsten Lodderstedt wrote:

> Am 01.05.2010 03:07, schrieb Marius Scurtescu:
>> On Fri, Apr 30, 2010 at 11:43 AM, Torsten Lodderstedt
>> <[email-masked]>  wrote:
>>   
>>> In my opinion, automatic discovery on scope values is as valuable or not
>>> valuable as automatic discovery for a service API. I would like to echo one
>>> of my postings:
>>> 
>>> A scope defines the set of permissions a client asks for and that becomes
>>> associated with tokens. I don't see the need (and a way) for automatic scope
>>> discovery. In my opinion, scopes are part of the API documentation of a
>>> particular resource server. So if someone implements a client, it needs to
>>> consider the different scopes this client needs the end users authorization
>>> for. If the resource server implements a OAuth2-based standard API (e.g. for
>>> contact management or e-Mail), a client might be interoperable (in terms of
>>> scopes) among the resource servers implementing this standard.
>>>     
>> Not sure I understand, are you saying that for a standard API, like
>> IMAP for example, there should be a standard scope (or set of scopes)?
>>   
> 
> Yes, that's what I said.
> 
> Scopes (~permissions) should be defined allong with the corresponding API. So developers should know upfront
> which scope is required  to perform a particular action. For example, "uploading documents requires scope 'upload'".
> The same holds for IMAP. Depending on the IMAP feature set you want to use there could be plenty of scopes,
> ranging from "read users INBOX" to sharing scenarios, where users have access to other users IMAP folders.

This makes a ton of sense.  It's one of the reasons that, in UMA, we tried to specify a generic way of expressing scope that naturally and closely matches a resource-oriented (RESTful) API: resource + HTTP method is a reliable shorthand for an access feature.  For read and write and even delete permissions on (say) identity data accessed by URL, it's pretty much all the expressiveness you need, and ideally the same documentation easily covers both features and scopes.  For any API that's more "compressed" (e.g. one complex endpoint for many operations), it doesn't really help.

	Eve

Eve Maler
[email-masked]
http://www.xmlgrrl.com/blog

---

From: Luke Shepard <[email-masked]>
Date: Sat, 1 May 2010 15:48:44 -0700

I agree with approach #3.

As for the delimiter, I'm fine if the spec wants to do space-delimited. 

Just FYI Facebook will also continue to support and document commas in addition to whatever the spec says, because spaces are typically URL-encoded while commas are considered reserved characters and so not encoded. It's easier to write "read,write" than "read%20write".

On Apr 30, 2010, at 6:11 PM, Marius Scurtescu wrote:

> +1 for #3.
> 
> If the delimiter becomes an issue then:
> - for application/x-www-form-urlencoded and query parameters we can
> allow multiple values for this parameter
> - for json this parameter can be defined as an array
> 
> Marius
> 
> 
> 
> On Fri, Apr 30, 2010 at 12:08 PM, Allen Tom <[email-masked]> wrote:
>> I vote for #3
>> 
>> There are already plenty of implementations that use a scope parameter:
>> 
>> Facebook:
>> http://developers.facebook.com/docs/authentication/
>> 
>> Google:
>> http://code.google.com/apis/accounts/docs/OAuth_ref.html#RequestToken
>> 
>> Flickr: (called "perm")
>> http://www.flickr.com/services/api/auth.spec.html
>> 
>> Yahoo currently requires developers to tell us the scopes that they need
>> when registering for a consumer key. We've received plenty of feedback that
>> developers would rather specify the scope(s) at authorization time, so we
>> would support a multi-valued scope parameter. Space is a reasonable
>> delimiter.
>> 
>> Allen
>> 
>> 
>> 
>> On 4/30/10 8:43 AM, "Eran Hammer-Lahav" <[email-masked]> wrote:
>> 
>>> 
>>> 3. Space-Delimited Scope Parameter Value
>>> 
>>> Define a 'scope' parameter with value of space-delimited strings (which can
>>> include any character that is not a space - the entire parameter value is
>>> encoded per the transport rules regardless). Space allows using URIs or simple
>>> strings as values.
>>> 
>>> Pros:
>>> 
>>> - A separator-delimited list of values is the common format for scope
>>> parameters in existing implementations and represents actual deployment
>>> experience.
>>> - Most vendors define a set of opaque strings used for requesting scope. This
>>> enables libraries to concatenate these in a standard way.
>>> - Enables simple extensions in the future for discovering which scope is
>>> required by each resource.
>>> 
>>> Cons:
>>> 
>>> - Defining a format without a discovery method for the values needs doesn't
>>> offer much more than the other options.
>>> - Doesn't go far enough to actually achieve interoperability.
>>> - Adds complexity for little value.
>>> 
>>> 
>>> 
>>> _______________________________________________
>>> OAuth mailing list
>>> [email-masked]
>>> https://www.ietf.org/mailman/listinfo/oauth
>> 
>> _______________________________________________
>> OAuth mailing list
>> [email-masked]
>> https://www.ietf.org/mailman/listinfo/oauth
>> 
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth

---

From: Dick Hardt <[email-masked]>
Date: Sat, 1 May 2010 18:06:04 -0700

> Just FYI Facebook will also continue to support and document commas in addition to whatever the spec says, because spaces are typically URL-encoded while commas are considered reserved characters a…

Just in case it was not evident: a comma is a valid URL character, it would be legal for it to be contained in a URL scope, leading a library parsing scopes to inadvertently split up a single scope into one or more. Since the proposal says a scope can be a URI/URL, a space is a better delimiter.

-- Dick

---

From: "Manger, James H" <[email-masked]>
Date: Mon, 3 May 2010 23:23:50 +1000

A comma is a better separator here.
Allow URIs as scopes -- as long as the chosen URIs don't have commas. This isn't a big restriction on services.

[If a service provider really needs to include arbitrary URIs in an authorization URI they can still do so by defining another parameter, say "urls". We are barely defining any semantics for "scope" -- at least none that libraries can use -- so not much is lost in using a different parameter name.]

A space-separated list (encoded as per the transport) sounds nice at a logical level, but is just a bit unnecessarily awkward. The only place scope values appear is in an authz URI so the only encoding is URI-encoding. Are the spaces escaped as "%20" or "+"? Even if we try to pick one answer I suspect both will occur (it depends on which part of the software builds the authz URI -- ie prepare for interop glitches).
Any spaces in a URI used as a scope value needs to be %-escaped twice. It seems unnecessary to even allow this.

Facebook define values like scope=read,write.
However, if you build an authz URI from an HTML form with an input value of "read,write" you get scope=read%2Cwrite -- as comma is not an unreserved character.
  <input name="scope" value="read,write"/>
I suspect authz services might need to accept "read%2Cwrite" as equivalent to "read,write" [I wonder if Facebook does?]. Which gets produced will depend on how the client app (or client OAuth library) is designed, and will vary between apps. The spec probably need to say services MUST accept "," and "%2C" as separators -- and consequently individual scope values MUST NOT contain "," or "%2C".

I think the best definition (least potential for any developer or interop grief) would restrict individual scope values to chars that can be placed in a query parameter value without any special treatment.
Allow any chars allowed in URIs, except "&", "#", "%", or ",".
This doesn't allow arbitrary URIs, but I suspect it allows any URIs being used as scopes at present.

--
James Manger

---

From: "Manger, James H" <[email-masked]>
Date: Mon, 3 May 2010 23:57:05 +1000

Torsten,

> Scopes (~permissions) should be defined allong with the corresponding API.

But they aren't.
Lots of "APIs" -- particularly the most important/standard ones, like AtomPub, HTML itself, IMAP (?)... are already defined, or are defined separately from any permissions that one service chooses for their implementation.
Permissions can be coarse grained (eg have access / don't have access), or fine grained (eg can read green items on Fridays), or anywhere in between. If every client app always needs service-specific knowledge about how permission are arranged I don't think we can get much interop.

> Depending on the IMAP feature set you want to use there could be plenty of scopes,
ranging from "read users INBOX" to sharing scenarios, where users have 
access to other users IMAP folders.

[I am not sure that IMAP is a great example as I assume it isn't an HTTP protocol, but ignoring that]
I hope that if an IMAP service says "I support OAuth2", and a client app says "I understand IMAP and OAuth2" then they can interoperate with minimal config. The app may need an app-id/secret, it may need an URI to start at (perhaps even a complicated one), but I hope it doesn't also need a table of service-specific permission labels against every possible IMAP operation.

--
James Manger

---

From: Allen Tom <[email-masked]>
Date: Mon, 03 May 2010 10:02:35 -0700

On a related note, there's a group working on an OAuth2 binding for IMAP
(and other SASL based protocols) here:

http://tech.groups.yahoo.com/group/sasl_oauth/

Currently, we're trying to figure out how Mail clients are supposed to
discover what scopes they need. Also, most Mail clients would probably want
more than just "IMAP" scope, they probably also want to access other related
services, including SMTP, CalDAV, LDAP, Portable Contacts, etc.

Allen

On 5/3/10 6:57 AM, "Manger, James H" <[email-masked]>
wrote:

> I hope that if an IMAP service says "I support OAuth2", and a client app says
> "I understand IMAP and OAuth2" then they can interoperate with minimal config.
> The app may need an app-id/secret, it may need an URI to start at (perhaps
> even a complicated one), but I hope it doesn't also need a table of
> service-specific permission labels against every possible IMAP operation.
>

---

From: Evan Gilbert <[email-masked]>
Date: Mon, 3 May 2010 10:15:56 -0700

+1 on option 3.

Commas seem slightly cleaner, but can go either way.

We should also consider naming this parameter "scopes" if we go with option
3

Evan

On Mon, May 3, 2010 at 6:23 AM, Manger, James H <
[email-masked]> wrote:

> [If a service provider really needs to include arbitrary URIs in an
> authorization URI they can still do so by defining another parameter, say
> "urls". We are barely defining any semantics for "scope" -- at least none
> that libraries can use -- so not much is lost in using a different parameter
> name.]
>
>
> A space-separated list (encoded as per the transport) sounds nice at a
> logical level, but is just a bit unnecessarily awkward. The only place scope
> values appear is in an authz URI so the only encoding is URI-encoding. Are
> the spaces escaped as "%20" or "+"? Even if we try to pick one answer I
> suspect both will occur (it depends on which part of the software builds the
> authz URI -- ie prepare for interop glitches).
> However, if you build an authz URI from an HTML form with an input value of
> "read,write" you get scope=read%2Cwrite -- as comma is not an unreserved
> character.
> I suspect authz services might need to accept "read%2Cwrite" as equivalent
> to "read,write" [I wonder if Facebook does?]. Which gets produced will
> depend on how the client app (or client OAuth library) is designed, and will
> vary between apps. The spec probably need to say services MUST accept ","
> and "%2C" as separators -- and consequently individual scope values MUST NOT
> contain "," or "%2C".
>
>
> I think the best definition (least potential for any developer or interop
> grief) would restrict individual scope values to chars that can be placed in
> a query parameter value without any special treatment.

---

From: Mark Mcgloin <[email-masked]>
Date: Tue, 4 May 2010 10:08:07 +0100

+1  to option 3

I think the suggestion below from Torsten makes great sense, especially in
relation to standardized apis such as mail

Mark

On 01 May 2010, at 13:36 PM, Eve Maier wrote:

> which scope is required  to perform a particular action. For example,
"uploading documents requires scope 'upload'".

This makes a ton of sense.  It's one of the reasons that, in UMA, we tried
to specify a generic way of expressing scope that naturally and closely
matches a resource-oriented (RESTful) API: resource + HTTP method is a
reliable shorthand for an access feature.  For read and write and even
delete permissions on (say) identity data accessed by URL, it's pretty much
all the expressiveness you need, and ideally the same documentation easily
covers both features and scopes.  For any API that's more
"compressed" (e.g. one complex endpoint for many operations), it doesn't
really help.

             Eve

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Sun, 9 May 2010 10:44:44 -0700

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On Behalf
> Of Manger, James H
> Sent: Monday, May 03, 2010 6:24 AM
> To: OAuth WG ([email-masked])
> Subject: Re: [OAUTH-WG] Scope - Coming to a Consensus
> 

It's an odd restriction that violated the server's name space.

> [If a service provider really needs to include arbitrary URIs in an authorization
> URI they can still do so by defining another parameter, say "urls". We are
> barely defining any semantics for "scope" -- at least none that libraries can
> use -- so not much is lost in using a different parameter name.]

All this just to use a comma separator?
 
> A space-separated list (encoded as per the transport) sounds nice at a logical
> level, but is just a bit unnecessarily awkward. The only place scope values
> appear is in an authz URI so the only encoding is URI-encoding. Are the
> spaces escaped as "%20" or "+"? Even if we try to pick one answer I suspect
> both will occur (it depends on which part of the software builds the authz URI
> -- ie prepare for interop glitches).

They would have to be encoded twice either way. Form-encoded query (according to the HTML 4 specification) allows only '.', '_', '-', and '~' to remain unencoded. Everything else must be encoded including a comma. The fact that you can send a comma in the query doesn't make it a valid way to transmit form-encoded parameters.

EHL