Privacy/BestPractices/OAuth

From time to time, Mozilla products may need to access third-party services protected by OAuth. This document details the options from various OAuth providers and catalogs the pros and cons of these options.

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 in 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 consumer is requesting (e.g. read, read/write, ...).

• authenticating API calls: the consumer uses credentials to authenticate its API calls against the data host.

OAuth version 1 and 2 are quite different, but they both follow the above pattern.

Differences between OAuth 1.0 and 2.0

OAuth 1.0 and 2.0 are incompatible at the protocol level. The important design differences are:

• OAuth 1.0 credentials for API calls include the consumer's master secret in addition to the user-specific secret, while OAuth 2.0 credentials for API calls require only the user-specific secret.

• OAuth 1.0 is optimized for using HMAC during token establishment and 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.

• 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. This refresh design is most useful when user tokens are built to be self-verifiable (e.g. containing their own signature), so that large-scale OAuth deployments can scale horizontally more easily.

Designs of OAuth Consumers

Web-based

The typical OAuth architecture involves a web-based data host, e.g. Facebook, a web-based consumer, e.g. FarmVille, and a user accessing both services via a typical web browser with no special capabilities. 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.

Device-based

In some cases, e.g. desktop software or mobile-device apps, the consumer is not hosted on a remote server, rather it is hosted on each user's device.

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.