Many IMAP/SMTP clients, like msmtp,
fdm,
isync,
neomutt or
mutt can use OAuth2 access tokens but lack the
ability to renew and/or authorize OAuth2 credentials. The purpose of
oama
is to provide these missing capabilities by acting as a kind of
smart password manager. In particular, access token renewal happens
automatically in the background transparent to the user.
The OAuth2 credentials are kept in a keyring provided by any password manager with a FreeDesktop.org Secret Service compatible API. Some examples of such password managers are:
Alternatively GNU PG encrypted files can also be used as a backend for storing credentials.
Before oama
is fully operational you need to create the necessary
configuration files. See details in Configuration.
Invoking oama
without any arguments print a help message listing the
available commands:
oama - OAuth credential MAnager with store/lookup, renewal, authorization.
Usage: oama [--version] [-c|--config <config>] [--debug] COMMAND
Oama is an OAuth credential manager providing store/lookup, automatic renewal
and authorization operations. The credentials are stored either in the Gnome
keyring or in files encrypted by GnuPG. Oama is useful for IMAP/SMTP or other
network clients which cannot authorize and renew OAuth tokens on their own.
Available options:
-h,--help Show this help text
--version Show version
-c,--config <config> Configuration file
(default: "~/.config/oama/config.yaml")
--debug Print HTTP traffic to stdout
Available commands:
access Get the access token for email
show Show current credentials for email
renew Renew the access token of email
authorize Authorize OAuth2 for service/email
printenv Print the current runtime environment
template Print the default config template
More detailed help for individual commands can also be generated by appending
-h
after the command. Shell completion for bash
, zsh
and fish
shells
are provided.
After configuration, you must run the authorize
command. That is an
interactive process involving a browser since during it, you need to login
and authorize access to your email account. oama
will lead you through this
process.
oama
can be set up to run on a remote machine by running the authorization once
on the local host with a browser then copying over the obtained credentials to
the remote host.
Here is how to do it with GPG
backend.
-
Install
oama
both locally and on the remote host. On the local host configureoama
to use the GPG encrypted method to store your OAuth credentials. -
Run
oama authorize <service> <email>
on the local host where your browser is running. -
Mirror
~/.config/oama/config.yamal
and '~/.local/var/oama/*' on the remote host.
From that point you can use oama
on the remote machine as usual, just make
sure that oama
can access your encryption key by a gpg-agent
running on the
remote host.
oama
has a simple configuration system. When you run oama
at the first time
it will create the initial config file what you need to edit. This YAML file is
commented explaining your options, just follow the instructions there.
First select the method of storing the OAuth credentials. Then configure the
services you are going to use. There are two kinds of services the builtin
ones which oama
already knows and the user configured ones. The current
builtin services are google
and microsoft
.
For a builtin service the minimum information you need to provide are
client_id
and client_secret
. For user configured service there are a few
more required config options. See the initially created config file for more
details.
You can see all the configurable options in the services:
section of the
output of the oama printenv
command.
For institutional accounts your organization should provide the
client_{id,secret}
pair regardless who is the service provider.
For personal accounts you can register your own client application at your
service provider and obtain a client_{id,secret}
pair.
- Microsoft: Register an application
- Google: Credentials page
If that is too much hassle then you can try to find and use one of the open
source email clients' client_{id,secret}
pair. Most of these desktop clients
are already registered at many service providers.
Corporation/Organization/Institution accounts might be treated differently by the service provider. In such cases, not passing a login hint might be useful, see below.
Invoke oama
with no login hint:
oama authorize google <you@company.email> --nohint
Invoke oama
using your proper organizational email:
oama authorize microsoft <you@company.email>
Then visit the http://localhost:<portnumber>/start
page to perform the steps
below:
- Click "Sign in with another account"
- Click "Sign-in options"
- Click "Sign in to an organization"
- Put in the correct domain name which matches your organization address above
- Log in with your credentials at the organization.
All transactions and exceptions are logged to syslog
. If your OS using
systemd
you can inspect the log with a command like below:
journalctl --identifier oama --identifier msmtp --identifier fdm -e
Each release contains compiled executables of oama
which should work on
most Linux distributions. Currently, Linux/x86_64 and Linux/aarch64(arm64)
binaries are provided. Select the version you want to download from
releases.
For Archlinux users there is also a package on AUR: oama-bin
To build oama
from source you need a Haskell development environment,
with ghc 9.4.8
or higher. Either your platform's package system can provide
this or you can use ghcup. Once you have
the ghc
Haskell compiler and cabal
etc. installed, follow the steps
below:
Clone this repository and invoke cabal
:
git clone https://github.com/pdobsan/oama
cd oama
cabal update
cabal install --install-method=copy
That installs oama
into the ~/.cabal/bin/
directory.
Please, report any problems, questions, suggestions regarding oama
by opening
an issue or by starting a discussion.
-
Make sure that you are using the latest version of
oama
. -
Before opening an issue search old issues (both open and closed) and check whether similar problems have been raised or solved before.
-
Attach the complete output of the
oama printenv
command. Do not remove lines, get confidential values redacted by replacing them with<some explanation>
. In particular, indicate what kind ofclient_id/secret
you are using. For example,<my own app id registered with google>
. -
Indicate what kind of account(s) you are using that is who is the service provider and whether your account is personal or institutional.
-
Send also full error messages and related syslog entries. Even when
oama
was called by another program which could have hidden its error messages you might see them in the syslog.
The programs below solve similar problems as oama
does but have different
takes on them.
oama
is released under the 3-Clause BSD License, see the file
LICENSE.