Upgrading your apps to support TLS 1.2

What’s happening?

We recently announced that QuickBooks Online apps will be required to upgrade to TLS 1.1 or above by July 31, 2017 to align with industry best practices for security and data integrity.

As of December 31, 2017, the required version will be TLS 1.2 or higher.

Steps for upgrading to TLS 1.2 vary for different coding languages. See details below for the three languages for which we offer SDKs: PHP, Java and .NET.

PHP:

Are you using the PHP SDK?

Action required:

Yes

No action required.

The PHP SDK is on PHP 5.7. It uses CURL for making API calls and supports CURL version 7.54.0, which has default support for TLS 1.3. Refer to the Appendix.

No:

Verify that your PHP version supports CURL version 7.34.0 or newer:

1. Use php -i to check for modules that your PHP has installed.

2. Find the curl section. You will see something like:

o CURL

o cURL support => enabled

o cURL Information => 7.34.0

PHP version	cURL version	Default TLS version
5.6	7.34.0	TLS 1.2
5.7	7.54.0	TLS 1.3

JAVA:

Are you a Java developer?

Action required:

Yes

Depending on the Java version of your application environment you may or may not require changes to support TLS1.2. Please see the table below for details.

See the Appendix for updating and troubleshooting instructions.

Java version	TLS support	Action Required
8	Available	No action required.
7	Available	Yes. You must explicitly enable TLS 1.2.
6	Available	Maybe. Java 6 supports TLS 1.2 in versions 6u115 b32 and above. If you are on a lower version, upgrade to a higher version and explicitly enable TLS 1.2.
5 or earlier	No support	Yes. Upgrade to Java 6 or higher, preferably Java 8.

.NET:

The current version of the .NET SDK (v3.2.1) uses .NET Framework 4.0. We are migrating the .NET SDK (.NET SDK for QuickBooks Online V3.2.1) to Framework 4.6.1 to proactively support TLS 1.2.

After the mid-August 2017 .NET SDK release, the SDK will only support Framework 4.6.1.

Are you using the .NET SDK?

Action required:

Yes

If you are a .NET SDK developer, move your .NET application to Framework 4.6.1 and the latest SDK by Dec 31, 2017 to support TLS 1.2.

If you are not using the .NET SDK, move your .NET application to Framework 4.6.1 by Dec 31, 2017 to support TLS 1.2.

Refer to the Appendix.

.NET Framework	Default TLS version supported	Timing
4.0	1.1	July 31, 2017
4.5	1.1 is default, can be set to 1.2	July 31, 2017
4.6.1	1.2	December 31, 2017

What do you need to do for your .NET application?

To minimize the impact to our .NET developer community, we have prepared a migration plan to .NET Framework 4.6.1.

To move your .NET application to framework 4.6.1:

Open your project properties by right-clicking it.
Change the Target Framework to 4.6.1 under the Application tab.

Upgrade your .NET SDK to the latest version by mid-August. See the release notes here.
Use the NuGet Package Manager for this upgrade.
- Note: Any developer using the .NET OAuth 2.0 lib may already be using Framework 4.6.1, as this lib supports Framework 4.6.1, at a minimum.
Resolve any errors in your application that may arise from using the latest minor version.
The minor version mechanism is designed to be backward-compatible, but any hard-coded API response mapping can cause errors in your code. For example, your app may have a database mapping for an old QuickBooks Online schema if you haven’t updated the .NET SDK in a long time, and might not support new fields in newer minor versions.
Check the release notes and add support for the new fields in your code.
- Note: Minor versions provide support for additional new fields in the QuickBooks Online API schema. You can read more details about minor versions here. This table provides a mapping of all .NET SDK versions and the supported minor versions.

.NET SDK version	Highest supported minor version
V3DotNetSDK2.0.1	NA
V3DotNetSDK2.0.2	NA
V3DotNetSDK2.0.4	NA
V3DotNetSDK2.0.5	NA
V3DotNetSDK2.1.0	NA
V3DotNetSDK2.1.1	NA
V3DotNetSDK2.2.0	1
V3DotNetSDK2.3.0	2
V3DotNetSDK2.4.0	3,4
V3DotNetSDK2.5.0	5
V3DotNetSDK2.6.0	6
V3DotNetSDK2.7.0	7
V3DotNetSDK2.8.0	8
V3DotNetSDK2.9.0	8
V3DotNetSDK3.0.0	9,10,11
V3DotNetSDK3.1.0	9,10,11

Benefits of moving to the latest version:

Your .NET application will be ready to support TLS 1.2, a more secure communications method than earlier versions.
Your application will upgrade to the latest minor version of the QuickBooks Online API schema and can take advantage of the added features and fields of the API.
Any .NET applications integrating with financial data along with QuickBooks Online APIs will get some lead time to meet the upcoming PCI security standards TLS 1.2 migration dates.

How to test if your application is connecting to TLS 1.2 URL successfully after the required changes:

Make an HTTP call to this URL from your code https://tlstest.intuit.com.
It should give you a ‘success’ response.

Make an HTTP call to this URL from your code https://tlstest.intuit.com/1_2.json

It should give you the following json response-

{
“status”: 200,
“message”: “Success!”
}

Summary of Dates:

Now: Update the .NET Framework to 4.6.1 and update to the latest .NET SDK version, which supports .NET Framework 4.6.1. Watch the Release notes for the exact date of next .NET SDK release.
December 31, 2017: Update the .NET SDK to the latest version, which supports .NET Framework 4.6.1.

Appendix-

PHP-

https://curl.haxx.se/libcurl/c/CURLOPT_SSLVERSION.html

JAVA –

.Net-

Posted

August 3, 2017

News, QuickBooks API, QuickBooks Online, Technical Tips

Lisa Rathjens

Tags:

Comments

20 responses to “Upgrading your apps to support TLS 1.2”

Dean

September 29, 2017

Nimisha, perfect! Had a hard time finding .NET examples on TLS 1.2, artice was just what we needed! our app is https://apps.intuit.com/ontheclock / https://www.ontheclock.com Thanks, Dean

Reply
Jibin

October 4, 2017

We are using IppDotNetSdkForQuickBooksApiV3.2.2.0 and .net framework 4.0, our question is what will happen if we wont update our application to .net frame work 4.6 and wont upgrade to latest .Net SDK version. Did it cause any error? Did this affect our current functionality?

Reply
1. ServicePal
  
  October 19, 2017
  
  Where did you get IppDotNetSdkForQuickBooksApiV3.2.2.0 ?
  I don’t see that on Nuget.
  https://www.nuget.org/stats/packages/IppDotNetSdkForQuickBooksApiV3?groupby=Version
  
  Reply
  1. nimisha
    
    October 31, 2017
    
    They must have been on it much earlier. Just looking for an upgrade.
    
    Reply
2. raleigh
  
  October 25, 2017
  
  i’ve basically the same question as Jibin. Our .NET app does set security protocol to => TLS 1.2. So is it necessary for us to move to latest framework and QB SDK?
  
  Reply
  1. nimisha
    
    October 31, 2017
    
    I believe I answered your query on support. Same answer as above
    
    Reply
3. nimisha
  
  October 31, 2017
  
  I believe I answered your query on support. The application which do not migrate to 4.6.1 or higher or do not make changes to 4.5 framework code for TLS1.2 will not be able to make QBO api calls.
  
  Reply
Joyce

December 4, 2017

Hello, how does this change affect .net desktop applications and what is the course forward?

Reply
1. nimisha
  
  December 4, 2017
  
  I replied on your ticket
  
  Reply
nimisha

December 4, 2017

Attention- Any devs looking for ways to test TLS1.2, please refer these steps for .Net SDK-
Please follow the steps mentioned here- https://developer.intuit.com/hub/blog/2017/08/03/upgrading-your-apps-to-support-tls-1-2
to make just an http call to this url- https://tlstest.intuit.com
Code example-

ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12; //Add this just to be sure to use TLS1.2
var result = string.Empty;
using (var webClient = new WebClient())
{
result = webClient.DownloadString(“https://tlstest.intuit.com”);
}

Download Fiddler from Google and run it alongside your code to log raw requests and responses along with URL and headers to confirm that your calls are using TLS1.2 protocol. If the calls works for the url above then your QBO api sandbox/prod calls will also work once the change goes live after Dec 31st, 2017. I have also added how the fiddler logs would look like once you test your code.

When you download Fiddler, open it, go to Tools > Fiddler Option > Enable (Tick Mark) Capture HTTPS connects > Do not Enable Decrypt Https traffic (https://textslashplain.com/2015/10/12/viewing-https-handshakes-in-fiddler/). That’s it. No other setting is required. The .NET localhost is by default captured in Fiddler, so after you have enabled https traffic in Fiddler just run your code. (Fiddler should be open.) You will see requests and responses logged in Fiddler.

You should set ‘decode the raw request body’ by clicking on the yellow bar in Fiddler. Then go to the File menu on top, select Save all session > Save the fiddler session. A .saz file is created, which can be viewed later.

Reply
nimisha

December 4, 2017

Additional FAQs-
We have a .NET Framework 4.5, but we do set the security protocol to TLS1.2:

ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;

Our internal servers already require TLS1.2 and this was sufficient to allow the app to communicate with them.
I have verified that I am able to hit the test URLs below successfully from within the app as currently configured.
Nimisha- This should be just enough that your app can communicate with TLS url we have given and you already have 4.5 framework with the above config line for protocol set. But, this would also mean that you will not be able to upgrade the .Net SDK to 4.0.0. version as it now supports 4.6.1 or higher only.

My questions are:
1) Is the fact that hitting these test pages succeeds sufficient proof that it will work? It seems so based on what I’ve read, but we just want to be sure.
Nimisha- Yes, that is enough.

2) Is there another reason besides TLS compatibility that we need to update to the latest SDK (and hence .NET 4.6.1)? There are significant hurdles to doing this so we want to avoid it if possible.
Nimisha- TLS1.2 is just one aspect. We want devs to also move to the latest version of the SDK as .Net SDK 4.0.0 supports the latest schema/minorversion(with new fields supported by the QBO service.) Thus using this TLS1.2 was an opportunity to also move our developers to use latest SDK along with TLS1.2. If you have some hurdles, then keep on using the existing SDK version you have but your api fields supported by that SDK are very old.
They will not break later on but just that you will not be using any updated api related changes.
So, you might want to rethink on that.

3) If hitting the test pages is not sufficient, how can we test whether the current app will work now, and if we need to update, whether the updated app will work prior to the change? Is there a fully functional test server that we can use to test with beyond just these test pages?
Nimisha- Just testing with the TLS url we have should be enough.

Reply
Ryan

December 6, 2017

I’m a bit confused about the verification that my app is going to work. I currently have a .Net Framework 4.5 application running with the 2.6.1 version of IppDotNetSdkForQuickBooksApiV3 and without doing anything if I run
ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;
var result = string.Empty;
using (var webClient = new WebClient())
{
result = webClient.DownloadString(“https://tlstest.intuit.com”);
}

It works fine. If that test verifies I’m ready to go then why would I need to change my .Net Framework or version of the Sdk API? If I do need to still upgrade is there some way to test that the api is going to work instead of testing a generic web request?

Reply
1. nimisha
  
  December 7, 2017
  
  I believe I already answered your ticket with details. Yes, this should be fine. Testing with TLS1.2 url is fine.
  
  Reply
2. nimisha
  
  December 22, 2017
  
  If you are able to make some api calls with the SDK and .Net 4.5 framework with the SecurityProtocolType.Tls12 code, can you send me some sample company ids by creating a support ticket on developer.intuit.com->help.
  I can check the companyid calls in the logs to make sure of the TLS version.
  
  Reply
John

December 6, 2017

I have a .NET desktop application that uses a template Intuit put up on GitHub when we first moved to the new API (about 4 years ago). So all I have to do is update my NUGET references, rebuild, and redeploy? For example, I use the code below to create an OAuthSession. Is that still good? The URLs are still OK too? Thanks
private IOAuthSession createDevDefinedOAuthSession(string consumerKey, string consumerSecret)
{
var oauthRequestTokenUrl = @”https://oauth.intuit.com/oauth/v1/get_request_token”;
var oauthAccessTokenUrl = @”https://oauth.intuit.com/oauth/v1/get_access_token”;
var oauthUserAuthorizeUrl = @”https://appcenter.intuit.com/Connect/Begin”;

OAuthConsumerContext consumerContext = new OAuthConsumerContext
{
ConsumerKey = consumerKey,
ConsumerSecret = consumerSecret,
SignatureMethod = SignatureMethod.HmacSha1
};

return new OAuthSession(consumerContext, oauthRequestTokenUrl, oauthUserAuthorizeUrl, oauthAccessTokenUrl);

}

Reply
1. nimisha
  
  December 7, 2017
  
  Make sure your .Net Framework target version is changed to 4.6.1 and then update the Nuget Package to latest .Net SDK 4.0.0.0. Build and test.
  
  Reply
alejandro

July 16, 2018

i can not make a web request to the url “https://tlstest.intuit.com/” to check if my connection is success

Reply
Naveen Pazhanivel

January 21, 2019

Hi,
I have a php API in the server with the version 5.4.45 and TLS 1.0 ,Do i need to upgrade both php(to latest) and TLS 1.0 to 1.2 ,Currently i was not able to connect to third party api because they no longer support the TLS 1.0. Please let me know.

Reply
Simon

January 25, 2019

Even if you use .Net Framework 4.6.1 in a console application it doesn’t set TLS 1.2 by default. You have to explicitly set it with:

System.Net.ServicePointManager.SecurityProtocol = System.Net.SecurityProtocolType.Tls12;

Reply
1. Nimisha Shrivastava
  
  January 2, 2020
  
  bhai karyu 6 to pan nahi thatu
  
  Reply