Connecting to Xero
Xero specifies three types of applications that can connect to Xero APIs: public, private, and partner. You can use the driver to connect as any of these application types.
Selecting an Application Type
Following are details on how to select the application type you need:
- Public applications enable the quickest way to get started using the driver. You can connect without further configuration, as the driver is already registered as a public application.
However, public applications require you to reauthenticate every 30 minutes. In the public application auth flow, detailed in the next section, users log into Xero and grant the driver permissions through a web browser.
Developers may wish to register their own public application to customize the authorization prompt when users log into Xero: See Advanced Settings to create your own public application before following the authentication guide below.
- Private applications enable long-term access to an organization, without requiring you to authenticate through the browser.
A private application is linked to a single organization; you need access to the organization to create a private application.
To set up this flow, you need to create a Xero developer account and register a private application on the Xero developer portal. See the authentication guide below to create one and connect.
- Partner applications are not bound to an organization and enable long-term access. Partner applications follow the same browser-based auth flow as public applications, without requiring users to reauthenticate every 30 minutes.
To set up this flow, you upgrade a public application after becoming a partner with Xero: See Advanced Settings for a guide to create an application. You can then follow the steps in the next section.
Authenticate to Xero with a Public or Partner Application
Set the following to authenticate to Xero:
|ConnectionProperty||Public App Value||Partner App (or Custom Public App) Value|
|XeroAppAuthentication||Leave blank to use the default value||Set this to PARTNER or PUBLIC.|
|OAuthClientId||Leave this blank||Set this to the consumer key in your app settings.|
|OAuthClientSecret||Leave this blank||Set this to the consumer secret in your app settings.|
|CallbackURL||Leave this blank||Set this to http://localhost.|
Authenticate to Xero with a Private Application
To connect using Xero private application authentication, there are three basic steps that need to be completed:
- Create an X.509 digital certificate.
- Register an application on the Xero developer portal.
- Configure connection properties.
Create an X.509 Private/Public Key Pair
Private application authentication uses a private/public key pair to verify the identity of the connecting application. You upload the public key to Xero when you create the application, and you specify the private key when you connect with the driver.
To obtain the key pair, you need to obtain a digital certificate from a certificate authority or generate a self-signed certificate. One way to generate a self-signed certificate is to use the CData Certificate Generator application. Alternatively, you can use other tools such as OpenSSL or Microsoft’s IIS.
You can follow the steps below to generate a self-signed certificate with OpenSSL. The following steps must be run in a command prompt with administrator access.
- Create a private key PEM file. The command below creates a private key using 1024-bit encryption:
openssl genrsa -out privatekey.pem 1024
- Set CertificateStorePassword to the private key’s password.
- Set CertificateStoreType to PFXFILE.
Note: In addition to .pfx files, the driver supports other major formats.
- Create a public key certificate in the X.509 format. The command below sets the certificate validity to 365 days:
openssl req -new -x509 -key privatekey.pem -out publickey.cer -days 365
Register Your Application
After generating an X.509 digital certificate, follow the steps below to register an application on the Xero developer portal and upload the public key:
- Log in to the Xero developer portal.
- Click My Applications -> Add Application.
- Select the Private option.
- Enter an application name. This is only for identifying the application in the Xero developer portal.
- Select the organization that the application can access.
- Either paste the base-64-encoded public key certificate in the text box or upload a valid X.509 certificate (.cer) file.
This process will generate and display the OAuth client credentials, a consumer key (OAuthClientId) and consumer secret (OAuthClientSecret).
Configure Connection Properties
After setting the following properties, you are ready to connect:
- XeroAppAuthentication: Set this to PRIVATE.
- OAuthAccessToken: Set this to the consumer key obtained when you register.
- OAuthClientId: Set this to the consumer key obtained when you register.
Note: You must set both this property and OAuthAccessToken.
- OAuthClientSecret: Set this to the consumer secret obtained when you register.
- CertificateStoreType: Set this to the format of the private key certificate. There are a variety of options. For example, PFXFILE.
- CertificateStore: Set this to the store of the private key certificate. There are a variety of options depending on the CertificateStoreType set. For example, C:\privatekey.pfx.
- CertificateStorePassword: Set this to the password used to load the private key certificate.
- CertificateSubject: Set this to the subject of the private key certificate. For example, “CN=CData”.
- InitiateOAuth: Set this to “OFF” in the Other property. For example, “Other=InitiateOAuth=OFF”.