Subject: [OAUTH-WG] 'Scope' parameter proposal

From: Eran Hammer-Lahav <[email-masked]>
Date: Mon, 19 Apr 2010 09:25:16 -0700

Proposal:

'scope' is defined as a comma-separated list of resource URIs or resource
groups (e.g. contacts, photos). The server can provide a list of values for
the client to use in its documentation, or the client can use the URIs or
scope identifier of the protected resources it is trying to access (before
or after getting a 401 response).

For example:

1. Client requests resource

    GET /resource HTTP/1.1
    Host: example.com

2. Server requires authentication

    HTTP/1.1 401 Unauthorized
    WWW-Authenticate: Token realm='Example', scope='x2'

3. Client requests an access token by including scope=x2 in the request

Alternatively, the client can ask for an access token with
scope=http://example.com/resource.

If the client needs access to two resource with different scopes, it
requests an access token for scope=x2,x1.

That's it!

It allows the client to figure out what value to put in the scope parameter
and how to encode multiple scopes without any server-specific documentation.
Servers that wish to rely exclusively on paperwork can just omit the scope
parameter from the WWW-Authenticate header.

We can pick a different separator (space, semicolon, etc.) or different
parameter name (resource(s)).

EHL

---

From: Luke Shepard <[email-masked]>
Date: Mon, 19 Apr 2010 10:21:21 -0700

This seems pretty elegant to me. I like that in the general case, the protected resource can give an error saying the scope required.

As a specific example of how Facebook could use this, we have an extended permission for an app to publish to a user's stream. If an app tries to publish to the stream today, and they don't have the permission, we give an error that says "You need the publish_stream permission." With this extension, we could also add a header like:

WWW-Authenticate: Token realm="http://www.facebook.com", scope="publish_stream"

Then client libraries could craft an OAuth authorize URL for that scope, without having to refer to documentation.

One issue is how this would work with more complicated scenarios. There are resources that require multiple scopes, or even one of a few possible scopes (i.e., either "publish_stream" or "add_photo" to post a photo story). What are the semantics of the response header listing multiple scopes - are they all required, or just some?
 
-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Eran Hammer-Lahav
Sent: Monday, April 19, 2010 9:25 AM
To: OAuth WG
Subject: [OAUTH-WG] 'Scope' parameter proposal

Proposal:

For example:

    GET /resource HTTP/1.1
    Host: example.com

That's it!

EHL

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

---

From: Marius Scurtescu <[email-masked]>
Date: Mon, 19 Apr 2010 11:03:32 -0700

On Mon, Apr 19, 2010 at 9:25 AM, Eran Hammer-Lahav <[email-masked]> wrote:
> groups (e.g. contacts, photos).

How will commas in URIs be escaped? We just forbid them?

If the scope elements are URIs then a space separated list is much
safer, URIs cannot contain spaces.

But, I still don't see the point on trying to define the scope structure.

Marius

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Mon, 19 Apr 2010 11:14:33 -0700

> From: Marius Scurtescu [mailto:[email-masked]]
> Sent: Monday, April 19, 2010 11:04 AM
> To: Eran Hammer-Lahav
> Cc: OAuth WG
> Subject: Re: [OAUTH-WG] 'Scope' parameter proposal
> 
> > 'scope' is defined as a comma-separated list of resource URIs or
> > resource groups (e.g. contacts, photos).
> 
> If the scope elements are URIs then a space separated list is much safer, URIs
> cannot contain spaces.

Yep. I noted that in my proposal.

> But, I still don't see the point on trying to define the scope structure.

The same point in defining any other parameter - interop. I still haven't heard an argument for not defining it. By definition everything we add to the spec is meant to increase interop and should be well specified. If you want to leave someone under specified, the burden is on your to argue why, not on me to argue for it.

EHL

---

From: Torsten Lodderstedt <[email-masked]>
Date: Mon, 19 Apr 2010 22:34:50 +0200

+1

---

From: Marius Scurtescu <[email-masked]>
Date: Mon, 19 Apr 2010 13:49:43 -0700

On Mon, Apr 19, 2010 at 11:14 AM, Eran Hammer-Lahav <[email-masked]> wrote:
> The same point in defining any other parameter - interop. I still haven't heard an argument for not defining it. By definition everything we add to the spec is meant to increase interop and should be well specified.

How does defining the scope structure help interop?

There was a good argument why not define it. Getting everyone to agree
on one definition can be hard, and you cannot be sure everyone was
consulted. There are lots of service providers out there that use
scopes today. Are we sure that a space separated list of URIs will
work for all of them?

> If you want to leave someone under specified, the burden is on your to argue why, not on me to argue for it.

When you wanted to leave scopes out altogether, you wanted proof they
are needed :-)

I did a proof of concept implementation, with client, server and
protected resource support libraries, and the scope structure was
never an issue. Actual client, server and resource code, does need to
deal with scopes, but this is not the generic code that would go into
a library.

I do agree that it would be nice to have a defined structure for
scopes, I just don't think it is that important and that it is hard to
get right.

Marius

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Mon, 19 Apr 2010 14:20:56 -0700

> Sent: Monday, April 19, 2010 1:50 PM

> How does defining the scope structure help interop?

Clients can use scopes the same way across provides and don't need to read paperwork to figure out how to use the parameter. It allows smooth and seamless interaction with an unfamiliar server using an open API format.
 
> There was a good argument why not define it. Getting everyone to agree on
> one definition can be hard, and you cannot be sure everyone was consulted.
> There are lots of service providers out there that use scopes today. Are we
> sure that a space separated list of URIs will work for all of them?

Everything is hard to agree on - welcome to the wonderful work of standards. The signatures discussion took months for example. But you can't make this argument without even trying. Let's spend a week discussing a proposal (or others if people want to submit more) and see where we end up. As for those not participating, well, that's their problem. Seriously, if you don't bother to show up and participate you have absolutely no say. Specs are created by those who show up.

> When you wanted to leave scopes out altogether, you wanted proof they

That wasn't my position. My position was that the parameter was underspecified and as such added no value. I tried repeatedly to discuss ideas on how to define it but you and others just shot me down every time arguing it must be vendor-specific.
 
> I did a proof of concept implementation, with client, server and protected
> resource support libraries, and the scope structure was never an issue.
> Actual client, server and resource code, does need to deal with scopes, but
> this is not the generic code that would go into a library.

Did your library handle unknown parameters, passing them through the call stack?

> I do agree that it would be nice to have a defined structure for scopes, I just
> don't think it is that important and that it is hard to get right.

I disagree on both. It is important and not so hard to get right, just like any other feature we decide to include. How would you know if we don't even try?

This exact argument was made 3 years ago. Dick Hardt asked for a scope parameter. As editor I added a generic scope parameter to the spec called oauth_token_attributes. However the group consensus was that it was underspecified and lacked any implementation experience. We drop it and decided to revisit in an extension. That never happened. Instead, each vendor made up their own parameter. We are back where we started now, with the same arguments. I think 3 years is plenty experience to get this done right.

EHL

---

From: David Recordon <[email-masked]>
Date: Mon, 19 Apr 2010 14:23:10 -0700

+1 Eran's proposal as well

---

From: John Kemp <[email-masked]>
Date: Mon, 19 Apr 2010 17:58:44 -0400

> groups (e.g. contacts, photos).

So, 'scope' at the authenticating (via OAuth) server is simply a list of one or more URIs? There are no defined, interoperable, semantics that a server should use here - is that correct?

> The server can provide a list of values for

No (implied or otherwise) relationship between the realm and the scope? 

The scope doesn't have to match the base URI of the resource which the client tried and got the 401 from?

> requests an access token for scope=x2,x1.

Is the "effective" scope a URI, or a list of URIs?

> It allows the client to figure out what value to put in the scope parameter

It doesn't tell the client where to go to get a token related to that scope (nor should it). 

> parameter from the WWW-Authenticate header.

I think that there is much that is unspecified in this model and thus it doesn't provide much interoperability. If we don't tell the client what to do with the scope, and we don't specify what a server means by supplying a scope, I'm not sure what the point is to specifying this at all as clients will still need some documentation or be hard-coded (which token service do I get such a token from?) 

What am I missing here?

Cheers,

- johnk

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Mon, 19 Apr 2010 15:17:21 -0700

> From: John Kemp [mailto:[email-masked]]
> Sent: Monday, April 19, 2010 2:59 PM
> To: Eran Hammer-Lahav
> Cc: OAuth WG
> So, 'scope' at the authenticating (via OAuth) server is simply a list of one or
> more URIs? There are no defined, interoperable, semantics that a server
> should use here - is that correct?

Yes. Servers can use whatever they like. We can say the values are URIs (absolute or relative) - this allows short names but helps future interop or standard URI-based values. The client finds out what value(s) to request from documentation or a 401 challenge.

> > The server can provide a list of values for the client to use in its
> > documentation, or the client can use the URIs or scope identifier of
> > the protected resources it is trying to access (before or after
> > getting a 401 response).
> >
> > For example:
> >

No. Realm is too limited for many use cases. For example:

Resource A: scopes a and b
Resource B: scopes b and c
Resource C: scope b

If you want to access B and C you need a token scoped for b and c. No way to express this with realm.
 
> client tried and got the 401 from?

That's a security issue we need to address (when to trust the resource server and reuse an existing token). We need to figure it out either way.
 
> Is the "effective" scope a URI, or a list of URIs?

A list.

> It doesn't tell the client where to go to get a token related to that scope (nor

Yes. That's for another parameter and/or discovery flow.

> > Servers that wish to rely exclusively on paperwork can just omit the
> > scope parameter from the WWW-Authenticate header.
> 
> I think that there is much that is unspecified in this model and thus it doesn't
> provide much interoperability. If we don't tell the client what to do with the
> scope, and we don't specify what a server means by supplying a scope, I'm
> not sure what the point is to specifying this at all as clients will still need some
> documentation or be hard-coded (which token service do I get such a token
> from?)

Why?

The server tells the client what scope is needed for each resource. It can be a single scope id or multiple. The client checks to see if it has an access token issued with that scope combination. If it doesn't it goes and request an access token, and includes the required scope in the request. We can also allow the server to tell the client what scope an issued token includes in the token reply.

The client doesn't need to understand the internal structure of the scope identifiers. It just need to know what to ask for when trying to access an unfamiliar resource. No documentation is needed.

Client: I want to get an address book record with the latest email to that person.
Server: You need an access token scoped for "Contact" and "Email".
Client: Can I get an access token for scope=contact,email?
Server: Sure, here is an access token for scope=email,contact (order doesn't matter).

EHL

---

From: John Kemp <[email-masked]>
Date: Mon, 19 Apr 2010 19:01:10 -0400

On Apr 19, 2010, at 6:17 PM, Eran Hammer-Lahav wrote:

[...]

> The client doesn't need to understand the internal structure of the scope identifiers. It just need to know what to ask for when trying to access an unfamiliar resource. No documentation is needed.

Which server does the client ask to get a token with the particular scope which was asked for? How does the client determine that it's OK to ask server B for a token with scope X at server A?

> Client: Can I get an access token for scope=contact,email?

To whom does the client address the above question? How does the client know that server's URL without it either being available in documentation or hard-coded inside the client? 

I'm just questioning whether the "amount of interoperability" you get (client still needs to read some documentation in order to participate) is sufficient to make the specification of 'scope' worthwhile on its own, unless we supply it with some more shared semantics. 

- johnk

---

From: Marius Scurtescu <[email-masked]>
Date: Mon, 19 Apr 2010 16:36:49 -0700

> Did your library handle unknown parameters, passing them through the call stack?

Yes, it did.

Marius

---

From: Dick Hardt <[email-masked]>
Date: Mon, 19 Apr 2010 20:06:40 -0700

>    WWW-Authenticate: Token realm='Example', scope='x2'

Can more than one scope be returned? Is it a comma delimited list?

I wonder how much value this will provide. (I like the idea, but teasing out the implications.)

Imagine we have a resource that can have READ or  WRITE access granted.

An unauthenticated GET on the resource could return the scope URI needed for READ, an unauthenticated PUT on the resource could return the scope URI for WRITE. What if you want to both do READs and WRITEs? There may be another scope that is READ/WRITE. READ and WRITE are pretty common capabilities, but one can imagine much more complex capabilities at resources.

The exact semantics to the resource are likely going to very contextual.

Given that, returning a single scope value if that is all that makes sense to the resource will likely address many use cases.

(+1 to Eran's proposal given all the other factors)

-- Dick

---

From: "Manger, James H" <[email-masked]>
Date: Tue, 20 Apr 2010 14:05:48 +1000

>    WWW-Authenticate: Token realm='Example', scope='x2'

I assume the WWW-Authenticate response header also has an "authz-uri" parameter.

     WWW-Authenticate: Token realm='Example', scope='x2', authz-uri="https://as.example.com/"

The first time a client app gets this response all it can do is add the 'scope' to the 'authz-uri'. In which case the separate 'scope' parameter offered no advantage. The resource server could have more simply returned:

     WWW-Authenticate: Token realm='Example', authz-uri="https://as.example.com/?scope=x2"

The one situation where a 'scope' parameter can help interop (between client with no server-specific knowledge and the server) is when scopes are combined.

A client with a token for scope 'x1' that receives a 401 can request a new token that includes the extra scope 'x2' as well. Even in this situation, defining a 'scope' parameter is not necessary. The resource server knows the offered token was for scope 'x1', but scope 'x2' is required so the response can be:

     WWW-Authenticate: Token realm='Example', authz-uri="https://as.example.com/?scope=x2,x1"

The client just sees a URI and uses it to get a new token. This approach might require some resource servers to dynamically generate the 'authz-uri' value in error responses. I doubt that is too onerous.

An alternative way to support combining scopes would be to include (or reference) an existing token when requesting a new one. For instance, define an 'access_token' parameter to include when redirecting a user to the AS. This would work for updating a token for another 'scope', for a longer duration, for extra 'permissions' etc.
This is not absolutely necessary to define this extra 'access_token' parameter since the resource server could dynamically insert the current token into the returned 'authz_uri' value by itself, without requiring client code to do so.
Another difficulty is that some access_tokens should not be exposed to users. There may need to be an 'access_token_id' separate from the actual 'access_token' value.

In conclusion,
* -1 to Eran’s 'scope' proposal;
* perhaps add explicit support for updating a token (as opposed to refreshing) by referencing an existing token when getting a new one.

-- 
James Manger

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Mon, 19 Apr 2010 21:30:16 -0700

> Sent: Monday, April 19, 2010 4:37 PM
> To: Eran Hammer-Lahav
> Cc: OAuth WG
> >> protected resource support libraries, and the scope structure was never
> an issue.
> >> Actual client, server and resource code, does need to deal with
> >> scopes, but this is not the generic code that would go into a library.
> >

Did it hurt? :-)

EHL

---

From: Torsten Lodderstedt <[email-masked]>
Date: Tue, 20 Apr 2010 07:26:14 +0200

> Given that, returning a single scope value if that is all that makes sense to the resource will likely address many use cases.
I also think, the WWW-Authenticate header should only contain the scope 
required for the particular request. The get the whole picture of 
scope/request relations, the resource server could offer some kind of 
discovery.

regards,
Torsten.

---

From: Torsten Lodderstedt <[email-masked]>
Date: Tue, 20 Apr 2010 07:28:37 +0200

please, add the scope parameter to the flows and the refresh token 
request as well. This way, client can obtain refresh tokens with broad 
scope and narrow down it for particular request (least privileges principle)

regards,
Torsten.

---

From: Luke Shepard <[email-masked]>
Date: Tue, 20 Apr 2010 00:46:25 -0700

There are potentially three names for access tokens in this spec:

- token
- access_token
- oauth_token

You hit the /oauth/access_token endpoint, and get back access_token=blah. Then you take that string and pass it to the protected resource as oauth_token=blah.

Developers that have prototyped things over here have found this to be confusing. It's simpler to just take the same named param everywhere.

I vote that one of two things happen:

1/ Return oauth_token from the access token endpoint.
2/ Accept access_token on the protected resource endpoint.
3/ Return "token" (and still "refresh_token") from the access_token endpoint, and accept "token" on the protected resource.

I know there will be infinite debate about the right way to do this, but just wanted some thoughts for now. I will probably choose #2 as that seems most explicit, even though it's a few more characters.

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 20 Apr 2010 08:04:18 -0700

There is an explanation (I'm not defending it, just explaining).

In the flow endpoint I chose 'access_token' over token because of the refresh token. It seems better to talk about two different kinds of tokens than to have one generic 'token' and one with special meaning 'refresh_token'.

The protected resource endpoint is the only place I agree requires a prefix because it always intrudes on another namespace or platform and the likelihood of a conflict is high. I used 'oauth_token' instead of 'oauth_access_token' for brevity thinking that it should be trivial to figure out what to put there (the only other option is a refresh token which isn't likely to be confused here).

The header uses 'token' because it is a generic authentication scheme which doesn't mandate you use the OAuth flows to get a token. This is the only place I feel strongly about not changing it.

Feel free to propose new names.

EHL

> From: [email-masked] [mailto:[email-masked]] On Behalf
> Of Luke Shepard
> Sent: Tuesday, April 20, 2010 12:46 AM
> To: [email-masked]
> Subject: [OAUTH-WG] Consistency in access token parameter
> 
> You hit the /oauth/access_token endpoint, and get back access_token=blah.
> Then you take that string and pass it to the protected resource as
> oauth_token=blah.
> 
> Developers that have prototyped things over here have found this to be
> confusing. It's simpler to just take the same named param everywhere.
> 
> 3/ Return "token" (and still "refresh_token") from the access_token
> endpoint, and accept "token" on the protected resource.
> 
> I know there will be infinite debate about the right way to do this, but just
> wanted some thoughts for now. I will probably choose #2 as that seems most
> explicit, even though it's a few more characters.
>

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 20 Apr 2010 08:19:34 -0700

> From: Luke Shepard [mailto:[email-masked]]
> Sent: Monday, April 19, 2010 10:21 AM
> To: Eran Hammer-Lahav; OAuth WG
> Subject: RE: 'Scope' parameter proposal
> 
> This seems pretty elegant to me. I like that in the general case, the protected
> resource can give an error saying the scope required.
> 
> As a specific example of how Facebook could use this, we have an extended
> permission for an app to publish to a user's stream. If an app tries to publish
> to the stream today, and they don't have the permission, we give an error
> that says "You need the publish_stream permission." With this extension, we
> could also add a header like:
> 
> Then client libraries could craft an OAuth authorize URL for that scope,
> without having to refer to documentation.
> 
> One issue is how this would work with more complicated scenarios. There
> are resources that require multiple scopes, or even one of a few possible
> scopes (i.e., either "publish_stream" or "add_photo" to post a photo story).
> What are the semantics of the response header listing multiple scopes - are
> they all required, or just some?

The more complex the endpoint scope is, the more complex the "scope discovery" becomes. The trick is keeping the simple cases simple.

I would suggest this:

- If an endpoint requires a single or a set of scope identifiers, is uses a single WWW-Authenticate header with a scope parameter listing all the required values. They are all required (i.e. you need a token that covers them all). Anything else will not work.

- If an endpoint requires different sets of scope identifiers for different parameters or parameter values, it should reply with the required scope for the *failed* request only. It should help the client make the specific request it was attempting, not provide generic documentation for the entire endpoint capabilities.

EHL

> Of Eran Hammer-Lahav
> groups (e.g. contacts, photos). The server can provide a list of values for the
> client to use in its documentation, or the client can use the URIs or scope
> identifier of the protected resources it is trying to access (before or after
> getting a 401 response).
> 
> For example:
> 
> If the client needs access to two resource with different scopes, it requests
> an access token for scope=x2,x1.
> 
> That's it!
> 
> It allows the client to figure out what value to put in the scope parameter and
> how to encode multiple scopes without any server-specific documentation.

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 20 Apr 2010 08:32:03 -0700

- How is this proposal *better* than a separate scope parameter?

Instead of giving developers an outline of how to implement scope, you are basically saying that they can already do with without an extra protocol parameter and should go figure it out on their own (your proposal is pattern, not normative language). The group seems set on the need to have a scope parameter (unless you can convince them otherwise). Your proposal will produce a shorter specification, but not a simpler developer experience.

- How can the client tell if a token it already has is valid for a given protected resource?

Because there is no scope parameter, a client is forced to always get a new token when a request fails. I expect servers to issue tokens and say what they are for. For example, when returning an access token the server will include a scope=a,b,c. When the client is faced with an authentication challenge requiring a token capable of a and b, it knows it already have such a token. Clients can end up with multiple tokens, each with a different scope. This is a useful property of the protocol. It should be able to tell which token to use where.

EHL

> From: Manger, James H [mailto:[email-masked]]
> Sent: Monday, April 19, 2010 9:06 PM
> To: Eran Hammer-Lahav
> Cc: OAuth WG
> Subject: RE: [OAUTH-WG] 'Scope' parameter proposal
> 
> The first time a client app gets this response all it can do is add the 'scope' to
> the 'authz-uri'. In which case the separate 'scope' parameter offered no
> advantage. The resource server could have more simply returned:
> 
> The one situation where a 'scope' parameter can help interop (between
> client with no server-specific knowledge and the server) is when scopes are
> combined.
> 
> A client with a token for scope 'x1' that receives a 401 can request a new
> token that includes the extra scope 'x2' as well. Even in this situation,
> defining a 'scope' parameter is not necessary. The resource server knows the
> offered token was for scope 'x1', but scope 'x2' is required so the response
> can be:
> 
>      WWW-Authenticate: Token realm='Example', authz-
> uri="https://as.example.com/?scope=x2,x1"
> 
> The client just sees a URI and uses it to get a new token. This approach might
> require some resource servers to dynamically generate the 'authz-uri' value
> in error responses. I doubt that is too onerous.
> 
> 
> An alternative way to support combining scopes would be to include (or
> reference) an existing token when requesting a new one. For instance,
> define an 'access_token' parameter to include when redirecting a user to the
> AS. This would work for updating a token for another 'scope', for a longer
> duration, for extra 'permissions' etc.
> This is not absolutely necessary to define this extra 'access_token' parameter
> since the resource server could dynamically insert the current token into the
> returned 'authz_uri' value by itself, without requiring client code to do so.
> Another difficulty is that some access_tokens should not be exposed to
> users. There may need to be an 'access_token_id' separate from the actual
> 'access_token' value.
> 
> 
> In conclusion,
> * perhaps add explicit support for updating a token (as opposed to
> refreshing) by referencing an existing token when getting a new one.
> 
> 
> --
> James Manger
>

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 20 Apr 2010 08:42:59 -0700

> From: Dick Hardt [mailto:[email-masked]]
> Sent: Monday, April 19, 2010 8:07 PM
> To: Eran Hammer-Lahav
> Cc: OAuth WG

One scope parameter with one or more comma-delimited values (we can change this to space delimited if people would like to use URIs for scope identifiers).

> An unauthenticated GET on the resource could return the scope URI needed
> for READ, an unauthenticated PUT on the resource could return the scope
> URI for WRITE. What if you want to both do READs and WRITEs? There may
> be another scope that is READ/WRITE. READ and WRITE are pretty common
> capabilities, but one can imagine much more complex capabilities at
> resources.

A failed GET will return scope=read and a failed PUT will return scope=write. The server can issue an access token with:

scope=read
scope=write
scope=read,write

The last can be used for both. In other words, there should not be a read_write scope, instead, the token should have two scopes.

> The exact semantics to the resource are likely going to very contextual.

Yes, and this can get very complicated if people want an extremely granular way of doing permissions. For example, if you want to issue a token that can read contacts and write email, you will need to define a bigger set: email_read, email_write, contacts_read, contacts_write. On the other hand, if a write access is for all authorized resources, you need: email, contacts, read, write.

> Given that, returning a single scope value if that is all that makes sense to the
> resource will likely address many use cases.

This is true when looking at a single resource.

EHL

---

From: Joseph Smarr <[email-masked]>
Date: Tue, 20 Apr 2010 09:18:20 -0700

+1 to nailing down how to pass scopes, as Eran suggests (I think
space-delimited URLs is best, but that's a detail). Having implemented OAuth
with probably a dozen different providers (while at Plaxo), scopes were
always one of those things that just didn't fit cleanly into my libraries
and abstractions. Specifying a standard place for scope to go is one step,
but the choice of scopes were all still hardcoded in a per-domain config
file, which is a pain.

Worse, it makes it very hard to handle standard protocols like Portable
Contacts -- I want to be able to write a "contact importer from any Portable
Contacts provider", where the user types in the domain of their provider,
and the rest is automagic. Achieving this goal probably requires some amount
of discovery, and some ability to use "unregistered/anonymous mode", but it
also requires knowing which scopes to pass in. And the first two are pretty
easy to solve (include a PoCo entry in your site's /.well-known/host-meta
and allow anonymous/anonymous as consumer key/secret), so the scopes thing
is really the gating factor here.

Also +1 to Eran's meta-point that the job of a spec like this should be to
reach as far as possible towards specified behavior for interop. Just like
we defined a large number of contact fields in PoCo, the point was not
"everyone has to support all of these", but rather "if multiple parties want
to support any of these, now they have an agreed-upon way to do so". And
with scope, I hope by now it's well established that scopes are going to be
common and the status quo badly under-specifies how to query for them and
use them.

Thanks, js

On Tue, Apr 20, 2010 at 8:42 AM, Eran Hammer-Lahav <[email-masked]>wrote:

> One scope parameter with one or more comma-delimited values (we can change
> this to space delimited if people would like to use URIs for scope
> identifiers).
>
> A failed GET will return scope=read and a failed PUT will return
> scope=write. The server can issue an access token with:
>
> scope=read
> scope=write
> scope=read,write
>
> The last can be used for both. In other words, there should not be a
> read_write scope, instead, the token should have two scopes.
>
> Yes, and this can get very complicated if people want an extremely granular
> way of doing permissions. For example, if you want to issue a token that can
> read contacts and write email, you will need to define a bigger set:
> email_read, email_write, contacts_read, contacts_write. On the other hand,
> if a write access is for all authorized resources, you need: email,
> contacts, read, write.
>

---

From: Joseph Smarr <[email-masked]>
Date: Tue, 20 Apr 2010 09:41:34 -0700

In my experience, a frequent source of bugs/frustration for developers
implementing OAuth 1.0 was the fact that we have multiple "tokens" that are
easy to mix up and use in the wrong place. For instance, when I helped Dave
Winer debug his implementation (see
http://josephsmarr.com/2009/02/17/implementing-oauth-is-still-too-hard-but-it-doesnt-have-to-be/),
the problem ended up being that he was passing his request-token instead of
his access-token when making API requests (they're both returned as
oauth_token, after all). (So I'd strongly urge us to pick as disparate names
for the various "tokens" in OAuth 2.0 as possible, and to not use similar
variable names when returning them, to minimize these chances of mix-up.
It's probably also helpful if they look visually distinct, so it would be
more obvious "oh, you're using the wrong kind of token here", but that may
be too hard to enforce in practice.)

Thanks, js

On Tue, Apr 20, 2010 at 8:04 AM, Eran Hammer-Lahav <[email-masked]>wrote:

> In the flow endpoint I chose 'access_token' over token because of the
> refresh token. It seems better to talk about two different kinds of tokens
> than to have one generic 'token' and one with special meaning
> 'refresh_token'.
>
> The protected resource endpoint is the only place I agree requires a prefix
> because it always intrudes on another namespace or platform and the
> likelihood of a conflict is high. I used 'oauth_token' instead of
> 'oauth_access_token' for brevity thinking that it should be trivial to
> figure out what to put there (the only other option is a refresh token which
> isn't likely to be confused here).
>
> The header uses 'token' because it is a generic authentication scheme which
> doesn't mandate you use the OAuth flows to get a token. This is the only
> place I feel strongly about not changing it.
>

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 20 Apr 2010 10:12:28 -0700

I still don't know where you stand on the actual proposal. Is the spec currently confusing? If it is, please suggest alternatives.

EHL

From: Joseph Smarr [mailto:[email-masked]]
Sent: Tuesday, April 20, 2010 9:42 AM
To: Eran Hammer-Lahav
Cc: Luke Shepard; [email-masked]
Subject: Re: [OAUTH-WG] Consistency in access token parameter

In my experience, a frequent source of bugs/frustration for developers implementing OAuth 1.0 was the fact that we have multiple "tokens" that are easy to mix up and use in the wrong place. For instance, when I helped Dave Winer debug his implementation (see http://josephsmarr.com/2009/02/17/implementing-oauth-is-still-too-hard-but-it-doesnt-have-to-be/), the problem ended up being that he was passing his request-token instead of his access-token when making API requests (they're both returned as oauth_token, after all). (So I'd strongly urge us to pick as disparate names for the various "tokens" in OAuth 2.0 as possible, and to not use similar variable names when returning them, to minimize these chances of mix-up. It's probably also helpful if they look visually distinct, so it would be more obvious "oh, you're using the wrong kind of token here", but that may be too hard to enforce in practice.)

Thanks, js
On Tue, Apr 20, 2010 at 8:04 AM, Eran Hammer-Lahav <[email-masked]<mailto:[email-masked]>> wrote:
There is an explanation (I'm not defending it, just explaining).

EHL

> From: [email-masked]<mailto:[email-masked]> [mailto:[email-masked]<mailto:[email-masked]>] On Behalf
> Of Luke Shepard
> To: [email-masked]<mailto:[email-masked]>
> [email-masked]<mailto:[email-masked]>
_______________________________________________
OAuth mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/oauth

---

From: Eve Maler <[email-masked]>
Date: Tue, 20 Apr 2010 18:05:39 -0700

Folks-- I'm desperately trying to catch up on the list traffic after an enforced couple of weeks away (pity me :-).  This seems to be the freshest scope thread; let me know if I'm missing a newer one. I just wanted to remind people about the previous JSON-flavored proposal from the UMA group for standardizing expressions of scope, e.g.:

[{"method": "GET", "uri": "http://example.com/foo"},
{"method": "POST", "uri": "http://example.com/*"}]
We were interested in this approach because many of UMA's use cases deal with protecting access to web resources for simple data-sharing, e.g. GET access to all the photos in a directory, or to a single web resource that represents some identified chunk of the user's identity data. But it could also be pretty useful for any API that achieves at least level 1 in the "REST maturity model" (http://www.infoq.com/news/2010/03/RESTLevels -- obviously the particular semantics beyond the method/uri pair still needs to be documented, but this would encourage such documentation and more-standard APIs).

URL-encoding this obviously gets a bit ugly, but the basic form is otherwise readily processable. There was a bit of interest expressed on the OAuth Google group when I brought this up about a month ago, and I previously explored some of the implications in a discussion with Dick in the "Recent UMA work that may inform this group's deliberations" thread on this list about six weeks ago. (I couldn't find archives that went back this far in order to link to the thread. What am I missing?)

It seems like this proposal "goes there" in terms of getting as expressive as Eran fears, though the addition of the wildcard takes away a good deal of the pain depending on the particular interface at the endpoint(s). Is there any wider interest in "going there"?

	Eve

On 20 Apr 2010, at 9:18 AM, Joseph Smarr wrote:

> +1 to nailing down how to pass scopes, as Eran suggests (I think space-delimited URLs is best, but that's a detail). Having implemented OAuth with probably a dozen different providers (while at Plaxo), scopes were always one of those things that just didn't fit cleanly into my libraries and abstractions. Specifying a standard place for scope to go is one step, but the choice of scopes were all still hardcoded in a per-domain config file, which is a pain. 
> 
> Worse, it makes it very hard to handle standard protocols like Portable Contacts -- I want to be able to write a "contact importer from any Portable Contacts provider", where the user types in the domain of their provider, and the rest is automagic. Achieving this goal probably requires some amount of discovery, and some ability to use "unregistered/anonymous mode", but it also requires knowing which scopes to pass in. And the first two are pretty easy to solve (include a PoCo entry in your site's /.well-known/host-meta and allow anonymous/anonymous as consumer key/secret), so the scopes thing is really the gating factor here.
> 
> Also +1 to Eran's meta-point that the job of a spec like this should be to reach as far as possible towards specified behavior for interop. Just like we defined a large number of contact fields in PoCo, the point was not "everyone has to support all of these", but rather "if multiple parties want to support any of these, now they have an agreed-upon way to do so". And with scope, I hope by now it's well established that scopes are going to be common and the status quo badly under-specifies how to query for them and use them.
> 
> Thanks, js
> 
> On Tue, Apr 20, 2010 at 8:42 AM, Eran Hammer-Lahav <[email-masked]> wrote:
> 
> 

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

---

From: "Manger, James H" <[email-masked]>
Date: Wed, 21 Apr 2010 11:13:44 +1000

Eran,

>> "authz-uri=http://as.example.com/?scope=x2"
>> vs "authz-uri=http://as.example.com/" and "scope=x2"

> - How is this proposal *better* than a separate scope parameter?

1 field is simpler than 2.

> Your proposal will produce a shorter specification,
> but not a simpler developer experience.

It is no simpler for service developers -- these still need to agree on how to organize scopes/permissions with their authorization server.

It will be simpler for client developers. The concept of scopes disappears when they access services that they don't have service-specific knowledge about.

Developers writing for a specific service get a set of authorization URIs from the service's docs covering the different scopes (resources/permission/durations/...). Getting a set of URIs vs a base URI and a set of scopes is a trivial (or non-existent) difference.

> - How can the client tell if a token it already has is valid for a given protected resource?

This is absolutely required -- before making the request (ie before exposing the token).
My suggestion (in the "application/credentials" thread) is to include a list of locations whenever a token is issued. For example, a response to an access token request could include:
  "sites":["https://api.example.com", "http://photo.example.com"]

> Because there is no scope parameter, a client is forced to always get a new token when a request fails. I expect servers to issue tokens and say what they are for. For example, when returning an ac…

This sounds messy. A client might get "red", "blue", and "green" tokens all for the same resources. It cannot tell which is appropriate for any given request until a 401 response tells it. Yuck. This might allow tokens-of-least-privilege, but to be usable it demands far more extensive "discovery" mechanisms than per-request 401 responses.

A far more likely approach is that an existing token is upgraded to a more powerful token (more scopes) as required. In this situation, a client need to say to the authorization server (via a user):
  "Please authorize {stuff the resource server said I need}, I already have {stuff you gave me previously}."

A single authz-uri in a 401 response can encode "{stuff the resource server said I need}".
A existing token (or an identifier for such a token) can encode "{stuff you gave me previously}".

Client developers should not be burdened with the internal structure of the "stuff" without a good reason.

--
James Manger

> uri="https://as.example.com/?scope=x2"
> 
>

---

From: Chasen Le Hara <[email-masked]>
Date: Wed, 21 Apr 2010 13:22:31 -0700

Hi all,

On Tue, Apr 20, 2010 at 6:05 PM, Eve Maler <[email-masked]> wrote:

> It seems like this proposal "goes there" in terms of getting as expressive
> as Eran fears, though the addition of the wildcard takes away a good deal of
> the pain depending on the particular interface at the endpoint(s). Is there
> any wider interest in "going there"?
>

Yes. A couple months ago Iron Money implemented a permissions system[1] that
includes read_permissions and write_permissions as parameters when getting a
request token. Those two parameters take a comma-separated list of
pre-defined resource values (such as "write_permissions=accounts" for read
and write permissions for the /accounts/ resource).

If what is specified by OAuth 2.0 doesn’t meet Iron Money’s needs, that’s
fine, but I wanted to raise my hand high as one of the people interested in
a high level of expressiveness.
-Chasen

[1] https://ironmoney.com/api/permissions/

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Wed, 21 Apr 2010 14:41:52 -0700

How about review the proposals?

EHL

From: [email-masked] [mailto:[email-masked]] On Behalf Of Chasen Le Hara
Sent: Wednesday, April 21, 2010 1:23 PM
To: Eve Maler
Cc: [email-masked]; OAuth WG
Subject: Re: [OAUTH-WG] 'Scope' parameter proposal

Hi all,

On Tue, Apr 20, 2010 at 6:05 PM, Eve Maler <[email-masked]<mailto:[email-masked]>> wrote:
It seems like this proposal "goes there" in terms of getting as expressive as Eran fears, though the addition of the wildcard takes away a good deal of the pain depending on the particular interface at the endpoint(s). Is there any wider interest in "going there"?

Yes. A couple months ago Iron Money implemented a permissions system[1] that includes read_permissions and write_permissions as parameters when getting a request token. Those two parameters take a comma-separated list of pre-defined resource values (such as "write_permissions=accounts" for read and write permissions for the /accounts/ resource).

If what is specified by OAuth 2.0 doesn’t meet Iron Money’s needs, that’s fine, but I wanted to raise my hand high as one of the people interested in a high level of expressiveness.
-Chasen

---

From: Chasen Le Hara <[email-masked]>
Date: Wed, 21 Apr 2010 17:36:27 -0700

Your original proposal seems like it would do the trick, although I would
make the allowed scope values as flexible as possible while allowing
multiple scope values to be separated by commas or spaces.

If the scope values were opaque to the client, then a server could use
values such as "accounts", "read:accounts", or "GET:accounts". This would
fit my needs for Iron Money.

As proposed, the server could respond to unauthorized requests with the
minimum scope values required to make the client’s next request successful.

Hopefully this is the kind of feedback you were looking for.
-Chasen

On Wed, Apr 21, 2010 at 2:41 PM, Eran Hammer-Lahav <[email-masked]>wrote:

> *From:* [email-masked] [mailto:[email-masked]] *On Behalf
> Of *Chasen Le Hara
> *Sent:* Wednesday, April 21, 2010 1:23 PM
> *To:* Eve Maler
> *Cc:* [email-masked]; OAuth WG
>
> *Subject:* Re: [OAUTH-WG] 'Scope' parameter proposal
>
>
>
> Hi all,
>
>
>
> Yes. A couple months ago Iron Money implemented a permissions system[1]
> that includes read_permissions and write_permissions as parameters when
> getting a request token. Those two parameters take a comma-separated list of

---

From: Brian Eaton <[email-masked]>
Date: Thu, 22 Apr 2010 10:36:06 -0700

> That's a security issue we need to address (when to trust the resource server and reuse an existing token). We need to figure it out either way.

Are you sure we need to figure this out?  Is it even possible to figure it out?

I'm very skeptical of attempts to automatically determine which tokens
go with which resources.  There are no examples in the wild of people
doing this.  There have been a few proposals for techniques, all of
which have turned out to either be really complicated, or to have
fundamental security problems.  Or both.

I'd rather we didn't put stuff in the OAuth 2 spec that we aren't 100%
sure is going to work.  Ideally there should be lots of examples in
production.

I do like the idea of defining the scope parameter to be a delimited
list of otherwise opaque strings.  Several service providers have
already adopted this approach, and it seems to work reasonably well.
This would even work for the complex scope definitions that Eve and
Chase have brought up.

Defining scope to be a list of strings would also enable the "least
privilege" principal that Torsten mentioned, because once someone has
a token, there would be a well-defined way of reducing the scopes in
the token.  But it's probably too soon to actually add a "privilege
drop" call to the spec - as far as I know, no one has actually built
this yet.

Cheers,
Brian

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 22 Apr 2010 11:01:09 -0700

> From: Brian Eaton [mailto:[email-masked]]
> Sent: Thursday, April 22, 2010 10:36 AM
> To: Eran Hammer-Lahav
> Cc: John Kemp; OAuth WG
> > That's a security issue we need to address (when to trust the resource
> server and reuse an existing token). We need to figure it out either way.
> 

Yes. It doesn't mean we have to solve it, but we must give developers guidance on what to do or not to do. This is clearly a major part of any authentication protocol - when do use a set of credentials.

Rules around realms show this is very tricky but unless we update 2617 (which we are not chartered to do) we are still stuck with realm as a required parameter. One way to avoid this debate is to simply say that clients should use realms to decide when to reuse tokens. It doesn't solve the problem, but it doesn't create a new one either.

As for scopes:

In a 401 response, the scope parameter tells the client what scopes the token needs to include.
In a token request, the client may tell the server what scope it desires (based on documentation or the 401 response).
In a token response, the server may tell the client the scopes included in the token issued.

Scope is defined as a list of opaque identifier (which can be strings or URIs). Multiple scopes should be space delimited because it's the easiest character to allow both simple names and URIs (URIs can include un-escaped commas).

In other word, we need to address it, but it doesn't need to be part of the scope proposal.

EHL

---

From: Brian Eaton <[email-masked]>
Date: Thu, 22 Apr 2010 11:21:57 -0700

On Thu, Apr 22, 2010 at 11:01 AM, Eran Hammer-Lahav <[email-masked]> wrote:
> Rules around realms show this is very tricky but unless we update 2617 (which we
> are not chartered to do) we are still stuck with realm as a required parameter.
> One way to avoid this debate is to simply say that clients should use realms to
> decide when to reuse tokens. It doesn't solve the problem, but it doesn't create a
> new one either.

The existing rules for realm are basically same-origin policy.  That
doesn't actually work for any of the delegated auth solutions that
OAuth2 is based on, and is meant to replace.  Telling people to use
realm is terrible, no-good, very-bad advice.

As far as I can tell, the only practical guidance we can give
developers is "follow the service provider documentation."

Cheers,
Brian

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 22 Apr 2010 11:30:06 -0700

What makes this so much different from Basic? Instead of using a flow the browser simply asks the user for a set of credentials. Once it has a set, it reuses it based on realm.

EHL

> Sent: Thursday, April 22, 2010 11:22 AM
> To: Eran Hammer-Lahav
> Cc: OAuth WG
> > Rules around realms show this is very tricky but unless we update 2617
> > (which we are not chartered to do) we are still stuck with realm as a
> required parameter.
> > One way to avoid this debate is to simply say that clients should use
> > realms to decide when to reuse tokens. It doesn't solve the problem,
> > but it doesn't create a new one either.
> 
> The existing rules for realm are basically same-origin policy.  That doesn't
> actually work for any of the delegated auth solutions that
> OAuth2 is based on, and is meant to replace.  Telling people to use realm is
> terrible, no-good, very-bad advice.
> 
> As far as I can tell, the only practical guidance we can give developers is
> "follow the service provider documentation."
> 
> Cheers,
> Brian

---

From: Brian Eaton <[email-masked]>
Date: Thu, 22 Apr 2010 11:33:03 -0700

On Thu, Apr 22, 2010 at 11:30 AM, Eran Hammer-Lahav <[email-masked]> wrote:
> What makes this so much different from Basic? Instead of using a flow the browser
> simply asks the user for a set of credentials. Once it has a set, it reuses it based on realm.

Those rules aren't practical or correct for most APIs.

Remember that basic auth was designed for people using web browsers.

---

From: John Kemp <[email-masked]>
Date: Thu, 22 Apr 2010 14:39:08 -0400

Hi Brian,

[...]

> sure is going to work.  Ideally there should be lots of examples in

I agree.

> list of otherwise opaque strings.

So what we get in OAuth is simply an agreed parameter name in which to carry a list of opaque strings which might be used in any way imaginable (ie. not documented by the spec, no model in relation to the token) with usage model basically as decided by the various parties at deployment time. 

I'm not really seeing the *interoperability* value of that at all without some more rigorous description of the underlying model (note: I'm not saying we should necessarily make that model, but merely that without any described model, you don't have very much interoperability) 

>  Several service providers have

I agree that 'scope' is something that many SPs want. If they don't want it roughly the same way though (something more than a "bucket of opaque strings with a standard name") I don't know if I understand the point to standardizing it. 

Even those who write libraries won't get much value since they'll have to provide an extension point to do whatever is needed according to the particular deployment here anyway, and that extension point could already exist without the existence of an already-named parameter for "scope" functionality. 

[...]

- johnk

---

From: Brian Eaton <[email-masked]>
Date: Thu, 22 Apr 2010 11:47:49 -0700

On Thu, Apr 22, 2010 at 11:39 AM, John Kemp <[email-masked]> wrote:
> I agree that 'scope' is something that many SPs want. If they don't want it roughly the
> same way though (something more than a "bucket of opaque strings with a standard
> name") I don't know if I understand the point to standardizing it.

Well, we've moved from "opaque string" to "bucket of opaque strings".
And from there, we could in theory move to "bucket of opaque strings
that represent privileges, and well defined ways of dropping those
privileges".

I'm not sure that counts as progress, but it might be. =)

This is hand-wavy, but the main reason I see to standardize a scope
parameter is that it helps developers with a consistent mental model
of how service providers work.  It also helps new service providers be
consistent with the way previous APIs have been built.

Cheers,
Brian

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 22 Apr 2010 11:54:10 -0700

> Sent: Thursday, April 22, 2010 11:48 AM
 
> > I agree that 'scope' is something that many SPs want. If they don't
> > want it roughly the same way though (something more than a "bucket of
> > opaque strings with a standard

And that's where we should stop. That's as far as required given the way scope is widely used today.

> And from there, we could in theory move to "bucket of opaque strings that
> represent privileges, and well defined ways of dropping those privileges".

We only need to make sure not to prevent it. We should not specify something that is too limited to begin with. I don't think we have.
 
> parameter is that it helps developers with a consistent mental model of how
> service providers work.  It also helps new service providers be consistent
> with the way previous APIs have been built.

If that is all you want to accomplish we can describe such a mechanism without naming a parameter. What you are describing is prose, not normative language.

EHL

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 22 Apr 2010 12:07:05 -0700

This suggests we need to rethink our goal of interop and replace it with library re-use.

To me interop means that a client can interact with an unknown server by simply speaking the protocol (the way an email can be delivered to any server). Library re-use means that we define a set of configuration values (client identifier, endpoints, cryptographic algorithms, scope, realm policy, etc.) and once those are manually set (or via a discovery specification that is completely out of scope) to make the library work.

If we are not going to enable a client to access a protected resource hosted by an unfamiliar server, we need to stop pretending this (alone) is about interop. In other words, if we take this approach we are mandating paperwork to make the protocol work, at least based on this single specification. We can also drop advertising the authorization and token endpoints in a 401 or really *any* parameter in a WWW-Authenticate response.

I'm not opposed to that, and it is in line with the charter (which left discovery out).
 
Regardless, I disagree with your conclusion that the scope proposal doesn't accomplish interop. It allows a client to interact with an unknown server, obtain an access token for the required scope, and access it. It doesn't address the trust issue of when to reuse an existing token, but that's going to be a problem with or without a scope. If the client never attempts to reuse a token but always obtain a new access token when encountering an unknown server, it can interop perfectly well. And making scope a list of values allows secure reuse of tokens using same-origin policy (which is still useful even if limited).

OAuth 1.0 doesn't accomplish interop because it is under-specified. I have no problems keeping 2.0 at the same level. I just think it is premature to give up.

EHL

> Sent: Thursday, April 22, 2010 11:39 AM
> To: Brian Eaton
> Cc: Eran Hammer-Lahav; OAuth WG
> So what we get in OAuth is simply an agreed parameter name in which to
> carry a list of opaque strings which might be used in any way imaginable (ie.
> not documented by the spec, no model in relation to the token) with usage
> model basically as decided by the various parties at deployment time.
> 
> I'm not really seeing the *interoperability* value of that at all without some
> more rigorous description of the underlying model (note: I'm not saying we
> should necessarily make that model, but merely that without any described
> model, you don't have very much interoperability)
> 
> I agree that 'scope' is something that many SPs want. If they don't want it
> roughly the same way though (something more than a "bucket of opaque
> strings with a standard name") I don't know if I understand the point to
> standardizing it.
> 
> Even those who write libraries won't get much value since they'll have to
> provide an extension point to do whatever is needed according to the
> particular deployment here anyway, and that extension point could already
> exist without the existence of an already-named parameter for "scope"
> functionality.
> 
> [...]
> 
> - johnk

---

From: John Kemp <[email-masked]>
Date: Thu, 22 Apr 2010 15:09:54 -0400

On Apr 22, 2010, at 2:21 PM, Brian Eaton wrote:

> The existing rules for realm are basically same-origin policy.

Well, that's usually true in practice for HTTP BASIC, but looking at RFC2617, realm is really about telling the *user* the necessary credentials to access that resource. So 'realm' is supposed to be user-informative text, and could thus easily be something other than same-origin policy based. In fact the word 'realm' makes 'security realm' spring to mind. I don't think that by definition it excludes "multiple origins". 

>  That

Realm is intended to be information to guide a user on what credentials to use. OAuth is not concerned as such with credentials, it's concerned with authorization tokens. So I agree, we shouldn't use realm for something other than informing the user, should that be necessary. 

> developers is "follow the service provider documentation."

Agree.

- johnk

---

From: Brian Eaton <[email-masked]>
Date: Thu, 22 Apr 2010 12:35:48 -0700

On Thu, Apr 22, 2010 at 12:07 PM, Eran Hammer-Lahav <[email-masked]> wrote:
> If we are not going to enable a client to access a protected resource hosted by an unfamiliar
> server, we need to stop pretending this (alone) is about interop. In other words, if we take
> this approach we are mandating paperwork to make the protocol work, at least based
> on this single specification. We can also drop advertising the authorization and token
> endpoints in a 401 or really *any* parameter in a WWW-Authenticate response.

I think dropping the advertisements is the right thing to do.

I'm hopeful that either PoCo or the IMAP SASL/OAuth work ends up
showing how automatic interop is possible.

But I'd hate to have OAuth2 recommend something that doesn't actually work.

Cheers,
Brian

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 22 Apr 2010 12:41:02 -0700

Drop the 'scope' parameter as well and we're on the same page.

EHL

> Sent: Thursday, April 22, 2010 12:36 PM
> To: Eran Hammer-Lahav
> Cc: John Kemp; OAuth WG
> > If we are not going to enable a client to access a protected resource
> > hosted by an unfamiliar server, we need to stop pretending this
> > (alone) is about interop. In other words, if we take this approach we
> > are mandating paperwork to make the protocol work, at least based on
> > this single specification. We can also drop advertising the authorization and
> token endpoints in a 401 or really *any* parameter in a WWW-Authenticate
> response.
> 
> I'm hopeful that either PoCo or the IMAP SASL/OAuth work ends up showing
> how automatic interop is possible.
>

---

From: Chasen Le Hara <[email-masked]>
Date: Thu, 22 Apr 2010 12:49:14 -0700

On Thu, Apr 22, 2010 at 12:07 PM, Eran Hammer-Lahav <[email-masked]>wrote:

> To me interop means that a client can interact with an unknown server by
> simply speaking the protocol (the way an email can be delivered to any
> server). Library re-use means that we define a set of configuration values
> (client identifier, endpoints, cryptographic algorithms, scope, realm
> policy, etc.) and once those are manually set (or via a discovery
> specification that is completely out of scope) to make the library work.
>
> hosted by an unfamiliar server, we need to stop pretending this (alone) is
> about interop. In other words, if we take this approach we are mandating
> paperwork to make the protocol work, at least based on this single
> specification. We can also drop advertising the authorization and token

In my case, the proposed "bucket of opaque strings separated by spaces" does
enable a client to access protected resources without knowing the details of
Iron Money’s permission system.

In 1.0, there was no set way of doing scope/permissions, which led me to a
custom solution in which it’s not possible to access any protected resources
without reading the documentation. With scope, the client wouldn’t need to
know anything about the permission system; Iron Money could simply reply
with the required scope values to access the resource.

It seems as if this would also fit Facebook’s requirements, and I’m guessing
this would fit the bill for most service providers as well.
-Chasen

---

From: Brian Eaton <[email-masked]>
Date: Thu, 22 Apr 2010 13:50:22 -0700

> Drop the 'scope' parameter as well and we're on the same page.

So we have a choice between

a) not documenting something that a bunch of providers have already
implemented and found useful
   or
b) documenting something that no one has built yet, and that might not
actually work

Bummer. =)

---

From: Eve Maler <[email-masked]>
Date: Thu, 22 Apr 2010 16:24:36 -0700

I'm getting whiplash. :)  Some of us are working on UMA implementations based on the ever-changing OAuth substrate, and just discussed being glad we could reuse OAuth's advertisement of these two endpoints rather than inventing our own mechanism. If it goes, I guess we'll have to go back to defining a way to indicate it in Authz Manager (~AS) hostmeta so that the Host (~Resource Server) can pick it up and tell the Requester (~Client) where to go.

FWIW,

	Eve

Eve Maler
[email-masked]

---

From: "Manger, James H" <[email-masked]>
Date: Fri, 23 Apr 2010 11:11:55 +1000

We mustn't drop advertisements (details in 401 responses).
We mustn't drop the goal of a standard for interoperability.

I don't think we have to, just because of difficulties over the 'scope' parameter.

How about if the spec explicitly says:

"There can be any number of authorization endpoints for a given service — representing different resources, different permissions, different durations etc. Each authorization endpoint has a URI. A client needs one such URI to start the OAuth user delegation dance.

"A resource server can advertise support for OAuth by returning a 'WWW-Auth' HTTP header that includes an authz endpoint URI. The URI returned shall represent sufficient authority to access the resource that was requested.

"A query parameter named 'scope' has been used by many services to differentiate different authorization URIs. The 'scope' value is often a comma-separated list of strings. The OAuth spec will not define a 'scope' parameter that is inconsistent with this current usage. Different authorization URIs may be distinguished by other aspects in the URIs as well at the service’s discretion."

This allows most current practice (reconciling comma-separated and space-separated is not really possible). It doesn't impose any new models. It doesn't add much (if anything) to interoperability, but I don't think it harms it much either. It explicitly indicates that using a 'scope' parameter in authz URIs does not make a service non-compliant with OAuth, even if the semantics of the 'scope' value is service-specific.

I suspect the key concept is realising that there can be many authz URIs — and that that is ok. OAuth libraries should support this concept — perhaps by not expecting a single authz URI to be provided in a config file.
The Terminology section should be reworded to reflect this concept. For example:
"authorization endpoint
  *An* endpoint on the authorization server capable of obtaining a user's authority to delegate requested access to a client application"

> b) documenting something that no one has built yet,
> and that might not actually work

Defining a scope field in a 401 response is the novel aspect that “might not actually work”. Allowing a 'scope' query parameter in authz URIs is be quite separate.

-- 
James Manger

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Brian Eaton
Sent: Friday, 23 April 2010 6:50 AM
To: Eran Hammer-Lahav
Cc: OAuth WG
Subject: Re: [OAUTH-WG] 'Scope' parameter proposal

Bummer. =)

---

From: Torsten Lodderstedt <[email-masked]>
Date: Sat, 24 Apr 2010 00:31:09 +0200

> I suspect the key concept is realising that there can be many authz URIs — and that that is ok. OAuth libraries should support this concept — perhaps by not expecting a single authz URI to be provi…

I fully agree with your statement. Authorization servers may use 
different URLs for different resource servers. For example, our token 
service uses URLs like

https://tokenservice.example.com/tokens/service1
https://tokenservice.example.com/tokens/service2

to identify services and their respective tokens.

> Defining a scope field in a 401 response is the novel aspect that “might not actually work”. Allowing a 'scope' query parameter in authz URIs is be quite separate.

I agree again. Moreover, I would say a 401 response is not the right 
place to talk about scopes. From my point of view, the scope is about 
permissions (authorization) and not about authentication. So a scope 
violation should be signaled using status code 403 (Forbidden).

from rfc2616
"The server understood the request, but is refusing to fulfill it. 
Authorization will not help and the request SHOULD NOT be repeated. If 
the request method was not HEAD and the server wishes to make public why 
the request has not been fulfilled, it SHOULD describe the reason for 
the refusal in the entity. If the server does not wish to make this 
information available to the client, the status code 404 (Not Found) can 
be used instead."

So if the token send with a request is not suffiently scoped, the server 
could respond as follows

HTTP/1.1 403
insufficient permission, required scope=delete

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

I followed this thread the last days and came to the following 
conclusions/perception I would like to discuss:

Providing authorization server endpoint URLs to clients dynamically is a 
must have. Otherwise, URL cannot be changed easily by the resource or 
authorization server. Every authorization server may use several authz 
URLs. Such URLs may also contain query parameters. The client should use 
these URLs "as is" and add further parameters required for the flow it 
uses, respectively.

Realm in contrast to scope is about authentication domains. The realm 
element represents a protection doamin, typically identified with a 
single user database. In the context of OAuth, the authorization server 
(conceptually) represents a user database, but I don't tend to say the 
authorization server is the realm. I would suggest a realm represents 
the set of endpoints accepting the same kind of token (by content) 
issued by the same authorization server. Different tokens are need if 
authorization servers issue service-specific self-containt tokens with 
different contents (attributes or permissions), typically protected by 
different signatures. If an authorization server issues one kind of 
token only, which can be used on all services it is responsible for, 
there is one realm only. In contrast, if the authorization server issues 
different tokens, every realm is the set of resource servers (services) 
accepting this kind of token. Based on this definition, libraries can 
automatically send a particular token to all resource servers using the 
same realm.

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.

A token may be issued to a particular realm but it might not suffienctly 
be authorized to perform all possible actions on all corresponding 
resource servers. This means that the servers can interpret the token 
but may refuse to process a particular requests. Generally, a client 
should know the maximum set of permissions (scope) needed to function 
properly and indicate this during the authorization process.

I would like to illustrate what I have written in an example:

The client wants to access a photo on server webstorage.example.com

GET  /photos/example.jpg HTTP/1.1
      Host: webstorage.example.com

The server responds with the following header:

WWW-Authenticate Token realm="http://authorize.example.com/webstorage",
                
authz-uri="https://authorize.example.com/oauth2/tokens/webstorage?format=compact",
                token-uri="https://authorize.example.com/oauth2/tokens"

The client does not find a refresh token for the realm 
"http://authorize.example.com/webstorage" in its persistent storage and 
thus initiates a authorization process. This time the client does not 
request a certain scope, so a default scope is automatically selected by 
the authorization server.

GET 
/oauth2/tokens/webstorage?format=compact&type=web_server&client_id=s6BhdRkqt3&redirect_uri=
          https%3A%2F%2Fwebstorage%2Eexample%2Ecom%2Fcb HTTP/1.1
      Host: https://authorize.example.com

After obtaining the token, the client retries the service request

GET  /photos/example.jpg HTTP/1.1
      Host: webstorage.example.com

Authorization: Token 
token="ECDuk8mV8OJIK6D6PAteNtXJAAsEBwAAASgsdUvAAAABKC4sv8ABAAgAAAEoLHVLqBShAyHT24Hq78UYdr3a-
bDggz2IAgwQAEkBUXdxYwACAAETJQAAAAA="

HTTP/1.1 200 OK

The client now wants to download another photo. Since the resource path 
contains the "same last symbolic element in the path field of the 
Request-URI", the token is automatically reused for that request.

GET  /photos/example1.jpg HTTP/1.1
      Host: webstorage.example.com

Authorization: Token 
token="ECDuk8mV8OJIK6D6PAteNtXJAAsEBwAAASgsdUvAAAABKC4sv8ABAAgAAAEoLHVLqBShAyHT24Hq78UYdr3a-
bDggz2IAgwQAEkBUXdxYwACAAETJQAAAAA="

After that, the client wants to download a video on the same resource 
server. Since the URL differs, it sends an unauthorized request first

GET  /videos/example1.mpg HTTP/1.1
      Host: webstorage.example.com

WWW-Authenticate Token realm="http://authorize.example.com/webstorage",
                
authz-uri="https://authorize.example.com/oauth2/tokens/webstorage?format=compact",
                token-uri="https://authorize.example.com/oauth2/tokens"

The resource server responds with the same realm as before thus the 
client can reuse the token again.

GET  /videos/example1.mpg HTTP/1.1
      Host: webstorage.example.com

Authorization: Token 
token="ECDuk8mV8OJIK6D6PAteNtXJAAsEBwAAASgsdUvAAAABKC4sv8ABAAgAAAEoLHVLqBShAyHT24Hq78UYdr3a-
bDggz2IAgwQAEkBUXdxYwACAAETJQAAAAA="

In the last step, the client wants to delete a photo. It sends the 
following request

DELETE /photos/example.jpg HTTP/1.1
      Host: webstorage.example.com

Authorization: Token 
token="ECDuk8mV8OJIK6D6PAteNtXJAAsEBwAAASgsdUvAAAABKC4sv8ABAAgAAAEoLHVLqBShAyHT24Hq78UYdr3a-
bDggz2IAgwQAEkBUXdxYwACAAETJQAAAAA="

Since the token has a default scope, which does not contain the 
permission to delete anything, the server responds with a status code 
403 and a description of the problem in the response entity.

HTTP/1.1 403
scope=delete

Hence the client initiates an authorization process in order to obtain 
this additional authorization (together with a standard set of other 
permissions).

GET 
/oauth2/tokens/webstorage?format=compact&type=web_server&client_id=s6BhdRkqt3&redirect_uri=
          
https%3A%2F%2Fwebstorage%2Eexample%2Ecom%2Fcb&scope=read,upload,delete 
HTTP/1.1
      Host: https://authorize.example.com

In the last call, the client uses the new token to delete the photo.

DELETE /photos/example.jpg HTTP/1.1
      Host: webstorage.example.com

Authorization: Token 
token="ECCkrX3ASC9BCLnjOzmYzMSHAAsEBwAAASgsgwIuAAABKC46di4BAAgAAAEoLIMCFwtd7LCwTW6MflQB8WT_mjZVQNpZAgwQAEkBUXdxYwACAAETJQAAAAA="

HTTP/1.1 200 OK

Any thoughts?

regards,
Torsten.

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Fri, 23 Apr 2010 16:31:53 -0700

This looks about right.

EHL

> From: Torsten Lodderstedt [mailto:[email-masked]]
> Sent: Friday, April 23, 2010 3:31 PM
> To: Manger, James H
> Cc: Brian Eaton; Eran Hammer-Lahav; OAuth WG
> > I suspect the key concept is realising that there can be many authz URIs —
> and that that is ok. OAuth libraries should support this concept — perhaps by
> not expecting a single authz URI to be provided in a config file.
> >
> 
> I fully agree with your statement. Authorization servers may use different
> URLs for different resource servers. For example, our token service uses
> URLs like
> 
> >> b) documenting something that no one has built yet, and that might
> >> not actually work
> >>
> > Defining a scope field in a 401 response is the novel aspect that “might not
> actually work”. Allowing a 'scope' query parameter in authz URIs is be quite
> separate.
> >
> >
> 
> I agree again. Moreover, I would say a 401 response is not the right place to
> talk about scopes. From my point of view, the scope is about permissions
> (authorization) and not about authentication. So a scope violation should be
> signaled using status code 403 (Forbidden).
> 
> from rfc2616
> Authorization will not help and the request SHOULD NOT be repeated. If the
> request method was not HEAD and the server wishes to make public why the
> request has not been fulfilled, it SHOULD describe the reason for the refusal
> in the entity. If the server does not wish to make this information available to
> the client, the status code 404 (Not Found) can be used instead."
> 
> So if the token send with a request is not suffiently scoped, the server could
> respond as follows
> 
> HTTP/1.1 403
> Providing authorization server endpoint URLs to clients dynamically is a must
> have. Otherwise, URL cannot be changed easily by the resource or
> authorization server. Every authorization server may use several authz URLs.
> Such URLs may also contain query parameters. The client should use these
> URLs "as is" and add further parameters required for the flow it uses,
> respectively.
> 
> element represents a protection doamin, typically identified with a single
> user database. In the context of OAuth, the authorization server
> authorization server is the realm. I would suggest a realm represents the set
> of endpoints accepting the same kind of token (by content) issued by the
> same authorization server. Different tokens are need if authorization servers
> issue service-specific self-containt tokens with different contents (attributes
> or permissions), typically protected by different signatures. If an
> authorization server issues one kind of token only, which can be used on all
> services it is responsible for, there is one realm only. In contrast, if the
> authorization server issues different tokens, every realm is the set of
> resource servers (services) accepting this kind of token. Based on this
> definition, libraries can automatically send a particular token to all resource
> servers using the same realm.
> 
> 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.
> 
> A token may be issued to a particular realm but it might not suffienctly be
> authorized to perform all possible actions on all corresponding resource
> servers. This means that the servers can interpret the token but may refuse
> to process a particular requests. Generally, a client should know the
> maximum set of permissions (scope) needed to function properly and
> indicate this during the authorization process.
> 
> WWW-Authenticate Token
> realm="http://authorize.example.com/webstorage",
> 
> authz-
> uri="https://authorize.example.com/oauth2/tokens/webstorage?format=co
> mpact",
> thus initiates a authorization process. This time the client does not request a
> certain scope, so a default scope is automatically selected by the
> authorization server.
> 
> GET
> contains the "same last symbolic element in the path field of the Request-
> URI", the token is automatically reused for that request.
> 
> WWW-Authenticate Token
> realm="http://authorize.example.com/webstorage",
> 
> authz-
> uri="https://authorize.example.com/oauth2/tokens/webstorage?format=co
> mpact",
> The resource server responds with the same realm as before thus the client
> can reuse the token again.
> 
> In the last step, the client wants to delete a photo. It sends the following
> request
> 
> Since the token has a default scope, which does not contain the permission
> to delete anything, the server responds with a status code
> Hence the client initiates an authorization process in order to obtain this
> additional authorization (together with a standard set of other permissions).
> 
> GET
> token="ECCkrX3ASC9BCLnjOzmYzMSHAAsEBwAAASgsgwIuAAABKC46di4BA
> AgAAAEoLIMCFwtd7LCwTW6MflQB8WT_mjZVQNpZAgwQAEkBUXdxYwACA
> AETJQAAAAA="
> 
> HTTP/1.1 200 OK
> 
> Any thoughts?
> 
> regards,
> Torsten.

---

From: Brian Eaton <[email-masked]>
Date: Fri, 23 Apr 2010 17:05:14 -0700

> We mustn't drop the goal of a standard for interoperability.

I share the goals, I just don't think that a specification is the way
to get there.  I think working examples in the wild would help
enormously.

> Defining a scope field in a 401 response is the novel aspect that “might not actually work”. Allowing a 'scope' query parameter in authz URIs is be quite separate.

Yeah, I agree with that analysis.

Though I don't know of any providers that are returning authorization
URLs in 401 responses right now.  That's novel, too.

Cheers,
Brian

---

From: Torsten Lodderstedt <[email-masked]>
Date: Tue, 27 Apr 2010 20:49:04 +0200

> URLs in 401 responses right now.  That's novel, too.

That's novel, yes. But I think no one did it before because there was no 
need to do so. BASIC and DIGEST don't require authorization endpoint 
coordinates. SPNEGO/Kerberos would be a candidate because of its 
architecture, but it uses the standard Kerberos mechanisms (config or 
DNS-based discovery via SRV records).

I think there is a need for a standardized way of authorization server 
discovery. Using the WWW-Authentication header is better than nothing 
from my point of view.

Alternatively, resource servers could publish their supported 
authentication servers via XRD or a similar mechanism. The authorization 
server in turn could publish its endpoints (and capabilities) the same way.

regards,
Torsten.

---

From: John Panzer <[email-masked]>
Date: Tue, 27 Apr 2010 12:19:52 -0700

The old AOL Blogs API, which used AOL's OpenAuth service, provided a url=
parameter on WWW-Authenticate: challenges:

dev.estage.aol.com/aolblogs_api#mozTocId815750

<http://webcache.googleusercontent.com/search?q=cache:VD8dYmqAaREJ:dev.estage.aol.com/aolblogs_api+AOL+OpenAuth+401+response+WWW-Authenticate&cd=9&hl=en&ct=clnk&gl=us>

   -  If authorization fails, a 401 response is returned with a
   WWW-Authenticate: header providing additional details.

WWW-Authenticate: OpenAuth realm="AOLBlogs", status="status", msg="message",
url="url"

This is from 2007 ;).

On Tue, Apr 27, 2010 at 11:49 AM, Torsten Lodderstedt <
[email-masked]> wrote:

>>> Defining a scope field in a 401 response is the novel aspect that “might
>>> not actually work”. Allowing a 'scope' query parameter in authz URIs is be
>>> quite separate.
>>>
>>>
> discovery. Using the WWW-Authentication header is better than nothing from
> my point of view.
>

---

From: "Keenan, Bill" <[email-masked]>
Date: Tue, 27 Apr 2010 12:39:47 -0700

The amount of writing done on scope the past few weeks indicates this
concept generates a lot of passion. I hope we will spend some time on it
during IIW X and at our 20-May f2f.

For me, delegation is an identity in my system authorizing my system to
issue a toke to an identity, which is not in my system. The rights and
privileges attached to the token will almost never be the same as the
authorizing user. [My colleague, Tom Holodnik, is working on a user
story around tax return data you must share with the financial aid
department at a university your child is applying to.] My current
thinking is to present a set of constraints in the UI presented to the
authorizing user. Our systems would maintain these constrains - others
may choose to encode the constraints into their opaque token. I'm having
a hard time seeing how I can trust the scope parameter passed in by a
delegate. Even if I could trust the passed in scope, it does not help me
with access control of a complex entity model (e.g., tax return). I
still need some other mechanism for access control, and I'm concerned
scope defined in the specification may create unintended conflict cases
with my access control model.

BillK

From: [email-masked] [mailto:[email-masked]] On Behalf
Of John Panzer
Sent: Tuesday, April 27, 2010 12:20 PM
To: Torsten Lodderstedt
Cc: OAuth WG
Subject: Re: [OAUTH-WG] 'Scope' parameter proposal

The old AOL Blogs API, which used AOL's OpenAuth service, provided a
url= parameter on WWW-Authenticate: challenges:

*          If authorization fails, a 401 response is returned with a
WWW-Authenticate: header providing additional details.

WWW-Authenticate: OpenAuth realm="AOLBlogs", status="status",
msg="message", url="url"

This is from 2007 ;).

On Tue, Apr 27, 2010 at 11:49 AM, Torsten Lodderstedt
<[email-masked]> wrote:

	I share the goals, I just don't think that a specification is
the way
	to get there.  I think working examples in the wild would help
	enormously.

	Defining a scope field in a 401 response is the novel aspect
that "might not actually work". Allowing a 'scope' query parameter in
authz URIs is be quite separate.

	Though I don't know of any providers that are returning
authorization
	URLs in 401 responses right now.  That's novel, too.

Alternatively, resource servers could publish their supported
authentication servers via XRD or a similar mechanism. The authorization
server in turn could publish its endpoints (and capabilities) the same
way.

regards,
Torsten.