pizauth recipes

This page contains some example configurations and per-repo programs that may help you think of how pizauth can best be applied to your situation. The per-repo programs in this page happen to be written in shell script for easy deployment, but note that you can write per-repo programs in whatever language/system you wish.

Example integrations

Once you have set up pizauth, you will then need to set up the software which needs access tokens. This section contains example configuration snippets to help you get up and running.

The examples assume that pizauth is in your $PATH: if it is not, you will need to substitute an absolute path to pizauth in these snippets.

mbsync

Ensure you have the xoauth2 plugin for cyrus-sasl installed, and then use something like this for the IMAP account in `~/.mbsyncrc`:

IMAPAccount account-name
Host imap-server
User username
PassCmd "pizauth show pizauth-account-name"
AuthMechs XOAUTH2

msmtp

In your configuration file (typically ~/.config/msmtp/config):

account account-name
auth xoauth2
host smtp-server
protocol smtp
from email-address
user username
passwordeval pizauth show

mutt/neomutt

In your muttrc:

set imap_user = "your-email-address"
set folder = "imaps://outlook.office365.com:993"
set spoolfile = "+INBOX"
set ssl_force_tls = yes
set imap_authenticators="oauthbearer:xoauth2"
set imap_oauth_refresh_command="pizauth show work"
set smtp_authenticators="oauthbearer:xoauth2"
set smtp_oauth_refresh_command="pizauth show work"

Example account settings

Each provider you wish to authenticate with will have its own settings it requires of you. These can be difficult to find, so examples are provided in this section. Caveat emptor: these settings will not work in all situations, and providers have historically required users to intermittently change their settings.

Microsoft / HotMail / Exchange

There is more than one possible setting here, at the very least depending on whether your particular sub-provider requires an http or https redirection URI. You may also need to create your own client ID and secret by registering with Microsoft’s identity platform.

An example http redirection URI configuration might look as follows:

account "your-account-name" {
  auth_uri = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize";
  token_uri = "https://login.microsoftonline.com/common/oauth2/v2.0/token";
  client_id = "your-client-id";
  client_secret = "your-client-secret";
  scopes = [
    "https://outlook.office365.com/IMAP.AccessAsUser.All",
    "https://outlook.office365.com/POP.AccessAsUser.All",
    "https://outlook.office365.com/SMTP.Send",
    "offline_access"
  ];
  auth_uri_fields = {"login_hint": "your-email-address"};
}

An example https redirection URI configuration might look as follows:

account "your-account-name" {
  auth_uri = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize";
  token_uri = "https://login.microsoftonline.com/common/oauth2/v2.0/token";
  client_id = "your-client-id";
  client_secret = "your-client-secret";
  redirect_uri = "https://localhost";
  scopes = [
    "https://outlook.office.com/IMAP.AccessAsUser.All",
    "https://outlook.office.com/SMTP.Send",
    "offline_access"
  ];
  auth_uri_fields = {"login_hint": "your-email-address"};
}

Gmail

You may need to create your own client ID and secret via the credentials tab of the Google Cloud Console.

account "your-account-name" {
  auth_uri = "https://accounts.google.com/o/oauth2/auth";
  token_uri = "https://oauth2.googleapis.com/token";
  client_id = "your-client-id";
  client_secret = "your-client-secret";
  scopes = ["https://mail.google.com/"];
  auth_uri_fields = {"login_hint": "your-email-address"};
}

pizauth on a remote machine

You can run pizauth on a remote machine and have your local machine authenticate that remote existence with ssh -L. pizauth contains a small HTTP server used to receive authentication requests. By default the HTTP server listens on a random port, but it is easiest in this scenario to fix a port with the global http_listen option:

http_listen = "127.0.0.1:port-number";
account "..." { ... }

Then on your local machine (using the same port-number) as above run ssh:

ssh -L 127.0.0.1:port-number:127.0.0.1:port-number remote

Then on the remote machine start pizauth server and then pizauth show account-name. Copy the authentication URL into a browser on your local machine and continue as normal. When you see the “pizauth processing authentication: you can safely close this page.” message you can close the ssh tunnel. If the account later needs reauthenticating (e.g. because the refresh token has become invalid), simply reopen the ssh tunnel, reauthenticate, and close the ssh tunnel.