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.
- Generate and download Xero signing certificates
- Generate PFX
- Get Entrust root certificate
- Update your API integration
- Install certificates to Azure
- Configure Azure roles
Generate and download Xero signing certificates
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).
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!
Get 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
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
.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.
- Xero, become a partner – http://developer.xero.com/partner/#become-a-partner
- Xero, getting started guide – http://developer.xero.com/documentation/getting-started/getting-started-guide/
- Xero, Entrust Client SSL Certificate – https://developer.xero.com/documentation/advanced-docs/partner-app-entrust-certificate-instructions/
- Microsoft Azure – Associate a Certificate with a Service – https://msdn.microsoft.com/library/azure/gg465718.aspx
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.