pizauth: another alpha release

Recent posts
What Factors Explain the Nature of Software?
Some Reflections on Writing Unix Daemons
Faster Shell Startup With Shell Switching
Choosing What To Read
Debugging A Failing Hotkey
How Often Should We Sharpen Our Tools?
Four Kinds of Optimisation
Minor Advances in Knowledge Are Still a Worthwhile Goal
How Hard is it to Adapt a Memory Allocator to CHERI?
"Programming" and "Programmers" Mean Different Things to Different People

Blog archive

A few weeks back I made the first alpha release of pizauth, a simple program for requesting, showing, and refreshing OAuth2 access tokens. I’ve been pleasantly surprised at the number of people who’ve tested pizauth since then, mostly successfully. Inevitably, pizauth hasn’t quite worked perfectly for everyone, so I’m making available the next alpha release, 0.1.1. One new feature, and one portability fix, are particularly worth mentioning.

Running pizauth on a remote machine

A valid use case for pizauth is to run on a remote machine (e.g. to download email in a cron job on a server), but for authentication to happen locally. I had assumed, but hadn’t tested, that using pizauth with ssh -L would work. Indeed, it did work, but it required users to work out what port that pizauth’s HTTP server (a vital part of the OAuth2 authentications sequence) was listening on. Users could discover the port number by carefully examining the authorisation URL:


Did you spot the port number in that ASCII maelstrom? I wouldn’t blame you if you didn’t! (Answer in the footnote [1].) Just to make life a bit more miserable for users, the port number is randomly generated by the operating system every time pizauth starts.

I’ve therefore added a global http_listen configuration option which allows users to force pizauth’s HTTP server to listen on a specific IP address and port. For example if you want it to listen on port 12345:

http_listen = "";

With this, it’s now much easier to use pizauth on a remote machine [2]. In essence, after fixing the port number [3] with http_listen, you run pizauth server on the remote machine. On your local machine you then open an SSH tunnel to the remote machine (note that you have to listen on the same port locally and remotely, in this example 12345):

ssh -L <remote-machine-name>

When pizauth show is executed on the remote machine, one then copies the authorisation URL over to a browser in the local machine, and authenticates as normal. Once pizauth displays “pizauth processing authentication: you can safely close this page.” in the browser, the SSH tunnel can be closed. As and when pizauth requires reauthentication (e.g. because the refresh token has expired), one follows the same “open an SSH tunnel, authenticate, close the SSH tunnel” sequence.

OS X port

The first alpha release didn’t compile on OS X because the Unix daemon function leads to a deprecation warning at link time which was upgraded to an error. Fortunately Eddie Antonio Santos intergrated a simple fix for OS X, which at least two other people have subsequently confirmed works well.

Client IDs and secrets are outside pizauth’s control

The most common complaint (or plea) I’ve heard is from people who haven’t been able to find the right OAuth2 client IDs and secrets for their setup. Regrettably, there’s absolutely nothing I can do about this: it’s up to the administrators running each OAuth server as to how they handle this.

Some administrators explicitly list the valid client IDs and secrets (or allow users to generate their own) but many administrators incorrectly assume that client IDs and secrets increase security, and prevent users from finding out valid values. The latter case implicitly creates two classes of users. The first class are shut out from vital services. The second class, using various means that their (incorrectly paranoid) administrators might not approve of, are able to find valid client IDs and secrets which work with their servers.

I hope that a future revision of the OAuth standard will a) only require one of client ID or secret b) made that single setting optional and strongly suggest that it is only used for unmonitored server applications. Until then, all I can do is sympathise with users who can’t find valid client IDs and secrets.

Testing is still appreciated!

I’m gradually gaining confidence that pizauth’s features and user-facing interface aren’t entirely stupid. I hope that even more people will test pizauth to see if there are any other deficiencies that need addressing!

Newer 2022-10-20 08:00 Older
If you’d like updates on new blog posts: follow me on Mastodon or Twitter; or subscribe to the RSS feed; or subscribe to email updates:






Using this option also guarantees that pizauth won’t listen on a random port that you expected a later program to listen on instead.

Using this option also guarantees that pizauth won’t listen on a random port that you expected a later program to listen on instead.


I’m not yet aware of a good use case for listening on an IP address other than, but that might be narrowness of thinking on my part.

I’m not yet aware of a good use case for listening on an IP address other than, but that might be narrowness of thinking on my part.


(used only to verify your comment: it is not displayed)