Subject: [OAUTH-WG] Scope using Realm idea

From: Eran Hammer-Lahav <[email-masked]>
Date: Fri, 2 Apr 2010 09:18:36 -0700

This is half baked but I wanted to get people's reaction:

Clients tries accessing a resource with or without an access token:

  GET /resource/1 HTTP/1.1
  Host: server.example.com

The server replies with:

  HTTP/1.1 401 Unauthorized
  WWW-Authenticate: OAuth realm='example'

Clients requests an access token (using the client credentials flow) and
includes the requested realm (line breaks for display purposes):

  POST /access_token HTTP/1.1
  Host: server.example.com
  
  client_id=s6BhdRkqt3&client_secret=8eSEIpnqmM&
  mode=flow_client&realm=example

The server issues a access token capable of accessing the resource realm.

This means one new parameter on the request side which is already baked into
the 401 response in a standard way.

Thoughts?

EHL

---

From: "Paul C. Bryan" <[email-masked]>
Date: Fri, 02 Apr 2010 09:24:28 -0700

Presumably, the realm was used to discover the token issuance endpoints.
Why wouldn't the discovered URL of the access token endpoint dictate
realm, and why can't the realm then be implicit beyond discovery?

-----Original Message-----
From: Eran Hammer-Lahav <[email-masked]>
To: OAuth WG <[email-masked]>
Subject: [OAUTH-WG] Scope using Realm idea
Date: Fri, 2 Apr 2010 09:18:36 -0700

  GET /resource/1 HTTP/1.1
  Host: server.example.com

The server replies with:

  

Thoughts?

EHL

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

---

From: David Recordon <[email-masked]>
Date: Fri, 2 Apr 2010 14:11:54 -0700

Assuming that this is mean to replace the scope parameter?

---

From: Igor Faynberg <[email-masked]>
Date: Fri, 02 Apr 2010 17:45:52 -0400

I don't see any problem at all.

Igor

---

From: Dick Hardt <[email-masked]>
Date: Fri, 2 Apr 2010 15:27:38 -0700

There are times when a resource may have different scope for different kinds of access. realm != scope

---

From: Torsten Lodderstedt <[email-masked]>
Date: Sat, 03 Apr 2010 09:59:53 +0200

I don't think the example implies discovery. As far as I understood, it 
just uses the same addresses for both protected resource and 
authorization server. This might work for some deployments, it won't 
work for installation with a single authorization server authorizing 
access to multiple resources with different adresses.

I like the idea of using the protected resources realm as resource 
specification in the authorization server requests. To enhance the idea 
we need some kind of endpoint discovery. The simplest way would be to 
include another parameter in the WWW-Authenticate response indicating 
the authorization servers endpoint, e.g.

HTTP/1.1 401 Unauthorized
   WWW-Authenticate: OAuth realm='example', endpoint='authorization.example.com'

According to http://www.ietf.org/rfc/rfc2617.txt (Basic/Digest Authn 
Spec) this should be a legal usage of the WW-Authenticate header. An 
example of a WWW-Authenticate header for Digest authentication is:

WWW-Authenticate: Digest realm="[email-masked]",
                          qop="auth,auth-int",
                          nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",
                          opaque="5ccc069c403ebaf9f0171e9517f40e41"

regards,
Torsten.
> From: Eran Hammer-Lahav<[email-masked]>
> To: OAuth WG<[email-masked]>

---

From: Torsten Lodderstedt <[email-masked]>
Date: Sat, 03 Apr 2010 12:35:28 +0200

I've just seen, the current draft already specifies an attribute 
"authorization-uri" for the WWW-Authenticate header. Is this attribute 
intended for announcing the authorization servers endpoint?

> I don't think the example implies discovery. As far as I understood, 
> it just uses the same addresses for both protected resource and 
> specification in the authorization server requests. To enhance the 
> idea we need some kind of endpoint discovery. The simplest way would 
> be to include another parameter in the WWW-Authenticate response 
> indicating the authorization servers endpoint, e.g.
>

---

From: John Kemp <[email-masked]>
Date: Sun, 4 Apr 2010 17:34:12 -0400

Hi Eran,

> WWW-Authenticate: OAuth realm='example'

From RFC 2617 (http://www.ietf.org/rfc/rfc2617.txt):

"The realm value (case-sensitive), in combination with the canonical root URL (the
absoluteURI for the server whose abs_path is empty; see section 5.1.2
of [2]) of the server being accessed, defines the protection space.
These realms allow the protected resources on a server to be
partitioned into a set of protection spaces, each with its own
authentication scheme and/or authorization database. The realm value
is a string, generally assigned by the origin server, which may have
additional semantics specific to the authentication scheme. Note that
there may be multiple challenges with the same auth-scheme but
different realms."

and:

realm
A string to be displayed to users so they know which username and
password to use. This string should contain at least the name of
the host performing the authentication and might additionally
indicate the collection of users who might have access. An example
might be "[email-masked]".

Leading me to conclude:

i) Realm is supposed to contain a hint for users as to which username/password to use (ie. a client cannot by default assume it to be machine-readable)
ii) The "protection space" defined by a realm may be as small as one resource, or as big as an entire site. RFC2617 tells clients what they can assume if they receive a challenge:

"A client SHOULD assume that all paths at or deeper than the depth of
the last symbolic element in the path field of the Request-URI also
are within the protection space specified by the Basic realm value of
the current challenge. A client MAY preemptively send the
corresponding Authorization header with requests for resources in
that space without receipt of another challenge from the server."

> the 401 response in a standard way.

I think that RFC2617 realms are similar in concept to the 'scope' you're looking for, but have some differences in use for the HTTP basic/digest protocol. In order to be sure you don't confuse clients which already know HTTP Basic/Digest, you may want to place some further restrictions on the values that can be in the realm parameter when a WWW-Authenticate challenge is issued (it's just a string in RFC2617). If a client receives an OAuth WWW-Authenticate challenge, I would assume that OAuth should anyway tell the client whether/what to present the user in order to have the client get an appropriate token to access the protected resource.

Some care is needed to specify this in a way that is compatible with the expected behaviour of user agents already familiar with RFC2617.

Regards,

- johnk

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 6 Apr 2010 00:13:39 -0700

Yep. I'm trying to remove the need for a more complex discovery.

EHL

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 6 Apr 2010 00:16:29 -0700

> of access. realm != scope

No. Realm is a subset. It is what people define as the protected segment
name. For any other scope attribute we need to first define it.

EHL

---

From: Brian Eaton <[email-masked]>
Date: Tue, 6 Apr 2010 00:37:50 -0700

> Yep. I'm trying to remove the need for a more complex discovery.

Not sure we need to do anything, discovery is pretty simple already.

We've been talking a bit about how to enable OAuth for IMAP:
http://tech.groups.yahoo.com/group/sasl_oauth/.

Here's the rough flow:
1) The hostname of the IMAP server to talk to magically appears.
Maybe the user enters it.
2) Client queries the IMAP server.
3) IMAP server points at the OAuth WRAP endpoints.
4) Client opens a browser to get user approval using the rich client flow.
5) Client saves the refresh token instead of the user's password.

Ideally the same SASL mechanism would work for XMPP.

Cheers,
Brian

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 6 Apr 2010 00:47:31 -0700

That's the same as what I have in the draft, only with a single endpoint instead of two. Since we already have a 'mode' parameter (which I am renaming to 'type'), that single endpoint can speak more than one flow.

EHL

On 4/6/10 12:37 AM, "Brian Eaton" <[email-masked]> wrote:

Here's the rough flow:

Cheers,
Brian

---

From: Brian Eaton <[email-masked]>
Date: Tue, 6 Apr 2010 00:58:07 -0700

On Tue, Apr 6, 2010 at 12:47 AM, Eran Hammer-Lahav <[email-masked]> wrote:
> That’s the same as what I have in the draft, only with a single endpoint
> instead of two. Since we already have a ‘mode’ parameter (which I am
> renaming to ‘type’), that single endpoint can speak more than one flow.

Note that the discovery flow I outlined only works for rich clients,
and is completely insecure for other types of clients.

In another thread Leif mentioned similar concerns.  I think they are justified.

Cheers,
Brian

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 6 Apr 2010 01:23:50 -0700

Why?

On 4/6/10 12:58 AM, "Brian Eaton" <[email-masked]> wrote:

On Tue, Apr 6, 2010 at 12:47 AM, Eran Hammer-Lahav <[email-masked]> wrote:
> That's the same as what I have in the draft, only with a single endpoint
> instead of two. Since we already have a 'mode' parameter (which I am
> renaming to 'type'), that single endpoint can speak more than one flow.

Cheers,
Brian

---

From: Brian Eaton <[email-masked]>
Date: Tue, 6 Apr 2010 06:58:59 -0700

Web clients are expected to have secrets or to have otherwise
registered with the AS.  In order for them to use those secrets, they
need to know the AS URL.

Cheers,
Brian

---

From: Dick Hardt <[email-masked]>
Date: Tue, 6 Apr 2010 08:03:41 -0700

On 2010-04-06, at 12:16 AM, Eran Hammer-Lahav wrote:

> name.

 Different Protected Resources could require the same scope, so I see realm and scope as being orthogonal.

> For any other scope attribute we need to first define it.

Why? Scope will often be application specific.

---

From: Luke Shepard <[email-masked]>
Date: Tue, 6 Apr 2010 08:29:30 -0700

For Facebook at least, we are currently planning to use scope as a comma-separated list of permissions from this set: http://wiki.developers.facebook.com/index.php/Extended_permissions

For instance:

	oauth_scope=read_stream,email,photo_upload

I'm not sure if that maps to realm exactly.

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 6 Apr 2010 14:41:06 -0700

RFC 2617 defines what a realm is - a set of resources sharing the same set
of credentials. It saves the client the need to prompt the user again for
their credentials when browsing a site across resources. Because sending
credentials to the wrong place is dangerous, realms are hard to use because
the client must take into account more than just the same realm but also the
domain name, etc.

Most of the example people gave for their use of scope where in practice a
segment ('photos', 'contacts', etc.). Usually each of these groups use
different APIs (a single API call that can bring both a photo and contact,
but only a photo if using a limited token without contact access, is rare).

This is why I suggested using realm as a well defined subset of what people
here refer to as 'scope'.

I don't like the idea of defining a parameter that requires internal
structure as opaque and leaving it up to the individual services to define.
This doesn't help interop. If you have to define the structure of the scope
parameter, you might as well define the parameter as well.

The argument that having a consistent parameter with an opaque value help
libraries is silly. Good libraries will pass along any custom parameters
they found to the higher level. This adds nothing but is likely to cause
problems when people code libraries with scope structure specific to one
company. It will also cause confusion when two scopes mean completely
different things across services.

EHL

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 6 Apr 2010 14:42:50 -0700

The question is how your APIs are structure. Do you have APIs that require multiple "scopes" in a single call?

EHL

On 4/6/10 8:29 AM, "Luke Shepard" <[email-masked]> wrote:

For instance:

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 6 Apr 2010 14:50:19 -0700

That's only when you need to trust the client. If your requirements demand registration, discovery is mostly pointless (other than dynamic configuration).

EHL

On 4/6/10 6:58 AM, "Brian Eaton" <[email-masked]> wrote:

Cheers,
Brian

---

From: Marius Scurtescu <[email-masked]>
Date: Tue, 6 Apr 2010 14:57:57 -0700

On Tue, Apr 6, 2010 at 2:42 PM, Eran Hammer-Lahav <[email-masked]> wrote:
> The question is how your APIs are structure. Do you have APIs that require
> multiple “scopes” in a single call?

Things can get even more complicated. When the user grants access for
the client, the approval page should list all the scopes the client is
requesting. This is the set of scopes needed by the client for *all*
the API calls. Each API will need a subset of this approved, larger
set.

With that in mind, it would be useful to be able to down-scope access
tokens when using the refresh token, this way the client can send the
smallest set of scopes with each API call.

But again, for all the above, the client must have intimate knowledge
of the APIs (aka protected resources) and what scopes are required,
the OAuth 2.0 libraries used by the client can treat the scopes as
opaque strings IMO.

Marius

> For Facebook at least, we are currently planning to use scope as a
> comma-separated list of permissions from this set:
> http://wiki.developers.facebook.com/index.php/Extended_permissions
>
> For instance:
>
>>>> There are times when a resource may have different scope for different
>>>> kinds
>>>> of access. realm != scope
>>>

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 6 Apr 2010 15:12:31 -0700

I am still waiting for someone to show how a scope parameter with an opaque value helps interop, where every single example requires the client to know how to construct this opaque string. OAuth libraries will need to support extension parameters - that's a given. So how is this not an extension if you will have to document how to use it in your own API spec?

If I want to ask for both a set of resources (photos, contact), access rights (read, write), and a specific duration (3 days), should I put all this into the scope parameter? Put some in and some in another parameter?

Help me write a definition that helps people understand exactly when and how they should use this parameter. How are you going to use it?

EHL

On 4/6/10 2:57 PM, "Marius Scurtescu" <[email-masked]> wrote:

On Tue, Apr 6, 2010 at 2:42 PM, Eran Hammer-Lahav <[email-masked]> wrote:
> multiple "scopes" in a single call?

Marius

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 6 Apr 2010 15:17:41 -0700

Thanks John.

I tend to agree that realm comes with a lot of baggage and is probably not going to work given people's expectations. After all, they are not likely to study 2617 before implementing OAuth.

The point of my proposal was to show one aspect of scope in which the client is being told what kind of access it should ask for. The client treats this as an opaque string, and it remains the an opaque string (i.e. No higher level handling by the client). In this scenario, if the client has an access token for "photos,contact", it will not use it for "contact,photos".

There seems to be high demand for scope parameter support, but very little actual use cases (provided).

EHL

On 4/4/10 2:34 PM, "John Kemp" <[email-masked]> wrote:

Hi Eran,

and:

realm

Leading me to conclude:

Regards,

- johnk

---

From: Marius Scurtescu <[email-masked]>
Date: Tue, 6 Apr 2010 15:28:06 -0700

On Tue, Apr 6, 2010 at 3:12 PM, Eran Hammer-Lahav <[email-masked]> wrote:
> I am still waiting for someone to show how a scope parameter with an opaque
> value helps interop, where every single example requires the client to know
> how to construct this opaque string. OAuth libraries will need to support
> extension parameters – that’s a given. So how is this not an extension if
> you will have to document how to use it in your own API spec?

You are probably right, an opaque scope does not help interop. I think
the reason the scope parameter was added to wrap is that in practice
with OAuth most implementations ended up needing such a parameter.
Having a standard one prevents everyone from (re)inventing a custom
parameter. Beyond that, I don't see any benefits.

> If I want to ask for both a set of resources (photos, contact), access
> rights (read, write), and a specific duration (3 days), should I put all
> this into the scope parameter? Put some in and some in another parameter?

Set of resources and access rights probably go together in a scope.
Not so sure about duration, until now duration was considered
unlimited, Authz Servers probably allow users to revoke access at any
time (this would revoke the corresponding refresh token and any
auto-approvals).

> Help me write a definition that helps people understand exactly when and how
> they should use this parameter. How are you going to use it?

I think the vague definition from the wrap spec was good enough: "The
Authorization Server MAY define authorization scope values for the
Client to include"

Marius

>>> Different Protected Resources could require the same scope, so I see
>>> realm
>>> and scope as being orthogonal.
>>>

---

From: Igor Faynberg <[email-masked]>
Date: Wed, 07 Apr 2010 00:16:39 -0400

Yes, if we go with RFC 2617, then--and please correct me if I am 
wrong--it looks to me that *realm* here means pretty much the same thing 
as *Kerberos realm*. I strongly agree on getting the definition clear, 
and I agree that nothing should be "opaque."

(I as puzzled by the quoted exchange, and I decided that I am simply 
ignorant about the terminology and should wait until it is clarified. In 
this group there is a good mix of people with different backgrounds, and 
so sorting out the terminology seems to be the most important thing to 
accomplish.)

Igor

---

From: Igor Faynberg <[email-masked]>
Date: Wed, 07 Apr 2010 00:31:36 -0400

I've been reading this with much interest, but I am getting hopelessly 
lost because of the usage of the word API.  Somehow, to me -- for many 
years--it meant the format of procedure calls, or, more general, 
procedure signatures in standard libraries.

I remember David at the last meeting clarified to me that by "API" he 
meant HTTP headers.  I don't mind broadening the term, but do we have a 
definition for it?

Igor

---

From: Leif Johansson <[email-masked]>
Date: Wed, 07 Apr 2010 09:20:25 +0200

> That's only when you need to trust the client. If your requirements demand registration, discovery is mostly pointless (other than dynamic configuration).

At the risk of comparing apples and pears - many large-scale SAML 
deployments rely on discovery even though the domain of discoverable
entities is provided by a registry. It isn't pointless :-)

	Cheers Leif