spec proposal: gadget XML changes for OAuth
Brian Eaton
gadget XML file. Configuration could theoretically be done with
<Require feature> elements, but this is awkward and works only for a
single service provider. We should have a new <OAuth> element in the
XML spec. Gadgets that want to use OAuth would use this element to
declare their OAuth related configuration information.
The simplest possible OAuth element declares that a gadget will use
OAuth with a service provider that supports OAuth discovery:
<ModulePrefs>
<OAuth>
<Service />
</OAuth>
</ModulePrefs>
OAuth discovery is new, and not many service providers support it yet.
The simplest possible OAuth element for a service provider that does
not support OAuth discovery declares three URLs used during the OAuth
protocol. Several reasonable defaults are assumed for some of the
OAuth protocol details.
<ModulePrefs>
<OAuth>
<Service>
<Request url="http://www.example.com/request"/>
<Authorization url="http://www.example.com/authorize"/>
<Access url="http://www.example.com/access"/>
</Service>
</OAuth>
</ModulePrefs>
The most complex OAuth element declares that the gadget will access
data from multiple OAuth service providers, and declares URLs and
several OAuth protocol details for all of them.
<OAuth>
<Service name="serviceOne">
<Request url="http://www.example.com/request"
method="GET"
param_location="header" />
<Authorization url="http://www.example.com/authorize"
method="GET"
param_location="header" />
<Access url="http://www.example.com/access"
method="GET"
param_location="header" />
</Service>
<Service name="serviceTwo">
<Request url="http://other.example.com/request"
method="GET"
param_location="header" />
<Authorization url="http://other.example.com/authorize"
method="GET"
param_location="header" />
<Access url="http://other.example.com/access"
method="GET"
param_location="header" />
</Service>
</OAuth>
OK, now that there are some examples to show how things ought to look,
let's get normative:
The <ModulePrefs> element can contain 0 or 1 <OAuth> elements.
The <OAuth> element can contain 1 or more <Service> elements.
The <Service> element has a single attribute:
name [optional]. This is a nickname the gadget will use to
reference the service provider. If unspecified, it defaults to "".
The <Service> element contains three elements, a <Request> element, an
<Authorization> element, and an <Access> element.
The <Request> element has three attributes.
url [required]: the absolute URL of the service provider request endpoint.
method [optional]: the HTTP method to use to access the
endpoint. May be GET or POST. If unspecifed, defaults to "GET".
param_location [optional]: the location of the OAuth parameters
in the request. May be "url", "header", or "body". If unspecified,
defaults to "header".
The <Access> element is identical to the <Request> element, but
describes an access token URL instead of a request token URL.
The <Authorization> element has a single attribute:
url [required]: the authorization URL for the service provider.
Bob Ngu
providers, Pownce for example, requires a consumer application to
register first to get the consumer credentials.
fer...@gmail.com
container our app will be hosted in?
Brian Eaton
> I'm confused, would we have to include a OAuth stanza for each
> container our app will be hosted in?
No, you would need to include an OAuth stanza for each service
provider whose data your gadget wants to access.
Example:
Gadget G hosted on container C1 wants to access user data on service provider S.
Gadget G should:
- include an OAuth stanza describing the OAuth interface provided by S.
- obtain a consumer key and secret from S.
- notify C1 about the consumer key and secret for the gadget.
If gadget G wants to run on container C2, the same consumer key and
secret might be usable, or perhaps a separate API key is necessary.
That's up to the gadget author and the service provider. The same
OAuth stanza should work in all containers that support OAuth.
Brian Eaton
> Question, how much can OAuth discovery be automated if OAuth service
> providers, Pownce for example, requires a consumer application to
> register first to get the consumer credentials.
Some bits can be automated very well, such as figuring out the OAuth
endpoints. That's grunt work for gadget authors, and OAuth discovery
will make that problem go away.
Registering consumer keys is interesting, it has more to do with
business than technology at this point. It's my hope that service
providers will make registering for consumer keys an automatic
process. If that doesn't happen, then either containers or gadget
authors are going to have to go through the manual registration
process. Legal issues, like agreeing to TOS, need to be addressed.
Containers need to tell gadget authors how to associate consumer keys
and secrets with their applications.
I put together a proposal that would allow a consumer and service
provider to automate registration. The consumer would verify that
they own a particular URL, and then the service provider would issue a
consumer key to that URL. That could be a good fit for gadgets and
OAuth.
Cheers,
Brian
fer...@gmail.com
understand what you're proposing and or what you are trying to solve.
So maybe I came late to the discussion, but all I see is that you're
proposing adding more information to the gadget xml. But who will use
that information and for what?
Are you trying to offload some oauth related work to the container?
What work?
Are you saying that the container would somehow be an oauth bridge for
gadgets?
Is that a good idea?
Why would an app trust a container enough to let it impersonate the
gadget?
( brain-twister: It sounds like you should start getting into
recursive oauth privilege forwarding.. user gives container access to
account using oauth, gadget gives container rights to act on its
behalf through oauth using oauth, thus user gives gadget access to
account using container's oauth then gadget's oauth?? )
On Apr 19, 10:16 pm, "Brian Eaton" <bea...@google.com> wrote:
Bob Ngu
> Registering consumer keys is interesting, it has more to do with
> business than technology at this point. It's my hope that service
> providers will make registering for consumer keys an automatic
> process. If that doesn't happen, then either containers or gadget
> authors are going to have to go through the manual registration
> process. Legal issues, like agreeing to TOS, need to be addressed.
> Containers need to tell gadget authors how to associate consumer keys
> and secrets with their applications.
problem. My understanding is that the OAuth protocol does not specify
how this get done, just that it is done leaving it up to the service
provider to decide how to implement it. Near as I can tell, it seems
to be standard practice for service providers to require consumer apps
to register manually. My point or maybe confusion rather is that this
manual registration step presents a serious kink in the discovery
process to automate usage of the OAuth service. But even if the
consumer registration is automated, doesn't the consumer app need to
have prior knowledge of what is available from the service provider to
write code and make use of the service providers APIs? This is yet
another manual step again rendering the discovery process moot because
the end goal is not achievable without these manual steps. Sorry if my
questions are off the mark, I am new to OAuth, discovery, etc and
trying to understand the end-to-end process better.
>
> I put together a proposal that would allow a consumer and service
> provider to automate registration. The consumer would verify that
> they own a particular URL, and then the service provider would issue a
> consumer key to that URL. That could be a good fit for gadgets and
> OAuth.
>
> Cheers,
> Brian
Brian Eaton
>
> Alright, then maybe my questions are off-topic, but I still don't
> understand what you're proposing and or what you are trying to solve.
I don't think your questions are off-topic at all. The problem I am
trying to solve is this one:
- user has an account at some service provider.
- they also have an account at some social networking site.
- how can they see their data from the service provider on the SNS?
There have been several answers to that question in the past (BBAuth,
AuthSub, others...). OAuth is an attempt to standardize those
protocols so that developers don't need to learn a new protocol every
time they integrate with a new service provider.
The problem with gadgets and OAuth is that gadgets don't know much
about who the user is without container support, and gadgets have no
way of keeping long-lived secrets (like the consumer key and secret,
or the access token and secret) out of browsers. One way to fix that
is container support for OAuth, where the gadget server stores the
OAuth secrets and carries out the OAuth protocol on behalf of the
gadget. That's the goal of my proposals.
> So maybe I came late to the discussion, but all I see is that you're
> proposing adding more information to the gadget xml. But who will use
> that information and for what?
The gadget server will use the information run the OAuth protocol on
behalf of the gadget.
> Are you trying to offload some oauth related work to the container?
> What work?
Most of the work. The gadget developer needs to
a) register a consumer key and secret, and tell the container about that secret.
b) understand the semantics of the service provider APIs.
c) direct the user to the service provider approval page at the
appropriate time.
The gadget developer should *not* need to know the details of the
OAuth protocol.
> Are you saying that the container would somehow be an oauth bridge for
> gadgets?
> Is that a good idea?
Yes, and yes. =)
> Why would an app trust a container enough to let it impersonate the
> gadget?
The gadget already has to trust the container completely, since the
container does all of the work to authenticate users, render the
gadget, and handle requests from the gadget. They are joined at the
hip. There's no way to implement OAuth in pure client-side code with
any degree of security or usability, there has to be server-side
support.
Cheers,
Brian
Brian Eaton
> My point or maybe confusion rather is that this
> manual registration step presents a serious kink in the discovery
> process to automate usage of the OAuth service.
Yes, it does. Service providers need to make this easy if they want
third-parties to write apps that use their APIs. If a service
provider wants to restrict access to their APIs, they can certainly do
that.
> But even if the
> consumer registration is automated, doesn't the consumer app need to
> have prior knowledge of what is available from the service provider to
> write code and make use of the service providers APIs?
Service providers provide APIs, and gadget developers will write to
those APIs. The gadget developer has to know what those APIs can do,
how else are they going to write a cool application on top of them?
My goal is to prevent gadget developers from needing to learn OAuth.
Learning the service provider APIs is enough of a challenge.
> Where is your proposal for automating registration?
http://groups.google.com/group/oauth-extensions/browse_thread/thread/bdd87bc7de25867c
Cheers,
Brian
fer...@gmail.com
Though, this is for the use case where the gadget is fully client-
side. Though I guess you could argue that for most gadgets worth
their weight, it will be heavy weight and backed by a server..
maybe? :) :) And any gadget that has a backend server probably is
already using the OS REST api ( yet to come ) and OAuth, so they
already know OAuth. :)
But then again, having the container maintain oauth credentials for
the user and third parties in a central place, might be beneficial for
the users. :)
(you could expose this oauth bridge through the REST api as well!! )
On Apr 20, 6:05 pm, "Brian Eaton" <bea...@google.com> wrote:
Brian Eaton
>
> I see. Thank you, definitely much clearer. :)
OK, good. Feel free to say so when I stop making sense, it happens on occasion.
> Though, this is for the use case where the gadget is fully client-
> side. Though I guess you could argue that for most gadgets worth
> their weight, it will be heavy weight and backed by a server..
> maybe? :) :)
I hope the OAuth proxy makes it so easy to write fully client-side
gadgets that this isn't true.
> (you could expose this oauth bridge through the REST api as well!! )
Whoops, my brain just melted. Please bring this up again once the
REST apis have matured, maybe I'll get it then. =)
Bob Ngu
> third-parties to write apps that use their APIs. If a service
> provider wants to restrict access to their APIs, they can certainly do
> that.
list, etc requires restricted access, that's why OAuth and other
similar protocols were created. Since the OAuth protocol doesn't
specify how this consumer key is handled, it's up to each service
provider to implement their own mechanism thereby seriously limiting
the standard protocol format unless a mechanism like what you proposed
get implemented, is it?
> Service providers provide APIs, and gadget developers will write to
> those APIs. The gadget developer has to know what those APIs can do,
> how else are they going to write a cool application on top of them?
> My goal is to prevent gadget developers from needing to learn OAuth.
> Learning the service provider APIs is enough of a challenge.
>
OAuth is designed to grant access to any number of potential APIs
which require prior knowledge and development to make use of,
otherwise OAuth by itself isn't useful. I think the conclusion I am
coming to is that OAuth discovery is essentially not useful or
relevant in real world applications. OAuth protocol yes, OAuth
discovery, no. Does that make sense?
Cassie
http://groups.google.com/group/opensocial-and-gadgets-spec/browse_frm/thread/dfd67adb39f2af6a#
Thanks.
- Cassie
Brian Eaton
> Unfortunately the most useful bits of information like your contact
> list, etc requires restricted access, that's why OAuth and other
> similar protocols were created.
There's some confusion here, between seeking approval from the end
user and seeking approval from the service provider.
All OAuth flows are going to require end user approval at some point,
that's what the protocol is for.
Seeking approval from the service provider is a different story.
There is a huge range of options here. Some service providers will
issue consumer keys to anyone, some will require TOS, some will
require legal contracts, and some will never issue an API key to
anyone who doesn't actually work for them.
> Since the OAuth protocol doesn't
> specify how this consumer key is handled, it's up to each service
> provider to implement their own mechanism thereby seriously limiting
> the standard protocol format unless a mechanism like what you proposed
> get implemented, is it?
I disagree on this point. Registering for a consumer key is ad hoc.
Using that consumer key goes through a well defined protocol. This is
pretty much the norm for authentication protocols.
I'd love to see automated registration happen, but even if it doesn't
OAuth will still be useful. Witness BBAuth/AuthSub/etc, all widely
used, all using ad hoc consumer key registration.
> Unlike openID which only goal is to authenticate a person identity,
> OAuth is designed to grant access to any number of potential APIs
> which require prior knowledge and development to make use of,
> otherwise OAuth by itself isn't useful.
Yes, exactly.
> I think the conclusion I am
> coming to is that OAuth discovery is essentially not useful or
> relevant in real world applications. OAuth protocol yes, OAuth
> discovery, no. Does that make sense?
Not one bit, no. =) OAuth discovery will definitely simplify
configuration by removing the need for developers to cut and paste
URLs. OAuth discovery may end up simplifying consumer key
registration as well. The SAML metadata format was a big win in terms
of ease of configuration for SAML 2.0. I suspect OAuth discovery will
fill a similar gap.
Brian Eaton
Dirk Balfanz
The <Request> element has three attributes.
url [required]: the absolute URL of the service provider request endpoint.
method [optional]: the HTTP method to use to access the
endpoint. May be GET or POST. If unspecifed, defaults to "GET".
param_location [optional]: the location of the OAuth parameters
in the request. May be "url", "header", or "body". If unspecified,
defaults to "header".
To be more in line with the OAuth lingo used elsewhere (e.g. in the discovery spec) I propose to that the param_location attribute have the following possible values: "uri-query", "auth-header", and "post-body", with the default being "auth-header".
Dirk.
Brian Eaton
> To be more in line with the OAuth lingo used elsewhere (e.g. in the
> discovery spec) I propose to that the param_location attribute have the
> following possible values: "uri-query", "auth-header", and "post-body", with
> the default being "auth-header".
Sounds good to me.
Bob Ngu
> user and seeking approval from the service provider.
have here is a failure to communicate, my fault really =)
>
> All OAuth flows are going to require end user approval at some point,
> that's what the protocol is for.
>
> Seeking approval from the service provider is a different story.
> There is a huge range of options here. Some service providers will
> issue consumer keys to anyone, some will require TOS, some will
> require legal contracts, and some will never issue an API key to
> anyone who doesn't actually work for them.
>
example =) Say there are 2 service providers for openID, SPA ad SPB.
Once I implemented support for openID in my consumer app, it will work
with users who have openids from either SPA and SPB without any
registration, I understand that there is still a manual user step to
login. Let's say both SPA and SPB also decide to support OAuth. I
added OAuth support for SPA in my consumer app which includes a manual
app registration step and code for SPA APIs. If my app discovers a
user from SPA, my app can happily use OAuth to get information for
that user from SPA. However, if my app discovers a user from SPB, it's
a dead stop because my app currently isn't registered with SPB nor
does it have code to consume SPB APIs. Basically, this is what I mean
by OAuth discovery not being useful (perhaps the wrong term?) when it
comes to discovering users on service providers that I don't already
have OAuth support for, Does this make more sense now?
Brian Eaton
> Let me rephrase my question, hopefully more clearly this time with an
> example =) Say there are 2 service providers for openID, SPA ad SPB.
> Once I implemented support for openID in my consumer app, it will work
> with users who have openids from either SPA and SPB without any
> registration, I understand that there is still a manual user step to
> login. Let's say both SPA and SPB also decide to support OAuth. I
> added OAuth support for SPA in my consumer app which includes a manual
> app registration step and code for SPA APIs. If my app discovers a
> user from SPA, my app can happily use OAuth to get information for
> that user from SPA. However, if my app discovers a user from SPB, it's
> a dead stop because my app currently isn't registered with SPB nor
> does it have code to consume SPB APIs. Basically, this is what I mean
> by OAuth discovery not being useful (perhaps the wrong term?) when it
> comes to discovering users on service providers that I don't already
> have OAuth support for, Does this make more sense now?
Yah, all true. The only place we'll have to agree to disagree is on
whether or not OAuth discovery is useful. I have lower expectations
for OAuth discovery than you do, so I'm not disappointed with what it
offers. =)
Bob Ngu
be aware of the OAuth discovery limitations that I mentioned and to be
honest, I wasn't entirely sure either, that's why I asked. Thanks for
taking the time to answer my questions. Keep up the good work!
Dirk Balfanz
Martin Webb
Cassie
Bob and fernman, are you onboard as well? If so, please respond with +1 and this will be approved.
Thanks.
- Cassie
Bob Ngu
+1
On Apr 24, 8:47 am, Cassie <d...@google.com> wrote:
> Okay, so Dirk, Martin, Brian are +1
> Bob and fernman, are you onboard as well? If so, please respond with +1 and
> this will be approved.
>
> Thanks.
> - Cassie
>
>
> > Late entrance to the thread, but:
>
> > +1
>
> > On Mon, Apr 21, 2008 at 6:55 PM, Brian Eaton <bea...@google.com> wrote:
>
John Panzer
Cassie
Thanks.
- Cassie
John Hjelmstad
This change was approved, but somehow missed getting patched into the gadgets XSDs (http://code.google.com/p/opensocial-resources/source/browse/spec/0.8/gadgets/gadgets.xsd and http://code.google.com/p/opensocial-resources/source/browse/spec/0.8/gadgets/gadgets-extended.xsd).
The attached patch provides these edits (while fixing the typo made in gadgets.xsd: <xs attribute... -> <xs:attribute...). If you (anyone) would like to take a look at it for review, it would be much appreciated.
Thanks,
John
Arne Roomann-Kurrik
If anyone sees any more issues, I'm happy to update as needed.
~Arne
OpenSocial IRC - irc://irc.freenode.net/opensocial
Singpolyma
> Question, how much can OAuth discovery be automated if OAuth service
> providers, Pownce for example, requires a consumer application to
> register first to get the consumer credentials.
they offer a consumer key to be discovered (which *is* part of the
discovery spec).