Presented by Jarred Keneally at the Code Works events for Intuit Developer on May 17, 2016 in San Francisco and June 16, 2016 in London

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