Help Center
Overview
Interactively prompts a user to login to the Xero finance package, grant access for a third-party (i.e. another script) to access the data, then saves two tokens issued by Xero. The tokens can be used by other scripts to retrieve data from Xero, e.g. for reporting purposes.
Where to find it
Name of script: SpeakeasyGetXeroTokens.ps1
This script handles the Xero authentication process. Once completed successfully, that enables programmatic access to data held in the Xero finance package, which is used by Speakeasy for recording financial transactions.
The script runs via a user’s desktop, not via Azure.
The script can be viewed and edited by opening the SpeakeasyGetXeroTokens.ps1 script via the following link: PowerShellScripts. However, it is easier and is recommended that this script be opened by first syncing the Speakeasy IT…General…Files Teams folder and opening the file via File Explorer. The file would be located under C:\Users\{yourUserName}\Bury Speakeasy\Speakeasy IT – General\PowerShellScripts
How it Works
The Xero authentication process is quite complex as it uses the new OATH2 standard. Xero provide an overview in the following page: Xero guide to PKCE OAUTH2 flow. For the script to work correctly, a new application has to be registered in Xero – see the “Xero App Registration” in this next section of this guide for more information.
The SpeakeasyGetXeroTokens.ps1 script works as follows:
- A user executes the PowerShell script SpeakeasyGetXeroTokens.ps1, usually from PowerShell ISE which is set to run as an administrator.
- The script makes an attempts to login to Xero via a browser – the user is presented with a page which prompts for a Xero username and password – the accounts and login details can all be found in BitWarden.
- The user should use BitWarden to login using their details. If the user does not have their own account, Paul Cashmore’s Xero details in BitWarden can be used to login
- If login is successful, the user will be prompted to confirm that programmatic access to Xero data will be allowed. Simply click the “Allow Access” button. The Powershell script has been configured to ask for the minimum possible permissions – i.e. read-only access to reports data. This can be modified in due course if other access is required – the script includes a commented out line showing some of the other permissions that can be requested.
- Once access is granted, two tokens – an access token and refresh token – are returned to the SpeakeasyGetXeroTokens.ps1. The access token will expire after 30 minutes, unless a token refresh is requested. The refresh process is described here: Refreshing of Xero Tokens.
- The SpeakeasyGetXeroTokens.ps1 script then stores the tokens in encrypted form in Azure Automation variables. All Azure automation variables can be seen via this link: Speakeasy Azure Automation Variables. The access token is stored in a variable called SpeakeasyXeroAccessToken and the refresh token is stored in a variable called SpeakeasyXeroRefreshToken.
- The script then completes.
When testing Powershell scripts that make use of Xero tokens, it can be easier to run these locally before moving them to Azure runbooks. However, it is not possible to retrieve the value of an encrypted Azure Automation variable via a desktop-executed Powershell – they can only be retrieve via a Azure runbook script. Therefore, to make the development process easier, the SpeakeasyGetXeroTokens.ps1 script also the access token in a file on the user’s desktop – this allows a user to use the token locally for 30 minutes before it expires (the token refresh process, outlined in the section below, only refreshes the Azure Automation variables).
Add a new section here