OAuth 2 and Native Apps 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. easy to implement 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. 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. 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. 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. good integration with native app, no focus issues 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. 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. 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. only method that can close the loop even if user wanders off or closes browser 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 No 1 Automatic copy-paste Yes Yes 2 Custom Scheme Yes Yes Local Server Yes Yes Embedded Browser Yes Yes Monitor Cookie Yes Yes 2 Monitor Title Yes No 3 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 No 1 Automatic copy-paste Yes Yes? Custom Scheme Yes Yes Yes 2 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.