The Xero API provides feature-rich APIs for app partners to expose functionality that Xero does not provide, or features that enhance the Xero experience. The mechanism that secures communication between Xero and our app partners relies on secure transport, comprising TLS, and secure authenticated data delivery using OAuth 1.0a.
To further strengthen security of our subscribers’ sensitive financial data, from the 30th of June 2018 Xero will be deprecating the use of TLS 1.0 for any application communicating to any Xero API product. After this date, all applications communicating with Xero products must use TLS 1.1 or above. While it isn’t mandatory, we recommend applications upgrade to TLS 1.2 as the Xero API already has support for this.
The below information is relevant for Xero’s private, public or partner apps. If you’re a Xero subscriber, refer to information on our blog.
There are a number of drivers for change, but the primary ones are:
Vulnerabilities in TLS 1.0 - While Xero uses two layers of data encryption, at the transport and presentation layers, there are no fixes or patches that are able to address the underlying vulnerabilities with one of these security mechanisms. These vulnerabilities were addressed in TLS 1.1
Operating System, Development tools and Browser Support - While the Xero API’s are unaffected by the underlying transport layer, the operating systems, development tools/libraries and browsers have also needed to support TLS 1.1 and more recently TLS 1.2. Xero’s API infrastructure has supported TLS 1.0/TLS 1.1/TLS 1.2 for quite some time, but because communication is usually instigated from the app partner connecting and negotiated from the connection request, the app must be modified to support the higher version of TLS.
Xero will be completely deprecating TLS 1.0 on 30th June 2018, with no extension possible. This will impact private, public and partner applications and because Xero does not have the source code for every app that connects to the Xero API, the changes need to be made by the developers of those applications.
For most applications upgrading from TLS 1.0 will require upgrading both the underlying framework or libraries that the application relies on. While not mandatory, we recommend any applications that require upgrading from TLS1.0, move to TLS 1.2.
As discussed in this previous document on our developer blog, to support TLS 1.2, changes to the operating system or runtime environment are required. The following are known to support TLS 1.2, however these are guidelines and the reader will need to validate the required changes:
JDK v7 onwards
.Net Framework 3.5.1 onwards (.Net 4.5 natively supported TLS1.2, and Microsoft released a package to support TLS 1.2 in 3.5.1, available here).
Windows 7 onwards
Windows Server 2008 R2 onwards
Most common Linux distributions rely on OpenSSL
An upgrade to TLS 1.1 or TLS 1.2 requires changes to the application to support the newer versions of TLS. What you’re required to do depends on whether you are using the application, own the source code or use a 3rd party library / connector to communicate with the Xero API. Each scenario is explained in detail below - if unsure, please refer to the types of applications that the Xero API supports.
As identified above, the app is generally the instigator of communication with Xero. When communication is established, a negotiation between security and encryption supported by both the client and server occurs during the initial phase. For the most part this negotiation is buried deep inside the libraries, frameworks and networking of operating systems that your applications rely on.
While the libraries, frameworks and networking can provide the ability to use the newer versions of TLS, their baseline may default to using the older version (TLS 1.0 in this case) and need to have small code changes in order to support the more recent versions of TLS 1.1 and TLS 1.2.
In order to support these newer versions of TLS upgrades may be required to entire libraries and frameworks and deployment of an existing app. Please review the Q & A section below as it may provide additional resources / information to reduce the amount of effort required.
There are a number of private applications that connect to Xero. These solutions may be bespoke systems written by custom integrators, in-house developers or third party solutions which only connect using the private application type. Additionally, your application may connect via a 3rd party library or connector that is not supported by either Xero’s supplied SDKs or community backed SDKs.
In both cases, it is important that you make the original developer aware of the Xero changes to TLS requirements as soon as possible. Unfortunately, Xero may not have been able to get in contact to the original developer directly as they may have developed their solution without requiring any assistance from Xero.
If you or your company are using a Xero organisation and are unsure whether you have any applications which are connecting to Xero, you can see these under Settings->General Settings->Connected Apps. If you are in doubt, you can also send this list to firstname.lastname@example.org along with your Xero organisation name.
Q: How can I test if my App uses the right TLS version? We’ve set up a test URL for you to test your app. if you can make successful requests to https://api-tls.xero.com then your integration will work after we make the changes on June 30
Q. Where do I find a list of Xero supported SDKs? The current list of Xero supported SDKs is available here.
Q. Will I need to Recertify my Application with Xero? Xero does not require you to recertify your application if you are already a certified app partner.
Q. I have a partner application already but need a development partner application to make these changes without disrupting customers. Can I have a dev partner app? If you create another public app with a “-dev” suffix and send an email to email@example.com requesting that be upgraded to partner for TLS purposes. For example, if your original app is called MyInvoice, create MyInvoice-dev.
Q. I’m using a Xero SDK will these be upgraded to support TLS 1.1 or TLS 1.2. ? Xero supported SDKs will be progressively updated to support the newer versions of TLS. At this stage, there is no defined timeline for each SDK supported by Xero to be upgraded. Any deprecated SDKs developed by Xero are unlikely to be upgraded to support newer versions by Xero but as the source is provided for these, a developer may do this themselves.
Q. I’m using a community Xero SDK, will these be upgraded to support TLS 1.1 or TLS 1.2. ? You may take the community SDKs and upgrade them to support the newer TLS versions and use them in your application or assist the community by submitting your changes for all who will use the community SDKs in future.
Q. Can Xero help me upgrade my code? Your local Developer Evangelists are able to provide high level assistance, but unfortunately are not able to write code for you.
Q. Are there additional ways I can get assistance? Xero has created a community page on Xero for developers to ask questions about TLS 1.0 deprecation. This community page will allow developers, both from the Xero API teams and external to Xero to share knowledge and learnings in a collaborative way.
If you still require some further details on what is required, please contact your local Developer Evangelist in your region or email firstname.lastname@example.org who will be able to assist.