Moving from Basic Auth to OAuth

Updated on Wed, 2012-08-22 08:55

Transitioning from Basic Authentication to OAuth isn't simple for everyone. You're going from an approach where you send a login and password with every REST API request you make to one in which you're first having to acquire user authorization, and then sending credentials that both identify your application and the user in every request.

We're here to help.

Many developers have trouble with OAuth. Search for OAuth topics or ask a question on our developer's mailing list if you run into problems.

Differences between Basic Auth and OAuth

If you think about an API request as a standard mailing envelope:

Basic Authentication

In Basic Authentication you need only provide a "return address" (the username and password), and the recipient's address (the resource you are accessing) -- occasionally stuffing the envelope with some data that is pertinent to the API request you are making.

Basic Authentication Envelope

Everything in this context is as simple as mailing a letter. Postage is generally free, but you can only send so many "letters" before your quota (rate limit) runs out.

Aspects of Basic Authentication with the Twitter API

  • The client application must store the user's login and password
  • The client application must send the user's login and password with every request
  • If the user's password changes, the client application must acquire a new password for the user
  • The user has no means to discover which basic auth-based apps have their login and password
  • The user has no ability to restrict an application from using their account after giving their login and password
  • The client application has a very weak identity within the Twitter ecosystem.
  • POST variables, query parameters, and the URL of the request can be modified at any stage of the request cycle without invalidating the request
  • Replayed requests are not preventable

Basic Authentication is a liability. By storing logins and passwords, a developer takes on additional responsibilities for the secure storage of those credentials; the potential harm to users if login credentials are leaked or abused is very high. Because many users utilize the same password across many sites, the potential for damage does not necessarily stop with their Twitter account.

OAuth Authentication

OAuth Authentication is a bit more complex in this metaphor.

OAuth Authentication Envelope

While you still address the envelope to the same recipient (the resource), you identify your request as coming from both the user performing the request and your application that's working on behalf of the user. In addition, you must provide a "post mark" of sorts, describing the time the "letter" was sent and the actual contents of the envelope. In some ways, this is the biggest difference between the access methods.

Aspects of OAuth Authentication with the Twitter API

  • The client application doesn't need to store a login and password
  • The client application delegates authorization to a trusted location, namely
  • The client application sends an access token representing the user with each request instead of a login & password
  • POST variables, query parameters, and the URL of the request must remain intact for a request to successfully complete (the oauth_signature cannot be verified unless all elements of the request retain their original qualities at the time of signature generation)
  • If the user's password changes, the client application continues functioning
  • The user is in control of what applications may act on their behalf and can remove authorization at any time
  • Your application is a known entity in the ecosystem, with benefits both realized and to come in the area of analytics, attribution, and more.
  • Replayed requests are prevented by a unique identifier for each request (the oauth_nonce)

With these comparisons in mind, it should be clear that migrating to OAuth is usually a more intensive process than just changing a few lines of code — and is highly dependent on the programming language and frameworks being used, in addition to what API interface libraries are in play.

Where do I begin?

Audit the API requests your application performs

Any authentication-requiring API calls that you make (such as statuses/home_timeline, statuses/mentions, statuses/update, etc.) will need to be converted to use OAuth. While you could choose to only move to OAuth for the operations requiring user authentication, it's recommended that you convert all of your API calls to using OAuth so that your application (and your user) are always identified in each request.

Choose an OAuth or OAuth-ready Twitter library for your programming environment

While you could go to the trouble of implementing all the ins and outs of the OAuth protocol (and HMAC-SHA1) yourself, it's not recommended. Consult our list of OAuth Libraries and Twitter Libraries to find a library suitable for you.

If you really want to create your own library we strongly encourage you to build a working application using existing libraries first. This way, when you roll your own solution you have a working application to compare to should you hit any problems.

Prepare long-term storage for access tokens and secrets

Whatever your storage system may be, you'll need to begin storing an oauth_token and oauth_token_secret (collectively, an "access token") for each user of your application. The oauth_token_secret should be stored securely. Remember, you'll be accessing these values for every authenticated request your application makes to the Twitter API, so store them in a way that will scale to your user base. When you're using OAuth, you should no longer be storing passwords for any of your users.

Choose & Implement your authentication pattern

We've put together a mini-guide called "Which authorization path should I choose?" that introduces the various OAuth methods we support for gaining user authorization — the process where an end-user grants your application permission to act on their behalf through a returned access token.

While implementing this, you'll need to prepare for a variety of different kinds of OAuth signed requests that are representative of the other types of calls you'll be making.

Migrate your API calls to using OAuth signatures

Now that you've prepared your OAuth implementation, you'll need to go through all the places in your code where you're currently using basic authentication and use OAuth instead. Like all parts of the OAuth flow, this is largely language and library dependent. Some OAuth or Twitter libraries will take care of all the nuts and bolts of these steps for you.


There are more than a few ways for an OAuth request to go wrong. Here are some tips to reduce the chance of errors.

  • Check you are using the right HTTP request method. Most methods on the Twitter API require a POST or GET request.
  • If you are generating your own nonce (number used once), make sure you incorporate the time and some form of random ID. To minimize the risk of nonce clashes between different uses of your application you might want also decided to incorporate something unique to the machine.
  • Check the order of the parameters you send in the request are the same as they were when you generated the OAuth signature.
  • Ensure that your system's timestamp is in sync with Twitter's. We return the current time in a HTTP header with every request.

Further Reading

Presentations on OAuth at SlideShare