This wiki is no longer active and is left here for historical purposes. Please visit oauth.net for up-to-date information.

Flows

While all OAuth 2 flows can be used by native apps, only the user delegation flows will be considered in this document: Web Server, User-Agent and Device flows.

The Web Server and User-Agent flows are similar in that information in the browser must be captured by the native app at some point. Transferring control and information from the browser back to the native app is a hard problem. The next section lists techniques that allow that.

The Device flow does not have the above problem, but it has a potential session fixation vulnerability. Also, this flow is relatively new and it was not used by native apps so it is not proved in practice.

Changes needed by current spec so native apps are supported:

• Web Server flow
• define standard result page if redirect_uri is missing
• make sure unregistered clients are properly supported
• make sure registered by insecure clients are supported
• display name parameter may be required
• User-Agent flow
• display name parameter may be required
• Device flow
• should define standard parameter name for user code
• display name parameter may be required

 

Information Transfer Techniques

After the end user approves that the native application gets access to the requested scopes the user-agent is redirected to the redirect_uri. The result page at the redirect_uri should display the information that the native application needs along with instructions for the end user. This information is a verification code (Web Server flow) or access/refresh tokens (User-Agent flow). The information can also include some client state, if it was initially sent by the client.

If the end user denies access, then ideally the result page should also be displayed but the information will be a relevant error code and some explanation for the end user.

The following techniques allow native applications to extract the needed information from the result page.

 

Manual copy-and-paste

The result page shows only one piece of text that the end user can copy and then should paste into the native app. Instructions on how to do that should also be provided. The text to be copied could be a single code/token or an encoded data structure.

The authorization dance can happen on a different machine and be controller by a separate web server. The native app could instruct the user to go to a URL and grab an activation code from there. The web application at the URL will start the OAuth dance with the same client Id as used by the native app and at the end show an appropriate result page.

Pros:

• easy to implement

Cons:

• loop is not closed automatically
• user has to copy-paste or memorize-type

 

Automatic copy-and-paste

The result page uses JavaScript and/or Flash to copy the information to the system clipboard. The native application is watching the clipboard in a loop.

Pros:

• good user experience

Cons:

• hard to copy to system clipboard from HTML page, may need flash
• text copied to clipboard can be seen by other apps, can leak, may need to encrypt
• native app must ensure it grabs the proper text from clipboard, client state can help
• requires JavaScript to be enabled in browser to copy to clipboard

 

Custom URI Scheme

The native app registers a custom URI scheme that will launch the application itself, or a helper app. The redirect_uri would use this scheme.

Pros:

• good user experience

Cons:

• no standard way to register schemes
• possible security issues if a newer app grabs an existing scheme
• does not work as well on desktop apps as on phones

 

Local Web Server

The native app starts a local web server on some available port and the redirect_uri will point to this server.

Pros:

• good user experience

Cons:

• native app needs to embed a web server
• local firewall may block access to local web server

 

Embedded Browser

The native app embeds a browser.

Pros:

• good user experience
• good integration with native app, no focus issues

Cons:

• embedded browser uses different cookie jar, no active session, user forced to login (apparently on Mac and iPhone cookies are shared by embedded browser)
• no browser plugins present, user may have difficulties to login
• probably no username/password auto-completion
• if some form of strong auth is used once per browser the user is forced to do it again
• what is embedded may not be the user’s preferred browser
• does not work with CLI apps
• user still enters credentials in native app

 

Monitor Cookies

The native app watches the cookie jar of the browser it launched. The result page will save the information to a cookie using JavaScript.

Pros:

• good user experience

Cons:

• each browser saves cookies differently
• access to cookie files cannot be synchronized
• requires JavaScript to be enabled in browser to save cookie

 

Monitor Window Title

The native application launches a browser and then keeps tracking the process and the corresponding OS window title. The result page should make sure the information shows up in the window title.

Pros:

• good user experience

Cons:

• only shorter text can be transferred
• no guarantee that each window manager or browser will display the title consistently

 

Browser Extension

The native app relies on a browser extension it can communicate with. The extension notices when the result page is rendered, extracts the information and passes it to the native app.

Pros:

• good user experience
• only method that can close the loop even if user wanders off or closes browser

Cons:

• extensions must be created for all browser
• user needs to install extension

 

Types of Result Pages

• Dynamic web page controlled by the native app publisher on some external web server.
• Default dynamic web page provided by the authorization server.
• Dynamic web page controlled by the native app on local machine.
• Custom scheme URI that invokes native app or helper.
• Static HTML page on local machine.

 

Types of Native Apps

• GUI Desktop App
• CLI Desktop App
• Smart Phone App

 

Technique vs Flow

	Web Server	User-Agent
Manual copy-paste	Yes	No1
Automatic copy-paste	Yes	Yes2
Custom Scheme	Yes	Yes
Local Server	Yes	Yes
Embedded Browser	Yes	Yes
Monitor Cookie	Yes	Yes2
Monitor Title	Yes	No3
Extension	Yes	Yes

Notes:

1. Access token, expiry time and potentially refresh token all would have to be copied. May not be practical.
2. Important tokens could be leaked.
3. Information probably too long to fit into window title.

 

Technique vs Native App Type

	GUI Desktop	CLI Desktop	Smart Phone
Manual copy-paste	Yes	Yes	No1
Automatic copy-paste	Yes	Yes	?
Custom Scheme	Yes	Yes	Yes2
Local Server	Yes	Yes	No
Embedded Browser	Yes	No	Yes
Monitor Cookie	Yes	Yes	?
Monitor Title	Yes	Yes	No
Extension	Yes	Yes	No

Notes:

1. Could work for simple verification code. Approval can even be done on a different computer.
2. This seems to work particularly well for phone apps.