OAuth - The Standard That Isn't...

OAuth in theory and in practice

Author's note: This paper was written in conjunction with the team at OAuth.io

The idea behind OAuth is simple: a standard way to enable access to protected resources, such as a social network, so a user can sign into a web service and, through a secure exchange of tokens, an app or third party can access that service. The developer never needs to see the user's username or password. In reality, however, implementations vary widely and contain many traps for developers.

OAuth 1.0 was released in October 2007 and revised in June 2009 as OAuth 1.0 Revision A. It was published as RFC 5849. The protocol is difficult to implement, has no standard token expiry or access-control level, and differing implementations create interoperability problems.

OAuth 2.0 was developed as a non-backward-compatible alternative and published as RFC 6749 in October 2012. It is more flexible and easier for client developers, but that flexibility turned it into a framework with many possible implementations. OAuth 2.0 also depends on TLS rather than OAuth 1.0's request signatures, which changes the security trade-off.

Documentation

OAuth 1.0 requires three distinct calls. The client requests temporary credentials, opens an authorization page so the user can grant access, and then calls the OAuth server again with the temporary credentials and returned token to obtain the final access token.

OAuth 2.0 simplifies this to two calls: open the authorization page, then exchange the returned code for an access token. The reduction is helpful, but the provider's exact flow and endpoint names still need to be documented clearly.

Finding the URLs for these services can be a challenge. Some providers hide the details inside code examples, make it unclear which service is being called, or fail to distinguish OAuth 1.0 from OAuth 2.0.

API implementation

Token responses vary enormously. Most providers return JSON, including Facebook, while others return XML, such as Concur, or URL-encoded text, such as Google. A token format found in one service is not a reliable guide to another, and copying an example often fails.

Early OAuth 2.0 implementations accepted the access token as an HTTP request parameter, while the final specification describes an HTTP header. Some providers support only one form. The parameter name also varies: Facebook uses `access\token` as described by RFC 6749, while Google and more than half of the web use `oauth\token`, largely because they implemented an earlier draft.

The `scope` parameter is similarly inconsistent. Providers use spaces, commas, semicolons or pipes as separators; some accept one scope option while others accept several. Google uses scope URLs, Live.com prefixes scope elements, and some providers use uppercase characters. Every provider needs to be treated as its own integration.

The paper cites TripIt as an OAuth 1.0 implementation that does not return `oauth\verifier` and requires `oauth\callback` in the authorization URL. For OAuth 2.0, AngelList is cited as a provider where common workarounds are not always possible. These differences are not cosmetic: they change the security and interoperability properties of the integration.

Token expiry and renewal

Tokens can expire, but providers differ significantly in how quickly they expire and whether renewal is straightforward. The standard OAuth 2.0 refresh-token flow should allow a client to call the OAuth server without user interaction, yet many services do not support it or add their own mechanism.

Facebook uses a custom `fb\exchange\token` grant type to exchange a token for a new token with a new expiry. Google and GitHub implement the standard refresh approach, but they are exceptions rather than the rule in the paper's survey.

Providers also expose different controls for longer-lived tokens: Google uses `access\type=offline`, Stack Exchange has `no\expiry`, SoundCloud has `non-expiring`, Meetup.com has `ageless`, and Live.com has `wl.offline\_access`. If automatic renewal is unavailable, the user must sign in again. During individual tests, observed timeouts were as short as two hours.

Speed

The OAuth process can require up to three separate API calls. The following comparison uses APImetrics public community tests conducted during the week ending March 14, 2014. All tests ran concurrently from the same test servers over a common internet connection.

Average latency varies by more than a second from the fastest service to the slowest. GitHub and Intel are four to five times slower than most other OAuth services on average. Maximum latency matters just as much: the normal tool timed out after 60 seconds, while GitHub took almost six minutes and involved ten redirects.

Even services with a 100% pass rate can be unpredictable. Yahoo's OAuth dialog passed every test, but one test still took more than 45 seconds. A delay in the request-token call is layered on top of the authorization dialog, increasing timeout risk and user frustration, especially on mobile.

Conclusions

OAuth has become an essential part of modern API access, but the standard does not guarantee a uniform developer experience. Documentation, token formats, parameter names, scope syntax, expiry, renewal and performance can all vary from provider to provider.

• Plan for discovery work: Allow additional time when integrating a new OAuth service, even when it claims to follow the standard.
• Design for slow responses: Authentication may take several seconds or involve many redirects. Keep users engaged while the third-party flow completes.
• Measure the complete journey: Average latency and pass rate are not enough; maximum latency, redirects, token renewal and real user geography all matter.
• Consider an integration layer: Services such as OAuth.io can absorb differences across provider implementations and reduce the burden of maintaining dozens of bespoke integrations.

The authors

About APImetrics

APImetrics is a Seattle-based company focused on testing and performance measurement for APIs. Almost every application, service and technology depends on APIs, making it critical to understand their impact on customers and users. APImetrics products help developers, enterprises and API providers understand API behavior and performance.

About OAuth.io

OAuth.io helps developers integrate OAuth in minutes instead of hours or days. It removes the burden of maintaining more than 30 provider implementations, supports more than 100 providers including Twitter and Facebook, and was relied on by more than 4,000 apps at the time of publication. Its core engine is open source.

Glossary

The authentication and performance terms used in this white paper, defined for teams integrating third-party APIs.

OAuth

An authorization framework that lets an application access protected resources through tokens without receiving the user's password.

OAuth 1.0

The original OAuth protocol, using signed requests and a multi-step request-token and access-token flow.

OAuth 1.0a

The June 2009 revision of OAuth 1.0, published as RFC 5849.

OAuth 2.0

A non-backward-compatible OAuth alternative published as RFC 6749. It is more flexible for clients, but leaves providers a broad implementation framework.

Access token

A credential issued by an OAuth server that an application presents when requesting protected resources.

Refresh token

A credential used to obtain a new access token without requiring the user to authorize the application again.

Scope

A provider-defined description of the permissions an access token grants.

State parameter

A value returned through the authorization flow so a client can correlate the response and help defend against CSRF.

CSRF

Cross-site request forgery, an attack in which a user's browser is induced to perform an unwanted action in a trusted session.

OAuth provider

The service that authenticates the user, grants authorization and issues tokens for its protected API.

About APIContext

APIContext eliminates blind spots for enterprises across the digital delivery chain with proactive synthetic monitoring, performance analytics, and automated conformance validation. Our platform delivers actionable insights so connected systems perform and conform—ensuring every interaction is trusted, secure, and compliant.

What are your APIs saying to AI? Contact us to find out.