pizauth: HTTPS redirects

I’ve just released pizauth-1.0.6 which introduces one notable new feature: support for HTTPS redirects. New features sound good, but what does this actually mean? My experience is that the way OAuth2 works is sufficiently counter-intuitive that people often struggle to make sense of what it’s doing.

Here’s a very quick, simplified, summary of what OAuth2, and pizauth do [1]. OAuth2 lets you obtain a time-limited token which you can use to access a remote resource (e.g. the ability to send email): pizauth’s job is to get you such a token. If you ask pizauth for a token for a resource and a token isn’t already available, pizauth will create a URL which you then open in your local web browser. That URL will take you to the remote resource (e.g. your email provider) who will then ask you to authenticate yourself (i.e. login). Once you’ve successfully done so, the remote web page then needs to tell pizauth that you’ve been successful: it does so by redirecting you to an HTTP URL that’s actually pizauth running on your local machine.

This last part – i.e. redirection – tends to surprise people, but somehow the remote resource needs to communicate success (or failure…) to pizauth. Piggybacking off HTTP uses a well-known existing protocol that’s tolerated well by most networks — it’s quite a cunning solution to the problem [2].

All of the remote systems I tried when I was creating pizauth used plain HTTP URLs (indeed, always http://localhost/) for redirects. pizauth’s little HTTP server supported just enough for that, and no more.

I vaguely suspected that some remote system would want more than HTTP redirects, but didn’t know that they existed in the wild. Now there is such evidence, and a kind user has implemented support for HTTPS redirects (i.e. things like http://localhost) in pizauth.

The little HTTP server has been extended so that pizauth now listens for both HTTP and HTTPS redirects. That means that we immediately bump into the problem of HTTPS certificates. Anyone who’s set up an HTTPS website will surely have been baffled by the series of similar, but distinct, files one has to create to assuage the SSL gods — or, at least, I always manage to baffle myself when doing so. Fortunately, pizauth creates certificates automatically, so you don’t need to worry about doing so.

However, the price to pay for automatic certificate generation is that the certificates are self-signed: when your browser redirects you to a URL like https://localhost/ you’ll see a warning that the website isn’t trusted. To help you check that you’re correcting to the right HTTPS server, pizauth info now prints out the public key of its certificate:

$ pizauth info
    pizauth version 1.0.5:
      cache directory: /tmp/runtime-ltratt/pizauth
      config file: /home/ltratt/.config/pizauth.conf
    server running:
      HTTP port: 7470
      HTTPS port: 24004
      HTTPS public key: 04:70:57:B0:9A:B4:1C:F9:CB:2E:33:CB:71:D9:B1:7C:5C:6E:84:8F:25:66:F4:C8:1E:3F:41:F8:34:8D:2A:6A:3F:26:D9:A6:57:27:D0:B0:93:09:5B:50:70:D9:DD:1A:A0:DE:33:04:E1:A8:FB:C6:30:D2:92:B1:26:11:E5:75:B9

You can use that information to check that you’re connecting to pizauth’s HTTPS server. Different browsers let you see this information in different ways, but none of those that I’ve tested make it very hard to find. In case you’re really, really, paranoid, you can also see the ports of the HTTP and HTTPS servers: the redirect URL will also include a port (e.g. https://localhost:24004/) which you can double check against the output from pizauth info.

Finally, particularly if you’re only using HTTPS redirects, you might not want to run an HTTP server: if nothing else, you might worry that that you could be redirected to an insecure URL when you’re not looking carefully. You can thus turn off the HTTP server with http_listen=off in your config [3].

Hopefully this makes pizauth useful to more people in more ways. And it’s a great example of open-source contributors scratching an itch!

Footnotes

Comments