toopher-pam provides a set of tools to enable Toopher-based PAM authentication
Install using one of our pre-built release packages, or build it yourself.
Configuring toopher-pam involves configuring the module itself and inserting it into a PAM-enabled application's authentication stack.
Configuration files live in /etc/security/toopher by default. See the included configuration file for configuration options. The defaults will suit most needs, but you do need to add Toopher API Requester credentials (available from our client portal) to your Toopher credential file (usually found in /etc/security/toopher/credentials). Please be sure to restrict access to the credential file's contents (but maintain accessibility for the toopher-api-helper utility).
Like all PAM service modules, toopher-pam must be inserted into the authentication stack of PAM-enabled applications. Unfortunately this can vary from one flavor of PAM to the next, but here are some example configurations.
The .deb supplied in our pre-built release packages uses pam-auth-update to automatically insert itself in the common authentication stack for Debian-based distros the support it (e.g. Ubuntu). All a user needs to do is pair their account with Toopher (see below) and they'll immediately start receiving authentication requests via toopher-pam.
Configuration on systems that don't support pam-auth-update involves manually manipulating the authentication stack configurations (usually found in /etc/pam.d/). The edits required will depend upon the existing stack (reference your system's PAM documentation for more details), but this typically involves inserting the toopher-pam module at the bottom of the stack and setting the previous terminal module as requisite. For example, on RedHat-based distros many of the PAM application configurations (such as sshd) reference by inclusion the password-auth configuration, which consists of the following auth section entries:
auth required pam_env.so
auth sufficient pam_unix.so nullok try_first_pass
auth requisite pam_succeed_if.so uid >= 500 quiet
auth required pam_deny.so
This stack can be modified as follows to add toopher-pam:
auth required pam_env.so
auth requisite pam_unix.so nullok try_first_pass
auth required pam_toopher.so
In fact, our pre-built rpms include this configuration as password+toopher-auth in the /etc/pam.d/ directory which can be used within individual application configuration stacks to provide authentication supplemented by toopher-pam's capabilities.
In order for a user to leverage toopher-pam's capabilities, they will need to pair their account with Toopher. The toopher-pair utility included with this package facilitates the pairing process and writes the necessary information into a configuration file in the user's home directory. The utility's help message is reproduced below (invoke the tool with the --help option for the latest information):
usage: toopher-pair [-h] [--user USER] [--shared | --host-specific]
[--phrase PAIRING_PHRASE]
Pair an account with the Toopher app
optional arguments:
-h, --help show this help message and exit
--user USER, -u USER the user to pair (defaults to the current user,
specifying a user is usually only useful for the
superuser)
--shared, -s create a shared pairing instead of a host-specific
pairing
--host-specific, -o create a host-specific pairing instead of a shared
pairing (this is the default unless otherwise
specified in the system configuration file)
--phrase PAIRING_PHRASE, -p PAIRING_PHRASE
a pairing phrase generated by the Toopher app (will
prompt if not supplied)
This PAModule is based on pam_python by Russell Stuart. This code inherits its use of the Eclipse Public License v1.0