xoauth

README

XOAuth

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

Supported grant types

• Authorisation code
• PKCE

Installation

Download the binary for your platform:

• Linux
• Mac OS
• Windows

You can run the binary directly:

./xoauth

Or add it to your OS PATH:

Mac/Linux

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

Windows

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

Quick start

Prerequisites

• 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]

Command reference

Setup

Creates a new connection

xoauth setup [clientName]
# for instance
xoauth setup xero

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

add-scope

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

remove-scope

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

update-secret

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!

List

Lists all the connections you have created

xoauth list

Flags

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

xoauth list --secrets

Delete

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

xoauth delete [clientName]

Connect

Starts the authorisation flow for a given client configuration

xoauth connect [clientName]
# for instance
xoauth connect xero

Flags

--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

Token

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

xoauth token [clientName]

Flags

--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

Global configuration

Changing the default web server port

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

# for instance
XOAUTH_PORT=9999 xoauth setup

Troubleshooting

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.

Entries in the OS Keychain

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

Contributing

• PRs welcome
• Be kind