Re: [OAUTH-WG] Indicating sites where a token is valid

[Eran Hammer-Lahav <[e-mail]>]

You are trying to match a mechanism designed for automatic discovery with a system designed to require paperwork. It sounds like for your use cases, you will not be using this optional parameter and just document how to use your API (i.e. hardcode your security setup and API format).

The whole point of this is that the developer isn't involved. The library takes care of everything. All the developer does is ask to get a protected resource. The library will check if it already has a valid token for that resource (based on the security restrictions provided by the sites parameter, and the scope requirements - two very separate things).

So yes - if your developers have plenty of stuff to hardcode already, this adds little value.

EHL

From: [e-mail] [mailto:[e-mail]] On Behalf Of Evan Gilbert
Sent: Thursday, May 13, 2010 9:00 AM
To: Manger, James H
Cc: OAuth WG
Subject: Re: [OAUTH-WG] Indicating sites where a token is valid


On Wed, May 12, 2010 at 11:52 PM, Manger, James H <[e-mail]<mailto:[e-mail]>> wrote:
Evan,

> The key point is that this discovery covers a lot of the same grounds as the sites parameter, and it's hard  to define semantics around a sites parameter without understanding the semantics of scopes and API endpoints.
I strongly disagree. The semantics are crystal clear:
 "Here is a token. It is INSECURE to send it anywhere not in this list."
These semantics are useful regardless of what the API does, how the client is using it, or how much (or how little) the client knows about the API.

To expand - it's hard to define *useful* semantics around a sites parameter without understanding the semantics of scopes and API endpoints. Yes, you can define crystal clear semantics, but these are not useful unless they work well with the way developers figure out the endpoints to call APIs.



> Clients need to [know] more about these links (at least the response format).

That knowledge comes from other standards (HTML, Atom, wiki of rel values...) and is totally independent of whether a token should or should not be sent.

In our use cases, clients almost always need to know more about the API:
- How to call directly - we have no API endpoints that are only arrived at by links
- Response format of the data



> The mechanism they use to find out about these links - documentation, discovery, data returned with token request - could also provide the information about whether a token should be sent to a particular API.
Could, but shouldn't and doesn't in practise.
It is much much better to have the information about how to use a token securely delivered at the same time & place as receiving that token, and with minimal assumptions about how much the client apps knows about the service.

So why wouldn't we return a list of specific API endpoints instead of a "sites" parameter?

Developers are going to call the APIs endpoints that they know about. If there is a conflict between this and the sites parameter, what should they do? For example, if facebook returns a sites parameter "https://unknown.facebook.com/", do we think the developer is going to not try to use the access token on https://graph.facebook.com/<https://graph.facebook.com/*> ?

Separating the concept of sites from API endpoints feels like a bad idea. Discovery / docs will give you a list of URLs where you should send tokens. The "sites" parameter will give you a list of URLs where you can send tokens. This is redundant, and will lead to developers / libraries not respecting the sites parameter. If developers / libraries don't respect it, then the service can't rely on it for enforcing security.

Another note: Where do we anticipate clients storing the sites parameter in the User-Agent flow? Right now the access token can be set as an HTTP cookie by the client. Do we expect them to set a separate "sites" cookie and respect this on their server when making requests? This seems complicated.



> I should be more concrete about the use cases I see. Let's assume there's an API where there are two endpoints, each with an associated permission
> - contacts.list permission -> http://contacts.serviceprovider.com/contacts/list
> - calendar.get permission -> http://calendar.serviceprovider.com/calendar/get
>
> If the response to an authorization request includes the authorized scopes (contacts.list, calendar.get), then the "sites" parameter is redundant.
I'll admit that "sites" is redundant if a client has *perfect* knowledge about a service, but so is pretty much any standard at that point.

Consider a generic search spider tool that you point at http://calendar.serviceprovider.com/calendar/get. It can do its job with no knowledge about what "calendar.get" means -- but it still needs to know (as it spiders along) when it is safe to expose the token.

How does the generic search spider know to call to http://calendar.serviceprovider.com/calendar/get in the first place?



--
James Manger