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-addres"
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 / Exchange
You may need to create your own client ID and secret by registering with
Microsoft's
identity platform:
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"};
}
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.