Privacy/BestPractices/OAuth
From time to time, Mozilla products may need to access third-party services protected by OAuth. This document details the software design options against various OAuth providers and catalogs their pros and cons.
Contents
Overview of OAuth
It is often important for users to give a third party access to their data. OAuth is a widely deployed standard for this purpose: a data host, e.g. Facebook, allows a consumer, e.g. FarmVille, to access a user's data when that user agrees. The OAuth protocol consists of two major portions:
- credential negotiation: the consumer, data host, and user engage in a dance that concludes with the consumer obtaining credentials that will allow it to make API calls into the data host to access the user's data. In this process, the user typically sees, before approving the request, which rights the data consumer is requesting (e.g. read, read/write, ...).
- authenticating API calls: the consumer uses credentials to authenticate its API calls against the data host.
Credential Negotiation
- the consumer registers with the data host and obtains a consumer_key, which is considered public, and a consumer_secret, which should be kept private.
- a user interacting with a data consumer decides to connect it to her data host, triggering the consumer to redirect the user to the data host with a permission request.
- the user is prompted to approve the request, at which point the data host redirects the user's browser back to the data consumer with a confirmation code.
- the data consumer makes an API call to the data host, authenticated with the consumer's credentials, to exchange the confirmation code for an access_token (and, in OAuth 1.0, an access_token_secret.)
The resulting access token is the user-specific credential that can be used to make API calls.
Authenticating API Calls
To make OAuth-credentialed API calls, the consumer adds authentication information to the HTTP calls it makes. This authentication information ranges from adding the access token as a GET parameter (OAuth 2.0 bearer tokens), to canonicalizing the request and signing it with HMAC using a combination of the consumer_secret and access_token_secret (OAuth 1.0 HMAC).
Differences between OAuth 1.0 and 2.0
Though they both follow the above pattern, OAuth 1.0 and 2.0 are quite different:
- In OAuth 1.0, API call authentication requires both the user-specific secret and the data-consumer secret. In OAuth 2.0, only the user-specific secret is needed to authenticate API calls.
- OAuth 1.0 is optimized for using HMAC to establish tokens credentials and make API calls, while OAuth 2.0 is optimized for bearer tokens over SSL (essentially, passwords over an encrypted channel.) OAuth 1.0 is technically capable of bearer tokens, but no one uses this because it would require sending the master-secret in every call. RSA signatures can be used in OAuth 1.0 instead of HMAC, but few providers support it, and the option has gone away in OAuth 2.0. HMAC signatures of API calls are supported in OAuth 2.0 with a simplified canonicalization algorithm, but do not appear to be in use by providers at this point (May 2011).
- OAuth 1.0 encourages the use of long-lasting user tokens, while OAuth 2.0 encourages the use of short-term user tokens with a built-in refresh mechanism. The refresh mechanism in OAuth 2.0 requires the consumer's master secret.
OAuth Consumer Design
While data hosts that offer OAuth are consistently web-based services, e.g. Facebook, consumers of OAuth services vary, and this variation can affect the preferable OAuth implementation path.
Web-based
The typical OAuth architecture involves a web-based consumer and a user accessing both the data-host and the consumer services via a typical web browser. The most important property of this setup is that the consumer sits on a controlled server and can easily maintain the secrecy of its authentication credentials.
OAuth 1.0 is designed around this specific use case (and makes others difficult). OAuth 2.0 calls this the Authorization Code Flow, because when the user approves the data-access, an authorization code is issued, and the data consumer must exchange this code for the actual access token.
Device-based
In some cases, e.g. desktop software or mobile-device apps, the consumer is not hosted on a remote server. Instead, it runs entirely on each user's device. In this scenario, it is not possible for the data host to truly authenticate the consumer: an attacker can extract all secrets from the software binary. Some controls can make it harder to extract the secret, but it is always feasible.
To integrate the desktop/device software with the web-based data host, it is typical for the consumer software to spawn a web browser through which the user authenticates and grants permission. Things are a little bit tricky for the second redirect, from the data host back to the consumer. In some cases, notably mobile devices, apps can register protocol names, so that redirecting to appname://back_from_auth?code=.. will trigger the switch back to the app, which can then complete the credentialing dance using the obtained code.
OAuth 2.0 defines a more integrated flow called the Implicit Authorization Grant. The data-consumer software is expected to embed a web browser and direct it to the data host for authorization. In the second redirect, the data host sends the consumer's embedded browser to a well-defined URL with the access_token positioned in the fragment identifier. The data consumer is expected to sniff this URL, extract the access_token and close its embedded web browser.
Hybrid
With OAuth 2.0, because API calls do not require the use of the consumer's master secret, a hybrid approach is possible: the credential negotiation and token refresh are mediated by a web-based server, while the user token remain on the user's device and the API calls are made directly from there.
Major OAuth Providers
Facebook supports only OAuth 2.0, with all three flows: server-side, fully device-based, and hybrid. In the device-based mechanism, the consumer_secret is not required. Thus, Facebook OAuth flows can be fully implemented in a desktop/mobile client.
Twitter runs an OAuth 1.0a service, with tokens that can either read or read-and-write. OAuth 2.0 support is not available at this time.
Twitter is particularly concerned about attackers using OAuth to bypass Twitter rate limits on API calls. Specifically, since rate limits are per-user-per-OAuth-app, leaking the consumer secret means an attacker can use it to increase his number of calls. To our knowledge, this concern is unique to Twitter.
