OAuth for QuickBooks Online REST Services
1 like3,082 views
The document provides a detailed overview of implementing OAuth for QuickBooks Online REST services, including information on creating apps, token management, and security practices. It discusses the flow of the OAuth authorization process, the importance of protecting OAuth tokens, and resources for using various programming languages. Additionally, it includes technical endpoints and implementation notes for developers, while addressing restrictions and considerations around app token management.
![Projections of the Graph
V4 {
companies: {
bills: {
vendor: { }
}
…
REST
GET https://v4.api.intuit.com/companies/1234/bills/1234/vendor
BATCH
POST https://v4.api.intuit.com/companies/1234/entities
[{vendor}, {employee}, {bill1}, {bill2}, {query}]
SIMPLE QUERY
GET
https://v4.api.intuit.com/companies/1234/bills?where=“vendor.name=J
eff”
GRAPH QUERY
POST https://v4.api.intuit.com/graphql
{ company(id: “1234”) {
bills(first: 100, where: “vendor.name=Jeff”) {
edges {
node {
id
txnDate
}
}
}
25](https://image.slidesharecdn.com/codeworkssanfrancisco-160519231647/85/OAuth-for-QuickBooks-Online-REST-Services-25-320.jpg)
OAuth for QuickBooks Online REST Services
- 1. Intuit Developer Group Oauth for QuickBooks Online REST services JarredKeneally Intuit Developer Relations
- 2. Who’s in the room? 2 • What’s your role? - ProductManager - Engineer? • Worked with OAuth-authorized APIs before? - OAuth 1.0a? - OAuth 2.0? • What languages are you working in? - Java? - .NET? - NodeJS?
- 3. 3 What is OAuth? Industry Standard in durableauthentication & authorization (AuthN & AuthZ) Token Provisioning,Use,Revocation Replacesprocesses thatinvolve you storing username+passwordfor services you do not provide Widely adopted,tested,and supported
- 4. 4 How does OAuth work? When you create an App on developer.intuit.com you get an OAuth consumerkey & secret Use the consumerkey to get a requesttoken (server-to-servercall) Open a browserwindow to Intuit for the user to authorizethe token request Upon authorization by the user,a redirectcallback to your serverfrom the browserwindow provides a tokenVerifier When you get the token verifier,the responseshouldclose the popup window. Make server-to-servercallto exchangerequestTokenand tokenVerifierfor an accessTokenand accessTokenSecret
- 5. 5 The OAuth Authorization Conversation
- 6. 6 Why is OAuth “hard”? Oauth 1.0a was designed for potentially insecure communication channels Client and Serverneed to implementcryptographyto sign & verify every requestusing the token secret If you get the signature wrong,the requestis rejected You are signing a signature base string composed ofthe requestmethod,scheme,server,path,GET query parameters,and oauth parametersin the header(exceptthe oauth_signature parameteritself)in alphabeticalorder. • Example: GET&http%3A%2F%2Fphotos.example.net%2Fphotos&file%3Dvacation.jpg%26oauth_consumer_key%3Ddpf43f3p2l4k 3l03%26oauth_nonce%3Dkllo9940pd9333jh%26oauth_signature_method%3DHMAC- SHA1%26oauth_timestamp%3D1191242096%26oauth_token%3Dnnch734d00sl2jdk%26oauth_version%3D1.0%26size %3Doriginal • If you get the base string wrong, then the signature won’t match the base string calculated by the server and the request is rejected.
- 7. 7 Libraries Help. A Lot Signpostlibrary (oauth.signpost.*) DevDefined.OAuth The “request”module (npm installrequest) PECL OAuth library or OAuthSimple oauth Gem Java .Net NodeJS PHP Ruby
- 8. 8 Critical URLs RequestToken endpoint: https://oauth.intuit.com/oauth/v1/get_request_token UserAuthorizationURL:https://appcenter.intuit.com/Connect/Begin Access Tokenendpoint:https://oauth.intuit.com/oauth/v1/get_access_token You will typically need to configure any library you use with these three key endpoints. Reconnectendpoint:https://appcenter.intuit.com/api/v1/connection/reconnect Tokensexpire 180 days aftergrant Within 30 days of expiry,callthe reconnectAPIto ensure uninterruptedservicefor your users
- 9. 9 Oauth Tokens & Secrets are “Top Secret” Data Yourclient credentials(ConsumerSecret)representthe ability to get a user to authorize access to their data thinking they are granting that access to you! If a black hatcan get your secret,they can use yourbrand to do bad things Your consumersecretshould alwaysbe encrypted when at-rest. An access token represents a long-term authorization foryourapp to accessa given user’s data unattended. Accesstoken and AccessToken Secretdata should*always*be stored in encrypted storageand the encryptionkey shouldnotbe stored in the same place! Access tokens& secrets shouldneverbe delivered to a browser Nevermake a call to ourAPIs directly from client-side Javascript For native client-side code in mobile devices:4-leggedOAuth
- 10. 10 Connect to QuickBooks – The Client Side • We provide a JS library to help manage the flow - https://js.appcenter.intuit.com/Content/IA/intuit.ipp.anywhere-1.3.2.js - Call intuit.ipp.anywhere.setup(params) o Params is a dictionary withgrantURL,datasources object,andpayment options object o grantURL is the URL on your server to start the Oauth process - When Connect To QuickBooks button is clicked call intuit.ipp.anywhere.controller.onConnectToIntuitClicked() o Opens a new popup window o Initiates a sessionwithIntuit withthe parameters you suppliedregarding data sources needed, etc. o Redirects to your Grant URL o Your GrantURL redirects back to us for the user to authorize the connection o We redirect back to your callback URL withthe token verifier o Your response closes the popup window
- 11. 11 Gotcha! Currentimplementationrestricts each app to one OAuth token per company! Same usergranting a token to the same app for the same company: • no error, previous token invalidated, new token granted. Differentuser granting a token to the same app for the same company: • Error! User informed that user X already subscribed to the app for this company, OAuth token is denied. We did this to preventtwo users from connecting the same app unaware ofeach other and creating duplicate data. There are legitimate use-cases for multiple tokens (i.e.multiple stores on an e-commercesite for differentregions),we’re consideringoptions.
- 12. 12 Explore the OAuth Samples .NET: https://github.com/IntuitDeveloper/oauth-dotnet Java:https://github.com/IntuitDeveloper/oauth-java PHP: https://github.com/IntuitDeveloper/oauth-php NodeJS:https://www.npmjs.com/package/node-quickbooks npm installnode-quickbooks cd node_modules/node-quickbooks/example Ruby:https://github.com/ruckus/quickbooks-ruby
- 13. 13 Putting it all together
- 14. 14 Q & A Contact Us: @IntuitDeveloper @JarredKeneally developer.intuit.com
- 15. Oauth 1.0 15
- 16. Oauth 1.0a 16
- 17. Oauth 1.0a 17
- 18. • An elegant and cohesive ecosystem API - Envisioned as a graph - Consumed by 1P through an internal SDK - Experienced through projections • High degree of automation – architected for testability • Architecture - Domain variability expressed consistently through Json Schema • Accelerates decomposition through orchestrated graph queries and writes • Enables innovation, balancing speed with governance • Dog-fooding: identical functionality, quality, and availability for 1st, 2nd, and 3rd parties V4 Services Overview V4 3rd 2nd 1st 18
- 19. Putting it all together 19
- 20. V4 Endpoint V4 Decomposed Services Putting it all together – ideal V4 services state 20 Internal SDK V3 EndpointTranslation QBO UX Widgets (Mobile, Web, Future 3P) 1P 2P / 3P Official 3P SDKs (e.g. Java, .net, PHP) App / Integration App / Integration App / Integration Many (~50%) of our 3P developers also use SDKs. Our official 3P SDKs will evolve to support multiple API version interoperability. Many of our 3P developers write directly to rest APIs. Our 1P teams will make heavy use of an internal SDK that enforces internal best practices around building great offerings. Our translation infrastructure makes it possible to extend the lifetime of API versions – a tremendous developer benefit for 1P, 2P, and 3P personas. Accountin g Payroll Payments Money Movemen t & Risk Transactio ns ReportingCompany Accountan t Integratio ns Network Indirect Tax Inventory
- 21. 21
- 22. V4 API Services Developer Benefit 22 QBO UX Widgets (Mobile,Web, Future 3P) V4 QBO Services App / Integration Complete and Consistent Foundation for Developers • 2P/3P Developers can do anything that the UI can do • All QBO uses the same services – so no more one-off behaviors • Apps enjoy the same reliability as core QBO V3 App V3 Endpoint V4 Endpoint V4 App Translation App Durability • API version translation means that developerinvestment is durable • No more deprecation cost for developers (and the QuickBooks team) QBO Services V4.1 Endpoint V4.1 App Translation QBO Services V4.n Endpoint V4.n App Translation QBO Services
- 23. Grow My Business Deliver Awesome Experiences Quickly Access New Connections Retention Active Connections Speed Time to Launch Value Integration Star Rating + + DEVELOPER SEGMENT 23
- 24. V4 is a graph V4 { companies: { bills: { vendor: { } } employees: { } vendors: { } items: { } } users: { … } } Root of the graph Has an array of companies Which has an array of bills … 24
- 25. Projections of the Graph V4 { companies: { bills: { vendor: { } } … REST GET https://v4.api.intuit.com/companies/1234/bills/1234/vendor BATCH POST https://v4.api.intuit.com/companies/1234/entities [{vendor}, {employee}, {bill1}, {bill2}, {query}] SIMPLE QUERY GET https://v4.api.intuit.com/companies/1234/bills?where=“vendor.name=J eff” GRAPH QUERY POST https://v4.api.intuit.com/graphql { company(id: “1234”) { bills(first: 100, where: “vendor.name=Jeff”) { edges { node { id txnDate } } } 25
- 26. Normalized to a Batch… Domains implement BATCH REST SIMPLE QUERY GRAPH QL Projections BATCH BATCH 26