Xero Partner SSL configuration in Azure

Recently we became a Xero partner, which meant that we had to go through the process of converting our public API application to a partner one, which involves some custom SSL certificates which can easily trip you up in an Azure environment. I’ll be going through the steps we took to make this work as the exact process can be a little tricky.

  1. Generate and download Xero signing certificates
  2. Generate PFX
  3. Get Entrust root certificate
  4. Update your API integration
  5. Install certificates to Azure
  6. Configure Azure roles

Generate and download Xero signing certificates

Certificate list

I’m going to assume that you have already got your self-signed certificate and have downloaded the certificate provided by Xero as this is all standard process when becoming a Xero partner. If you do not already have these go and get them, I’ll wait.

Right, you should have 2 certificates now, 1 from the Xero download (renamed to Timestamp Xero Entrust Certificate.p12) and the self-signed certificate (Timestamp Xero Signing.cer and Timestamp Xero Signing.pfx in our case).

Generate PFX

The next step is to create a PFX file that can be imported and used within your worker / web roles. To do this import the Xero-downloaded .p12 certificate (put it in your personal store to allow local testing) using certificate manager (certmgr.msc) and export with a private key. Make sure you pick a strong password, and make sure not to lose it as you will need it again later!

Certificate store

Get Entrust root certificate

Entrust root certificate

An additional certificate is required when running from Azure, the Entrust Root Certificate, which can be downloaded from https://enrollcompriv.managed.entrust.com/cda-cgi/clientcgi.exe?action=start. Download the .cer file by clicking the Install link under CA Certificates. In our case we have renamed it to Timestamp Xero Entrust Root.cer instead of clientcgi.cer.

Update your API integration

Once you have all the required certificates you are ready to change your code to access the Xero API as a partner. When we started our integration the new .NET SDK (Xero-Net) was not available, so the code below is for the older SDK (XeroAPI.Net), although the same patterns should apply:

In the above code we are creating an OAuthSession of type XeroApiPartnerSession. During development you would have had this be created as a XeroApiPublicSession with similar parameters. The difference here is you will be using the certificates and not a client key & secret.

Install certificates to Azure

Once the above has been completed and you can successfully access the Xero API using the certificates in partner mode it is time to move on to configuring Azure, which involves 2 steps. The first is to upload the 3 certificate from earlier (2 .pfx and 1 .cer) to your web or worker role within the Azure portal, the second to configure the cloud service to install these certificates as required.

Upload the certificates to your Azure Cloud Service by going to the certificates tab, clicking upload at the bottom and selecting the 3 certificates, entering your passwords for the PFX files from earlier.

Configure Azure roles

Once that is done you need to configure these certificates in your cloud service. You can do this by modifying the .cscfg and .csdef file for your cloud service:

Now that you have got your cloud service configured it is time to deploy and test your changes. Hopefully this is as easy as setting off a new build in your CI build system. If not, why not look at that as your next step. Repeatable builds is a must for any project, but even more so with the complexities of a cloud development environment.

Resources

Update 19th June 2015

This post originally contained incorrect information about where the Entrust Root Certificate came from, stating it was in the download from Xero. This has been corrected with the correct link and instructions about where to get this certificate from.

Adam Barclay

  • Do you have any guidance on using the Partner certificate with Azure Web Apps?

    • Hi Jacob. Unfortunately we do not.

      We attempted a migration from cloud service to web apps at the end of last year but deemed it impossible due to restrictions in the web app model for handling certificates.

      We found no way of getting the partner certificate + chain to load in Azure in a way that would allow communication with Xero.

      Unless things have changed the only possibility is to have a separate cloud service that handles Xero communication and the web app can communicate through that as a proxy

      • I’ve had a similar experience and have been working with MS support on seeing if there is a way to get this to work. I’ve actually managed to debug right down into SecureChannel (http://referencesource.microsoft.com/#System/net/System/Net/_SecureChannel.cs,539) to see why it won’t select an invalid client certificate even if you manually specify it.

        MS support have suggested using a client certificate that does chain back to a certificate that is already trusted in Azure….Not really a solution.

        • From memory I believe this issue exists only in .NET on Azure, not with PHP. I’m not sure that’s quite the option to go with though 🙂

          Thanks for the extra info, interesting to hear MS have no real solution still. I never got quite as far as debugging down that far, but had tried many different configurations.

          It’s a shame, because we would like to convert to using Web Apps but this, and the inability to use HTML-to-PDF converters because of GDI+ restrictions (I believe) stops us swapping without significant effort

View pricing & sign up 14-day free trial