Using Desktop and Mobile Apps with Xero using OAuth 1.0a


Background

Xero currently uses OAuth 1.0a for its authentication and to secure communication on an ongoing basis. OAuth 1.0a was originally designed for use in web applications. Unfortunately, both desktop and mobile solutions require on-device storage of key information that creates a significant security risk that Xero has determined is not acceptable. The key area where mobile and desktop solutions present an issue is allowing direct access to the underlying filesystem for decompilation / reverse engineering of code or access to key security features such as certificate files and consumer key and secret information.

There are alternatives however.


Alternative 1: OAuth 2.0 - coming in 2019

OAuth 2.0 will address the on-device security concerns raised above. Xero SDKs will also be updated to reflect the changes from OAuth 1.0a to 2.0 and Xero will also have a migration path to allow existing OAuth 1.0a apps to move simply to OAuth 2.0.


Alternative 2: OAuth 1.0a - Create a Comms Proxy.

In some cases, the desktop or mobile device may only integrate a few Xero endpoints (example, pushing an invoice), so creating a webservice which manages these maybe appropriate. Creating a Comms Proxy will comprise the following 2 elements:

  • An initial connection mechanism - this should link a specific instance (eg Device ID/Hardware ID/Software Licence ID) from the desktop or mobile app to the connection to the Xero Org. This connection could be established by passing this instance info as a parameter to an initial connection website from the app, then storing that parameter and the associated session and token information. This will implement the RequestToken and callback URL to get a valid access token.
  • Creating your own Webservice that uses the initial connection information stored above to communicate to the specific Xero instance. Each of the API calls supported between your desktop or mobile app and the Webservice is defined by you and then this data is transposed into one or more Xero API calls. An example might be sending an array of Invoice objects where the Invoice object is sent to the Webservice as a serialised XML object from your app, and then the Webservice maps the object to a Xero Invoice object.
Please note that the webservice should have its own security verification to validate the UniqueID - but this is beyond the scope of this document

The advantage of the comms proxy is that the Webservice manages all the comms and token management without any knowledge of the underlying desktop or mobile solution and importantly, the certificate file is not stored on device. This may simplify the complexity of the desktop or mobile application as the Webservice manages the majority of the delivery to Xero. It simplifies the logic associated with token refreshes as the Webservice can use semaphores, critical sections or singleton classes to guarantee multi-threaded access to a single org is maintained.

An example of the flow to initiate and setup:

Once communication and setup have been done, the desktop/mobile application can look at the workflows that will interact with the Xero API and design their Webservice to make calls on behalf of the mobile/desktop application based on their workflow needs; some examples might be:

  • A point of sale system passing through end-of-day/end-of-shift data (see example below).
  • A medical practice management software passing through individual invoices as well as any payments.
  • A payroll system which needs to push through employee timesheet information or Acc Payable for the wages for a pay period.