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

From: Eran Hammer-Lahav <[email-masked]>
Date: Fri, 30 Apr 2010 08:43:55 -0700

It's time to decide how we want to treat access token scope in the specification. Note that this discussion is limited to *requesting* an access token with a specific scope and does not include how to decide when a token should be reused against an unfamiliar server (i.e. resource server advertising which scope it requires).

Below is the list of options with enough group interest. I didn't my best to represent each option without bias but please feel free to add more details with your votes. If you feel strongly about other alternatives, please list them in your reply.

Please reply by 5/5.

EHL

---

1. Parameter Name Only 

Define a token request parameter 'scope' leaving the value structure undefined. This will allow libraries to define a built-in parameter to pass scope up and down the stack. Each provider will need to document their use of the parameter, including delimiter and encoding.

Pros:

- This does not require specifying a format that may conflict with existing or desired vendor-specific needs.
- There isn't enough deployment experience to go further than that.
- It makes using a library easier for client developers

Cons:

- Adding an undefined parameter can hurt interoperability in the long run because as soon as it is deployed it will become impossible to standardize this value in the future.
- Libraries are likely to implement the most popular form of scope encoding which will conflict with other vendors.
- Specifying a generally useful format isn't that hard, but is very useful.
- Libraries will need to pass arbitrary parameters anyway to accommodate other vendor-specific extensions.

2. No Scope Parameter

The protocol will remain mute on the subject, allowing vendors to introduce their own scope parameter either as an extension or as an opaque part of the authorization and token endpoints (as proposed by James Manger).

Pros:

- Simplicity - the protocol doesn't define (partially or fully) parameters that are not required in every implementation.
- Flexibility - since there is no consensus on the subject, this allows vendors to define their own parameters with more suitable names (e.g. 'resources', 'permission', 'duration', etc.).

Cons:

- Every implementation is likely to add such a parameter anyway.
- The pattern described by James isn't obvious and developers are likely to reinvent a scope parameter instead.
- Goes against common expectation of scope support in the core protocol.

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.

---

From: Torsten Lodderstedt <[email-masked]>
Date: Fri, 30 Apr 2010 20:43:22 +0200

+1 on option 3.

> - Defining a format without a discovery method for the values needs doesn't offer much more than the other options.

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.

> - Adds complexity for little value.

I think it adds a lot of value. It introduces the concept of client 
permissions to OAuth, which allows to restrict client access to services 
at a fine-grained level. At Deutsche Telekom, we have some use cases 
requiring such a feature and would be happy to see it supported by the 
standard.

regards,
Torsten.

>
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth
>

---

From: Allen Tom <[email-masked]>
Date: Fri, 30 Apr 2010 12:08:48 -0700

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:

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

---

From: Joseph Smarr <[email-masked]>
Date: Fri, 30 Apr 2010 13:52:16 -0700

I also vote for #3. I think our field experience has shown that a) lack of a
standard place to stick scope info in access token requests leads to
per-provider inconsistencies that further complicate libraries, b) lots of
providers do want to offer scoped access tokens (and show the list of scopes
being requested on consent UI), and c) we're likely to want to have some
cross-vendor standard scopes (e.g. "access profile data", PoCo, "post
activities", etc.) so it's natural to express those as URIs, thus favoring
space-delimited scope values.

Thanks,js

On Fri, Apr 30, 2010 at 12:08 PM, Allen Tom <[email-masked]> wrote:

> > - Defining a format without a discovery method for the values needs
> doesn't
> > offer much more than the other options.

---

From: Pelle Braendgaard <[email-masked]>
Date: Fri, 30 Apr 2010 17:13:20 -0400

+1 for #3

Since google implemented I always thought it an elegant simple way of
requesting access.

-- 
http://agree2.com - Reach Agreement!
http://extraeagle.com - Solutions for the electronic Extra Legal world
http://stakeventures.com - Bootstrapping blog

---

From: Justin Smith <[email-masked]>
Date: Fri, 30 Apr 2010 22:01:35 +0000

Piling on: +1 for #3.

--justin

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Pelle Braendgaard
Sent: Friday, April 30, 2010 2:13 PM
To: OAuth WG ([email-masked])
Subject: Re: [OAUTH-WG] Scope - Coming to a Consensus

+1 for #3

---

From: Marius Scurtescu <[email-masked]>
Date: Fri, 30 Apr 2010 18:07:04 -0700

On Fri, Apr 30, 2010 at 11:43 AM, Torsten Lodderstedt
<[email-masked]> wrote:
> 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)?
If not, then discovery of scopes is almost a must in this case. The
client implementor cannot know the actual scope because implementation
is done against a generic API.

I did not see the value of scope discovery until I realized the above use case.

Marius

---

From: Marius Scurtescu <[email-masked]>
Date: Fri, 30 Apr 2010 18:11:34 -0700

+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

---

From: Torsten Lodderstedt <[email-masked]>
Date: Sat, 01 May 2010 08:00:41 +0200

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

regards,
Torsten.