TACC OpenSSH pluggable authentication module project for multi-factor authentication
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.




Multi-factor authentication (MFA) is rapidly becoming the de facto standard for access to all computing, whether via web, phone, or direct command-line access. HPC centers and other institutions supporting hundreds or thousands of users face challenging cost, licensing, user support, and infrastructure deployment decisions when considering a transition to MFA at scale.

OpenMFA is a set of custom Linux Pluggable Authentication Modules (PAM) built to provide multi-factor authentication capability that does not interfere with common data transfer protocols (SCP, SFTP, rsync, etc.), provides a mechanism for specific accounts or IP ranges to be exempted, supports SSH public key authentication as a first factor, and is built to support opt-in or mandatory deployments designed for the transitioning of large user bases.

OpenMFA is designed for academic institutions and other service providers who are in need of a free, flexible, and secure means to provide multiple factors of authentication via SSH for identity management.

Developed and Maintained by

W. Cyrus Proctor (mailto:cproctor@tacc.utexas.edu)

  • Need Help?
  • Curious about OpenMFA?
  • Looking to set up your own MFA infrastructure?

Send me an email and we can discuss how my colleagues and I might help you get started with OpenMFA.


When logging in to a system via SSH with OpenMFA installed, users are required to successfully enter a correct password or provide an authorized public-key as the first factor of authentication. For the second factor of authentication, OpenMFA requires users own a device that may utilize one of the three following options to deliver a time-based, one-time use token code:

  • Soft Token -- smartphone-based application;
  • SMS Token -- SMS text message;
  • Hard Token -- key fob with LCD screen.

Service providers utilizing OpenMFA will benefit directly by reaching the expected industry standard for security, and via cost avoidance since no licenses will need to be purchased via a commercial provider, which may cost many thousands of dollars each year. All users will benefit from the added security inherent with multiple factors of authentication while minimally impacting ease-of-use and convenience they have come to expect with their institution’s identity management resources.

System administrators and developers are able to deploy and fully control free and open technology tailored specifically for this purpose. Service providers can adopt OpenMFA to raise their own level of service and benefit from being viewed as technology leaders in this area and responsible stewards of public information resources.


Change into the newly cloned OpenMFA directory; make a build directory; copy the build script into the build directory:

cd OpenMFA && mkdir -p build && cd build && cp -p ../omfa/cmake/openmfa.build ./

Update the RADIUS host and server key information in omfa/src/pam_openmfa_token.h.

Revise and run the build script:

./openmfa.build ../omfa

Note that build perquisites include the GCC compiler, CMake, and the PAM development RPM (or equivalent) to be present. CPack can be used to automatically create an RPM that is then installed on the target systems.

OpenMFA is currently in production at the Texas Advanced Computing Center (TACC) serving over 10 thousand accounts across CentOS, SUSE, and Solaris operating systems.


Install the generated OpenMFA RPM. Four PAM modules will be placed into the /lib64/security directory while several example configuration templates will be installed in /etc/pam.d and /etc/ssh directories.

  • Update /etc/pam.d/sshd to utilize one of the password-auth.openmfa configuration templates
  • /etc/ssh/sshd_config will need to be updated to utilize public key and keyboard interactive authentication while passing password authentication to PAM
  • /etc/security/openmfa_access.conf can be used to exempt/enforce users, groups, IPs, etc. for MFA authentication


PAM SSHD Service Configuration

The following line with /etc/pam.d/sshd should replace the current PAM authentication stack:

auth       include      password-auth.openmfa

An example /etc/pam.d/password-auth.openmfa might look like:

auth       required                                    pam_env.so
auth       [success=1 default=ignore]                  pam_openmfa_pubkey.so
auth       [success=ok default=2 new_authtok_reqd=ok]  pam_unix.so
auth       sufficient                                  pam_openmfa_access.so
auth       sufficient                                  pam_openmfa_token.so enforce=full
auth       requisite                                   pam_deny.so

The above representative Linux PAM authentication stack for SSH log in with OpenMFA. OpenMFA PAM modules are highlighted by blue borders. The decision tree below illustrates how considerations for first and second factors of authentication are integrated together to provide flexible and powerful configuration options that satisfy the needs of our HPC user base.

Alt text

Enforcement Modes

Users at TACC may currently pair with hard, soft, or sms tokens via a web portal. pam_openmfa_token.so will query LDAP for valid MFA pairing information. Depending on the setting within /etc/pam.d/password-auth.openmfa for the enforce keyword, OpenMFA will behave differently, designed to aid in the transitioning of large user bases to MFA:

  • If enforce is set to "off" (default), no MFA pairing information will be checked.
  • If enforce is set to "full", all users will be prompted for a token, even if no valid MFA pairings are found.
  • If enforce is set to "paired", only users with a valid MFA pairing will be prompted for a token code (for a soft rollout).
  • If enforce is set to "countdown", date and website keywords must also be specified. date is the date in YYYY-MM-DD format that MFA pairings will be enforced. Users will have to acknowledge the countdown to date and website will be displayed for them to find more information on pairing a device.

If any misconfigurations are detected, enforcement will fail to "full".

SSH Daemon Configuration

The following lines within /etc/ssh/sshd_config are recommended to be added/amended:

PasswordAuthentication no
ChallengeResponseAuthentication yes
AuthenticationMethods publickey,keyboard-interactive keyboard-interactive
UsePAM yes

Currently, OpenSSH version 7.1p2 is recommended for use. A modified version is utilized at TACC.

OpenMFA PAM token module decision tree when MFA is active, i.e. "full" mode. An LDAP query is used to check the user's MFA pairing type. The user is sent a challenge-response query to enter their token code. The entered code is validated on a LinOTP-based back end. Either success or authentiation error is returned from the token module. Dotted arrows represent remote requests while bold arrows indicate interaction outside PAM back to the SSH daemon in the illustration below.

Alt text

Exemption Configuration

OpenMFA has the ability to control which parties undergo multi-factor authentication. This is controlled inside /etc/security/openmfa_access.conf, the exemption control table.

  • A comment line must start with "#", no space at front.
  • Order of lines is important.

When someone logs in, the table is scanned for the first entry that matches the (date, user, host) combination, or, in case of non-networked logins, the first entry that matches the (date, user, tty) combination. The permissions field of that table entry determines whether the login will be accepted or refused.

Format of the login access control table is three fields separated by a ":" character:

permission : expiration date : users : origins
  • The first field should be a "+" (exemption granted) or "-" (exemption denied) character.

  • The second filed should be an expiration date of the form YYYY-MM-DD, or ALL (always matches). If a date is invalid or expired, the line will be ignored.

  • The third field should be a list of one or more login names, group names, or ALL (always matches). A pattern of the form user@host is matched when the login name matches the "user" part, and when the "host" part matches the local machine name.

  • The fourth field should be a list of one or more tty names (for non-networked logins), host names, domain names (begin with "."), host addresses, internet network numbers (end with "."), ALL (always matches), NONE (matches no tty on non-networked logins) or LOCAL (matches any string that does not contain a "." character).

In short, all pam_access.so syntax with the addition of the date field should be permitted. One major change from pam_access.so is that a login attempt will be denied unless there is at least one line with a valid positive match.

--- Examples ---


Exempt user bob from host 123.456.78.9 of MFA until 2019-12-31


Exempt user tactacc from all hosts of MFA forever


Exempt all users from host 123.456.7.89 of MFA forever


Enforce MFA all users from all hosts forever

Note: If no match is present in the two factor exemption control table, a user will return PAM_PERM_DENIED for pam_openmfa_access.so.

Cite as:


W. Cyrus Proctor, Patrick Storm, Matthew R. Hanlon, and Nathaniel Mendoza. 2017. Securing HPC: Development of a Low Cost, Open Source Multi-factor Authentication Infrastructure. InProceedings of SC17, Denver, CO,USA, November 12–17, 2017,11 pages.
DOI: 10.1145/3126908.31269


Cyrus Proctor. (2017, August 10). TACC/OpenMFA: TACC OpenMFA Initial Public DOI Release. Zenodo. http://doi.org/10.5281/zenodo.841211


Copyright 2016, University of Texas at Austin and W. Cyrus Proctor


Project License

OpenMFA is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.