In the first article in this series on using the QB API, we came up with a basic plan, and made the implementation of it sound pretty easy. And, it is straightforward … except for one part, a dark chasm we must cross, a confusing and mysterious place known as OAuth 1.0.
Understanding authentication with OAuth 1.0 is the sort of thing that most developers spend a little time trying to do before they go off and find a library some hardier person wrote that does it for them. Which is what I’ve done, and and we will use that library here. But first, we will do a daring and possibly foolish thing: we will delve into the mysteries of OAuth as implemented by Intuit. Let’s get this over with before I lose my nerve!
Ponder this tricky problem: I’ve written a cool Service (for example, an accounting tool called QuickBooks) which has many separate Users, each with their own account on my Service. I want to let anybody write a Client App that makes use of my Service’s API to make calls to a specific User’s account on my Service.
Here’s why the problem is so tricky: I require that a Client App get a User’s permission before messing with their account on my Service (duh). And furthermore, I don’t want a Client App to ever get it’s untrusted (and possibly dirty) little hands on any User’s login information, even though I’m going to need that User to log into their account to give permission.
How can this be done securely? OAuth provides one possible way to do this.
Intuit’s OAuth Flow
Here’s OAuth’s answer to the problem above, written in the form of a dialog between your Client App (the thing using the QuickBooks API), QuickBooks (the Service), and the QuickBooks Authentication Server (the central place helping with authentication. It all starts when a Resource Owner (a person who owns a QuickBooks account) pulls up a webpage with your Client App for the first time:
Client App: Hey, QuickBooks Authentication Server (QB Auth Server), somebody wants to use me to access their QuickBooks account.
QB Auth Server: Ok, here is a temporary token called a Request Token. Send your Resource Owner over to QuickBooks along with this Request Token, and have them log in and confirm that they’re cool with you accessing their stuff.
Client App: Ok. Hey Resource Owner, tell QuickBook who you are and that it’s cool to work with me.
Resource Owner: Ok. Hey QuickBooks, here’s my login, and yes, I want to let this Client App mess with my Quickbooks account.
QuickBooks: Ok. Hey, QB Auth Server, somebody sent this Resource Owner over here. Here is their login info, and they have this Request Token from this particular Client App. Can you confirm that their login is legit, and that you really gave that Request Token to that Client App?
QB Auth Server: Yes, that is the valid login from that Resource User, and I did provide that Request Token to that particular Client App.
QuickBooks: Awesome. Hey, Client App, everything checks out — the Resource Owner you sent over provided a valid login, confirmed that they want to let you access their account, and your Request Token was valid. Here’s an OAuth Token and Secret that you can use to get an OAuth Access Token when you’re ready to make an API request. Those will be valid for 6 months, and you can renew them after 5.
Client App: Hurray! Ok I’m ready to make a real call. Here’s my OAuth Token / Secret, please give me my OAuth Access Token.
QuickBooks: Groovy, here’s your OAuth Access Token, enjoy yourself.
Client App: Here’s my OAuth Access Token along with an API call …
QuickBooks: Here’s your API response …
And they live happily ever after. If you stayed with me through that whole thing, you may have noticed that the OAuth Token / Secret provided after the bulk of that dance was over will stay valid for 6 months, and can be renewed after 5 months. I’m assuming you’re an astute reader (I can tell these things) and as a result said something to yourself along the lines of “oh, we should store that info at that point and avoid going through that whole thing every time our poor Resource Owner wants to work with my Client App.” And you were very right. We’ll mention that step below, and will implement it in the next edition of this series.
QuickBooks OAuth with Ruby
Here’s a diagram of what that process looks like from your app’s (the Client App’s) point of view:
The user (the Resource Owner) experience embodied in the flow above for a typical Client App might go something like this:
- Somewhere in your Client App, the user must authorize access to their account before your Client App can do anything with their account. On that page, the “QB Connect” button shown above appears.
- The user clicks on that button, and a pop-up comes up asking them to log into QuickBooks and then to authorize your Client App.
- The pop-up window informs the user that everything is all set, and that they’re ready to use your Client App, and off you go.
In the next installment, we’ll build the flow above, using Ruby on Rails and Cody Caughlan‘s fine quickbooks-ruby Gem. If you’re anxious to get a move on, here’s our code to get an OAuth Access Token (but not to store it, that’ll get added later), and here’s a great series that covers Rails / QB integration from a slightly different perspective.