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