Quickbooks Online - OAuth2 Samples in DotNET

The Intuit Developer team has written these OAuth 2.0 sample applications using the .NET 6.0 (C# 10) framework to provide working examples of OAuth 2.0 verification concepts and methods.

Getting Started

Before proceeding, it may be helpful to understand how OAuth 2.0 works in Quickbooks Online. Check out the Authorization FAQ and the Authorization and authentication page found in the official Intuit documentation for more information on OAuth 2.0.

Pre-Requisites

Visual Studio
DotNET 6.0 SDK
A QBO App
WebView2 Runtime (Only required for the WinForms and WPF samples.)

Setup

Download the source code or use the clone function in Visual Studio to clone the repo to a local folder.

User Configuration

After cloning or downloading the repo, you will need to update the Tokens.json file to match your apps ClientId and ClientSecret. These values are in the Keys & credentials section under Development Settings on your QBO app’s dashboard.

{
  // The ClientId and ClientSecret
  // can be found in the QBO app on
  // the Keys & credentials page.
  "ClientId": "{your client id here}",
  "ClientSecret": "{your client secret here}",
  // Make sure this URL (or your custom URL) is
  // added to the redirect URLs in your QBO app.
  // 
  // Note: this URL can be anything as long as
  // it is listed in your QBO apps redirect URLs.
  "RedirectUrl": "https://archleaders.github.io/QBO-OAuth2-DotNET/",
  // This will be filled after running
  // the app and authenticating.
  "AccessToken": null,
  "RefreshToken": null,
  "RealmId": null
}

Note — if you are using the QBO.WebApp project, change the RedirectUrl to https://localhost:7106/Receiver

For more information on each configuration parameter, check out this document on the different Tokens and why they are used in OAuth 2.0.

Building

Once you have configured the settings to match your QBO App’s settings, build the solution in Visual Studio and run any one of the sample applications.

How it Works

This repository is set up to minimize code duplication and keep everything organized. That is done by having a single shared library that handles QBO connections and anything else done in the back-end of your application.

This section covers how each sample project handles OAuth2 authentication with the QBO SDK.

Desktop — WinForms / WPF

The Desktop sample implements a WebView2 control from the WebView2 library to display the Intuit sign-on page to the user while still keeping it contained within the application.

Note — All users must have the WebView2 runtime installed on their machine.

Authentication Flow

In the desktop sample applications, the authentication code is triggered and ended by two events. These two events can be anything, if the user runs the second event; this is clarified further by examining the authentication flow.

First Event (Form.Load in the sample application)
- The ClientID and ClientSecret are used to get an authorization URL from QBO. ^Shared
- That URL is sent to the WebView2 control to be rendered. ^WinForms
- The user is then prompted to sign in to their QBO account on the rendered page.
- After signing in, the WebView2 control is redirected to the RedirectUrl with a code and realmId in the query parameters.

At this point, your application has no idea that the authentication completed. We need a message from the user (or the redirected site) to say: “Yes, I have signed in and have been redirected.” That message in this example is the Form.Closing event.

Second Event (Form.Closing in the sample applications)
- The query parameters in the current WebView source URL are sent to the helper method to be handled. ^WinForms
- These are then used to get an access token from the OAuth2Client. ^Shared
- The next step depends on how you will store your access and refresh tokens. In this sample, it is just stored in a class to be written to a JSON file. ^Shared ^| ^WinForms

Further details are in the code and comments of each project.

Web App — ASP.NET Core

The ASP.NET sample application (as a web app) can natively display the Intuit sign-in page and collect the response from our server by setting the redirect URL to your host address (typically a page set up to receive and handle the query).

Authentication Flow

In the ASP.NET sample application, the authentication code is run when the Home (root) page is visited and ends when the Receiver page is visited. This example is not very practical in a real-world scenario; it is used to leave out unnecessary extra code that might be confusing.

First Event (HomeController.Index in the sample application)
- The ClientID and ClientSecret are used to get an authorization URL from QBO. ^Shared
- The controller then redirects to that URL and gets discarded automatically. ^WebApp
- The user is then prompted to sign in to there QBO account on the opened page.
- After the user signs in, a query request is sent to the redirect URL to be handled.

Second Event (ReceiverController.Index in the sample application)
- The query parameters of the current page are sent to the helper method to be handled. ^WebApp
- These are then used to get an access token from the OAuth2Client. ^Shared
- The next step depends on how you will store your Access and Refresh tokens. In this sample, it is just stored in a class to be written to a JSON file. ^Shared ^| ^WebApp

Further details are in the code and comments of each project.

Note — this app uses the new OAuth2Client. If you want to refer methods using standalone OAuth2 clients, please download the source code for v1.0 in the Release section on GitHub.