Get OpenId Connect tokens from the command line

XOAuth provides a simple way to interact with OpenId Connect identity providers from your local CLI. Many OIDC providers only support the Authorisation Code grant - and that means running a local web server to receive the authorisation response, or using something like Postman. These can be tricky to fit into a scripted workflow in a shell.

This tool saves you time, by:

• Helping you configure clients and manage scopes
• Storing client secrets securely in your OS keychain
• Managing a local web server to receive the OpenId Connect callback
• Opening a browser to allow users to grant consent
• Using metadata discovery to build the Authorisation Request
• Verifying the token integrity with the providers's JWKS public keys
• Piping the access_token, id_token and refresh_token to stdout, so you can use them in a script workflow

• Authorisation code
• PKCE (coming soon to the Xero API)

Download the binary for your platform:

• Linux
• Mac OS
• Windows

You can run the binary directly:

./xoauth

Or add it to your OS PATH:

mv xoauth /usr/local/bin/xoauth && chmod  x /usr/local/bin/xoauth

Alternatively you can use brew on Mac OS:

brew tap xeroapi/homebrew-taps
brew install xoauth

The easiest way to get started on Windows is to use scoop to install xoauth:

scoop bucket add xeroapi https://github.com/XeroAPI/scoop-bucket.git
scoop install xoauth

• An OpenId Connect Client Id and Secret
• A redirect_url of http://localhost:8080/callback configured in your OpenId Connect provider's settings (you can change the port if the default doesn't suit).

Once the tool is installed, and you have configured your client with the OpenId Provider, run these two commands to receive an access token on your command line:

xoauth setup [clientName]
xoauth connect [clientName]

Creates a new connection

xoauth setup [clientName]
# for instance
xoauth setup xero

This will guide you through setting up a new client configuration.

Adds a scope to an existing client configuration

xoauth setup add-scope [clientName] [scopeName...]
# for instance
xoauth setup add-scope xero accounting.transactions.read files.read

Removes a scope from a client configuration

xoauth setup remove-scope [clientName] [scopeName...]
# for instance
xoauth setup remove-scope xero accounting.transactions.read files.read

Replaces the client secret, which is stored in your OS keychain

xoauth setup update-secret [clientName] [secret]
# for instance
xoauth setup update-secret xero itsasecret!

Lists all the connections you have created

xoauth list

--secrets, -s - Includes the client secrets in the output (disabled by default)

xoauth list --secrets

Deletes a given client configuration (with a prompt to confirm, we're not barbarians)

xoauth delete [clientName]

Starts the authorisation flow for a given client configuration

xoauth connect [clientName]
# for instance
xoauth connect xero

--port, -p - Change the localhost port that is used for the redirect URL

# for instance
xoauth connect xero --port 8080

--dry-run, -d - Output the Authorisation Request URL, without opening a browser window or listening for the callback

# for instance
xoauth connect xero --dry-run

Output the last set of tokens that were retrieved by the connect command

xoauth token [clientName]

--refresh, `-r' - Force a refresh of the access token

# for instance
xoauth token xero --refresh

--env, -e - Export the tokens to the environment. By convention, these will be exported in an uppercase format.

[CLIENT]_ACCESS_TOKEN
[CLIENT]_ID_TOKEN
[CLIENT]_REFRESH_TOKEN

# for instance
eval(xoauth token xero --env)
echo $XERO_ACCESS_TOKEN

You can modify the default web server port by setting the XOAUTH_PORT environment variable:

# for instance
XOAUTH_PORT=9999 xoauth setup

Run the doctor command to check for common problems:

xoauth doctor

xoauth stores client configuration in a JSON file at the following location:

$HOME/.xoauth/xoauth.json

You may want to delete this file if problems persist.

Client secrets are saved as application passwords under the common name com.xero.xoauth

• PRs welcome
• Be kind