Subject: [OAUTH-WG] Combining the Native application and User-agent flows

From: Luke Shepard <[email-masked]>
Date: Tue, 13 Apr 2010 13:35:57 -0700

In the latest draft of the OAuth 2.0 spec, there are four "User Delegation" flows:

3.4.1   Web Callback Flow
3.4.2   Native Application Flow
3.4.3   User-Agent Flow
3.4.4   Device Flow

The Native Application and the User-Agent flows should be combined into one flow. The combined flow works for all client-side code. This is how it was in David's original draft; I'd love some help understanding why it was separated again.

>From the draft:

The native flow is intended for desktop applications where "the client is capable of interacting with the end user's user-agent but is incapable of receiving callback requests from the server (incapable of acting as an HTTP server) ... instead of using a callback to deliver the verification code to the client, the authorization server displays the verification code to the end user via its user-agent.  If the client is able to interact with the user-agent, it retrieves the verification code automatically.  Otherwise, the end user manually enters the verification code into a client dialog."

So the flow is:

1/ User goes to oauth/authorize endpoint.
2/ Server displays a page that says something like "We are done here" and puts a code in the title.
3/ Desktop app makes a call to exchange the code for an access token, and closes the window.
4/ App uses access token.

A simpler flow, which works for Desktop as well as Javascript apps, is:

1/ User goes to oauth/authorize endpoint.
2/ Server authorizes, then redirects to the callback url .. something like about:blank#access_token=blahblahblah
3/ App uses access token.

At Facebook we have a lot of experience integrating with desktop apps. (i.e., Facebook for Adobe Air, Seesmic, Tweetdeck, iPhoto). In my experience, none of the desktop apps like to show a code that the user then enters into the app. Instead, apps typically receive the session (access token) directly in the response url. They can either use a URL on their domain, or a fake URL like about:blank, or an endpoint provided by Facebook (/connect/login_success.html). More info: http://wiki.developers.facebook.com/index.php/Authorization_and_Authentication_for_Desktop_Applications

The access token never goes over the wire (it's in the fragment even if the url is legit) and the desktop app gets a more well-formatted response.

I just don't get the point of the hacky code-in-html style. Can someone point me to a place where this is in widespread use today?

---

From: Luke Shepard <[email-masked]>
Date: Wed, 14 Apr 2010 07:44:00 -0700

Anyone have feedback on this?

Sorry to push - we are in the midst of implementing this on a short timeline and it's important that we have clarity about the different flows. As it currently stands, I would not support the "Native Application Flow" and would instead tell desktop developers to use the "User-Agent Flow". But that is confusing and it would obviously be better if the flows were named correctly.

Can someone persuade me otherwise?

From: [email-masked] [mailto:[email-masked]] On Behalf Of Luke Shepard
Sent: Tuesday, April 13, 2010 1:36 PM
To: OAuth WG
Subject: [OAUTH-WG] Combining the Native application and User-agent flows

3.4.1   Web Callback Flow

So the flow is:

---

From: Chuck Mortimore <[email-masked]>
Date: Wed, 14 Apr 2010 10:00:52 -0700

+1, at least for changing the wording of the current flows to deal with Native applications capable of various callback mechanisms.

That's the gist of this thread: http://www.ietf.org/mail-archive/web/oauth/current/msg01779.html

-cmort

On 4/14/10 7:44 AM, "Luke Shepard" <[email-masked]> wrote:

3.4.1   Web Callback Flow

So the flow is:

---

From: Marius Scurtescu <[email-masked]>
Date: Wed, 14 Apr 2010 13:59:58 -0700

> Anyone have feedback on this?

I can see several problems with using the User-Agent flow for native
applications:

1. A verification code is much simpler to copy-and-paste (as opposed
to access token + refresh token + lifetime). At the extreme, the
verification code can be memorized and typed, this is impossible with
the tokens.

2. Not in all cases a native application can intercept a token sent
back to some callback URL. The native app could be a command line tool
on a headless server, for example. Or, the user's default browser
window does not show a custom title.

3. While it is feasible to extract a short verification code from a
window title, that may not be possible with a long access token (it
can end up truncated). Not to mention refresh token and lifetime.

4. Just redirecting to "about:blank#access_token=blahblahblah" is not
reliable IMO. Try this in Firefox, nothing in the title. Same thing in
Chrome will show the token in the title. I think the callback must
render a proper HTML page with the proper <title>

5. Not clear that the User-Agent flow is safe enough to send back a
refresh token. Was that decided?

Marius

The typical solution is for the native app to launch a browser and
then watch that process and look for
>
>
>
> Sorry to push – we are in the midst of implementing this on a short timeline
> and it’s important that we have clarity about the different flows. As it
> currently stands, I would not support the “Native Application Flow” and
> would instead tell desktop developers to use the “User-Agent Flow”. But that
> is confusing and it would obviously be better if the flows were named
> correctly.
>
>
>
> In the latest draft of the OAuth 2.0 spec, there are four “User Delegation”
> flows:
>
>
>
> 3.4.1   Web Callback Flow
>
> The Native Application and the User-Agent flows should be combined into one
> flow. The combined flow works for all client-side code. This is how it was
> in David’s original draft; I’d love some help understanding why it was
> separated again.
>
>
>
> From the draft:
>
>
>
> The native flow is intended for desktop applications where “the client is
> capable of interacting with the end user's user-agent but is incapable of
> receiving callback requests from the server (incapable of acting as an HTTP
> server) ... instead of using a callback to deliver the verification code to
> the client, the authorization server displays the verification code to the
> end user via its user-agent.  If the client is able to interact with the
> user-agent, it retrieves the verification code automatically.  Otherwise,
> the end user manually enters the verification code into a client dialog.”
>
>
>
> So the flow is:
>
>
>
> 2/ Server displays a page that says something like “We are done here” and
> puts a code in the title.
>
> At Facebook we have a lot of experience integrating with desktop apps.
> (i.e., Facebook for Adobe Air, Seesmic, Tweetdeck, iPhoto). In my
> experience, none of the desktop apps like to show a code that the user then
> enters into the app. Instead, apps typically receive the session (access
> token) directly in the response url. They can either use a URL on their
> domain, or a fake URL like about:blank, or an endpoint provided by Facebook
> (/connect/login_success.html). More info:
> http://wiki.developers.facebook.com/index.php/Authorization_and_Authentication_for_Desktop_Applications
>
>
>
> The access token never goes over the wire (it’s in the fragment even if the
> url is legit) and the desktop app gets a more well-formatted response.
>
>
>
> I just don’t get the point of the hacky code-in-html style. Can someone
> point me to a place where this is in widespread use today?
>
>
>
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth
>
>

---

From: Chuck Mortimore <[email-masked]>
Date: Wed, 14 Apr 2010 14:19:12 -0700

As far as 2,3, and 4, the window title approach is really irrelevant.    Instead, the client will either directly handle callbacks through a custom scheme, or be able to recognize when a known callback URL has been loaded, and hence can extract the fragment from the URL directly.

I'm not sure it's cut-and-dry that the world will never need the copy-paste mechanism that Native Client flow supports, but from a usability perspective, we don't plan to deploy this and instead will be relying on callback techniques where ever possible.

-cmort

On 4/14/10 1:59 PM, "Marius Scurtescu" <[email-masked]> wrote:

Marius

>
>
>
> Sorry to push - we are in the midst of implementing this on a short timeline
> and it's important that we have clarity about the different flows. As it
> currently stands, I would not support the "Native Application Flow" and
> would instead tell desktop developers to use the "User-Agent Flow". But that
> in David's original draft; I'd love some help understanding why it was
> separated again.
>
>
>
> From the draft:
>
>
>
> The native flow is intended for desktop applications where "the client is
> the end user manually enters the verification code into a client dialog."
>
>
>
> So the flow is:
>
>
>
> The access token never goes over the wire (it's in the fragment even if the
> I just don't get the point of the hacky code-in-html style. Can someone

---

From: Marius Scurtescu <[email-masked]>
Date: Wed, 14 Apr 2010 15:01:58 -0700

On Wed, Apr 14, 2010 at 2:19 PM, Chuck Mortimore
<[email-masked]> wrote:
> As far as 2,3, and 4, the window title approach is really irrelevant.
>    Instead, the client will either directly handle callbacks through a
> custom scheme, or be able to recognize when a known callback URL has been
> loaded, and hence can extract the fragment from the URL directly.

This is a very strong limitation, only native apps that can register
and handle a custom scheme will work.

What do we get in return, just a slight simplification in the spec?

Assuming simplification is the main driver, I think it is feasible to
combine Web Callback and Native Application, with no penalty.

Marius

>
> I’m not sure it’s cut-and-dry that the world will never need the copy-paste
> mechanism that Native Client flow supports, but from a usability
> perspective, we don’t plan to deploy this and instead will be relying on
> callback techniques where ever possible.
>
> -cmort
>

---

From: Chuck Mortimore <[email-masked]>
Date: Wed, 14 Apr 2010 15:17:21 -0700

It's not limited to only apps that can register custom schemes, but I do agree it doesn't solve all scenarios.

My main concern is that the current language seems to preclude a number of highly usable callback based scenarios that are viable with Native apps in 2 ways.

 1.  the Web Callback flow explicitly assumes that the client is an HTTP server, and that it can protect a client_secret
 2.  the User-Agent flow explicitly assumes the client is in capable of receiving callbacks - this may or may not be true

I'd be happy with some language and guidance changes, so that Native clients that can receive callbacks through either custom schemes, existing non-http schemes, or hosted endpoints have a clear path for implementers.   The patterns are likely to emerge ontop of the spec anyways...they certainly did in Oauth 1.0

-cmort

On 4/14/10 3:01 PM, "Marius Scurtescu" <[email-masked]> wrote:

Marius

>
> I'm not sure it's cut-and-dry that the world will never need the copy-paste
> perspective, we don't plan to deploy this and instead will be relying on
>> In the latest draft of the OAuth 2.0 spec, there are four "User
>> Delegation"
>> flows:
>>
>>
>>
>> 3.4.1   Web Callback Flow
>>

---

From: Luke Shepard <[email-masked]>
Date: Wed, 14 Apr 2010 16:23:48 -0700

To get a verification code in the Native App scenario, the app either:

1/ Asks the user to copy/paste it.
2/ Retrieves it programmatically.

For 1/, I haven't seen a widely deployed desktop app use the copy/paste scenario. For apps that do want the user to copy/paste a code, we have designed the Device Flow just for that.

For 2/, from my conversations with desktop developers, it is easier to grab information from the URL than from the <title>. This is because you don't have to parse and understand the content. It's also easier to poll for changes in the URL (as results from a redirect) than to monitor the state of the entire page. I can dig up some source examples if that's helpful.

I'd like to ask the list again: has anyone deployed a desktop application, in the wild, that uses a protocol close to the one that's proposed in the Native Application flow? I've listed several apps below that use the flow I'm proposing; I'd really like to highlight specific examples for the other side.

-----Original Message-----
From: Marius Scurtescu [mailto:[email-masked]] 
Sent: Wednesday, April 14, 2010 3:02 PM
To: Chuck Mortimore
Cc: Luke Shepard; OAuth WG
Subject: Re: [OAUTH-WG] Combining the Native application and User-agent flows

Marius

---

From: Luke Shepard <[email-masked]>
Date: Wed, 14 Apr 2010 16:24:52 -0700

> combine Web Callback and Native Application, with no penalty.

How would that work? The Web Callback flow assumes the presence of a client_secret, while the Native Application does not have a secret.

---

From: Allen Tom <[email-masked]>
Date: Wed, 14 Apr 2010 17:06:46 -0700

As a security person, I'm hesitant to bring this up, but perhaps the Device
Flow should just be the flow for native client apps.

The main security argument against the Device Flow is that users are
vulnerable to the Oauth 1.0 Session Fixation attack, in which an attacker
gets an Authorization URL with the user_code prefilled, and then "phishes" a
victim to approve it.

The Flickr Uploadr is a native application that uses an auth flow that's
nearly identical to Oauth 1.0, and it does NOT use a verification code, and
it is susceptible to the session fixation issue.

http://www.flickr.com/tools/

The way Flickr deals with this issue is by designing their browser UX to
make it very clear to the user that they should only be seeing this flow if
they were trying to authorize the Flickr Uploadr desktop app. The user
should *not* be seeing the flow if they clicked on a link from IM, email,
twitter, or a web page.

Perhaps if we had a OAuth2 UX spec, we can standardize on best practices for
the AS approval page for flows which don't have a verification code.
Something similar to what Flickr is doing might be the best compromise.

For reference, I've attached a screenshot of the Flickr Uploader approval
screen. 

Allen

---

From: Marius Scurtescu <[email-masked]>
Date: Wed, 14 Apr 2010 17:21:29 -0700

> For 1/, I haven't seen a widely deployed desktop app use the copy/paste scenario. For apps that do want the user to copy/paste a code, we have designed the Device Flow just for that.

This forces the native app flow to rely on polling, and that makes it
vulnerable to session fixation, just like OAuth 1.0, but much worse,
because polling is a must in the flow.

> For 2/, from my conversations with desktop developers, it is easier to grab information from the URL than from the <title>. This is because you don't have to parse and understand the content. It's…

I agree that it is much nicer to parse a URL than messing with the
title, but not sure how can this be done. Are you suggestion custom
schemes? I don't think this is feasible in all cases. If you are
suggesting a helper web app that receives the callback and provides
the data to the client through some client/server call, then I think
we are back to the device flow.

> I'd like to ask the list again: has anyone deployed a desktop application, in the wild, that uses a protocol close to the one that's proposed in the Native Application flow? I've listed several app…

I will check here at Google and get back to the list on that.

Marius

---

From: Marius Scurtescu <[email-masked]>
Date: Wed, 14 Apr 2010 17:23:51 -0700

> How would that work? The Web Callback flow assumes the presence of a client_secret, while the Native Application does not have a secret.

The client_secret would have to be optional then. This may be needed
anyhow to support an "unregistered" Web Callback flow.

Also, the callback URL may need to be optional, because some native
apps cannot receive a callback. The Authz Server will have to show a
page with the verification code in this case.

Marius

---

From: Marius Scurtescu <[email-masked]>
Date: Wed, 14 Apr 2010 17:26:41 -0700

Yes, the device flow could be made to work, but isn't the current
native app flow more secure? Why fallback to this?

My guess is that most end users will not know what to make of all that
explanation and will just click one of the next buttons. But that's
just a wild guess (or fear).

Marius

---

From: Chuck Mortimore <[email-masked]>
Date: Wed, 14 Apr 2010 21:17:44 -0700

I believe this is basically how the draft-hardt-oauth-o1 Rich App profile worked.   It probably could have benefited from requiring that response parameters were returned behind a # fragments on callback URLs.   It also could use the callback URL on the access token request, and the refresh token should be optional, but besides that, I think it worked pretty well.   If the client could handle callbacks, they could use them...if not, it gracefully degraded to the native application flow.

-cmort

On 4/14/10 5:23 PM, "Marius Scurtescu" <[email-masked]> wrote:

Marius

---

From: Brian Eaton <[email-masked]>
Date: Wed, 14 Apr 2010 23:43:42 -0700

> in David’s original draft; I’d love some help understanding why it was

I'd like to see them separate.  I'm open to being convinced otherwise.

I've got two reasons for preferring that they be separate.

1) You can authenticate the client for user-agent flows.  You can't
for native-app flows.

You can authenticate client-side javascript by callback URL.  For
example, a token returned to http://www.example.com/javascript_widget
can be assumed to only be accessible to www.example.com.

This, in turn, let's you do interesting things policy wise: for
example, you can remember that a user has approved that js widget and
automatically give it new tokens as needed.

You can't do the same thing for native apps.  Even if they have a
callback URL, you can't know which application is going to receive
tokens issued to the callback URL.

2) User-Agent flows don't need persistent access to user data.

A JS widget doesn't need a refresh token that grants permanent access
to user data, and from a security perspective I'd prefer not to hand
out verification codes without good reasons.

A native-app, on the other hand, does need permanent access to user
data, and so does need a verification code.

Cheers,
Brian

---

From: Brian Eaton <[email-masked]>
Date: Wed, 14 Apr 2010 23:52:13 -0700

> Flow should just be the flow for native client apps.

I'm open to this.

I'd suggest differentiating between devices that can open a web
browser (native apps), and apps that can't open a browser
(refrigerators).

For refrigerators: you need a device code that is short enough to
type.  Because the code is short, an attacker could theoretically
brute force the code and link someone else's device to the attacker's
account.   See [2] for the math on how long the attack would take.

For native apps: the native app can open a web browser with the device
code on the URL.  The code can be very long and impossible to
brute-force.  The session fixation/phishing attack still exists, but I
agree that could be addressed with good UI.

[2] http://trac.tools.ietf.org/wg/oauth/trac/attachment/wiki/SecurityConsiderations/OAuth%20WRAP%202.0%20Security%20Considerations.pdf,
last two pages have the math on the device profile.  Marius has
pointed out that the device secret completely prevents one of the
attacks I was worried about.  But brute forcing the device code is
still a risk.

Cheers,
Brian

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 15 Apr 2010 05:52:33 -0700

> page with the verification code in this case.

At some point all these optional parameters make the flow useless because it
loses all interop value. It becomes a developer guide instead of a spec.

Unregistered clients should be solved by other means than just making the
secret parameter optional (i.e. Issue an anonymous client identifier and
fixed of blank secret). The secret value can be empty anyway (there is no
text requiring it to be something other than an empty string).

The callback URI is optional already if it was established via other means,
but the server MUST be able to accept this parameter (allowing the client to
drop it as a special case doesn't hurt interop).

EHL

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 15 Apr 2010 05:55:11 -0700

I worked off that text and the main issue with it is that it is just a developer guide, not a spec. Every implementation can be completely different. The proposed text is basically making some choices.

EHL

On 4/14/10 9:17 PM, "Chuck Mortimore" <[email-masked]> wrote:

-cmort

Marius

---

From: Mark Mcgloin <[email-masked]>
Date: Thu, 15 Apr 2010 14:53:31 +0100

> On 15/04/2010 07:52, Brian Eaton <[email-masked]> wrote:

>agree that could be addressed with good UI.

What is the benefit in combining Native flow and Device flow and then
having to expend effort preventing any ingenious phishing attacks?

Mark McGloin

---

From: Marius Scurtescu <[email-masked]>
Date: Thu, 15 Apr 2010 10:15:43 -0700

> having to expend effort preventing any ingenious phishing attacks?

The main issue with the Native flow is how is the client getting hold
of the verification code. There are several solutions for that
(embedded browser, custom scheme and handler app, launching browser
process and checking window title), but all are hackish.

The Device flow relies on the client polling the authz server and
retrieving the tokens directly. This closes the loop nicely.

Marius

---

From: Mark Mcgloin <[email-masked]>
Date: Fri, 16 Apr 2010 10:08:14 +0100

My point though is why remove the Native app flow and then replace it with
something that relies on having to warn the user about possible phishing
attacks in your UI, like FlickR does. I would find it difficult to get that
approved here in IBM

I must look again at Luke Sheppard's suggestion for combining Native app
flow with UA flow as that seems a better solution

Mark

---

From: Evan Gilbert <[email-masked]>
Date: Fri, 16 Apr 2010 18:00:41 -0700

A few of us from Google & Facebook had a face-to-face discussion today to
talk through the differences / similarities between Native App, Web
Callback, and User-Agent.

>From the discussion it seemed that the current Native Application flow is
equivalent to Web Callback flow, with:
1. A redirect to a endpoint that shows the verification code in the title of
the page (http://www.yoursite.com/showtitle.html), content takes
verification code and inserts into title of HTML page) and
2. No client secret

It also seemed there were reasons why native app developers might prefer
using User-Agent flow over Web Callback, and vice versa. The Device flow is
also an option.

This seemed to be an opportunity to simplify the spec by removing Native App
flow. A proposal:
- Remove Native App flow
- Make client secret optional in Web Callback flow
- Add text to the spec to give overview of options for native app developers
- Document the "show verification code in titile" technique in best
practices doc

Evan

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Fri, 16 Apr 2010 20:09:07 -0700

> - Add text to the spec to give overview of options for native app developers

I need a proposal.

EHL

---

From: Evan Gilbert <[email-masked]>
Date: Fri, 23 Apr 2010 10:16:15 -0700

> > - Add text to the spec to give overview of options for native app

Here's a proposal for text to cover the options for native applications

*3.8 Native Applications*
Applications running in an operating system that have the ability to launch
or embed a web browser can use any of the User Delegation flows or the End
User Credentials flow to get an access token for the user.

Some options for native applications:

   - Launch an external browser and have it redirect back to your app using
   a custom URI scheme. This works with the Web Server flow and User Agent
   flow.
   - Launch an external browser & poll for changes to the window title. This
   works with the Web Server flow with a custom redirect result page that puts
   the verification code in the title.
   - Use an embedded browser and read the redirect URL. This works with the
   Web Server flow and User Agent flow.
   - Use the Device profile with either an external or embedded browser. The
   application will open a browser and then poll the authorization server for
   results.
   - Use the Username and Password Flow and prompt the user for their
   credentials. This is generally discouraged as it hands the user's password
   directly to the 3rd party and may not work with more complex authentication
   schemes.

Factors in choosing between launching an external browser and an embedded
browser:

   - External browser may improve completion rate as the user may already be
   logged in and not have to re-enter username and password.
   - Embedded browser often has a better user flow, as you don't have to
   switch contexts and open a new window.
   - Embedded browser is less secure because users are entering their
   password in a screen within a target app.