Multi Factor Authentication

The screenshot below shows the Time-based One-Time Password (TOTP) options available at login. This factor requires a third party application such as Google Authenticator. The sending party, factor length, and validity period for this are controlled by Global Flags described below.

The TOTP specification provides a strongly recommended best practice of using a stable user identifier within issuer label string. Because username, first and last name, email address, and barcode can all change for an Evergreen user (and in some cases, changed directly by a user), the Evergreen user ID is used as the stable identifier here even though this is less human-friendly than other identifiers.

If enabled, Web Authentication will prompt the operating system or password manager to establish MFA credentials. A third party account or device such as a Yubikey is required to use this factor. WebAuthn details are configured via Global Flags.

If so configured, a staff user may pair multiple WebAuthn devices with their account.

TOTP is also available via email, or via SMS, using Evergreen’s native Action Trigger tools. The sending party, factor length, and validity period for this factor are controlled by Global Flags.

For security reasons, this data does not prepopulate from existing staff profiles and must be entered at configuration time.

The email and SMS codes are time-based, so one code is valid for a given configurable time window for a specific user. The Resend option will resend the same code if there was an unrecoverable error somewhere in an email system.

Users should be aware that some carriers have been limiting email-to-SMS messages, which will affect the speed at which an SMS message will arrive and therefor might make it a less-desirable secondary factor.

Because enabling Multi-factor Authentication (MFA) creates a profound change to the login logic within Evergreen, there are certain settings that must be configured at the filesystem level, in the main settings configuration file opensrf.xml.

A new OpenSRF application, open-ils.auth_mfa, must be configured and running, whether MFA is in use or not. Within the configuration block for that application, the <app_settings> section looks like this:

If the top-level <enabled/> element contains true, then MFA will be generally available. Each potential MFA factor must also be enabled separately, with their own <enabled/> element containing true.

The TOTP, SMS, and email factors can make use of the <fuzziness/> element, which tells Evergreen how many timeout periods to look in the past and the future when verifying the one-time code for those factors. This defaults to 1 for all three factors, so that, for instance, a user using the Google Authenticator app for TOTP verification will have up to 90 seconds to enter a code, even though the codes change every 30 seconds. This setting helps account for unsynchronized server and client device clocks, as well as allowing Evergreen to be more forgiving for users that may take more than the average amount of time finding and then entering the one-time code.

To disable any factors you do not wish to offer to your users, simply remove the <enabled/> element, or change the content to false.

There is a single new Library Setting related to this work: Security: MFA recheck interval. This setting allows an Organizational Unit to specify the recheck interval for MFA among its staff members.

If this is unset, MFA will be forced at every login for MFA-Required permission group(s).

To force the "configure now, or skip for now" screen at every login until the user has configured a factor in "allowed" mode, you can unset the recheck interval setting (or set it to 0 seconds).

In order to require a second factor for login generally, you have to require it for the group. To require it at /every/ login, unset (or set to 0 seconds) the recheck interval.

The following table describes the new Global Flags associated with this work:

The Server Administration → Permission Groups interface now has two new options and a tab for MFA factors.

The two options are whether MFA is permitted, and whether it is required:

The new ADMIN_MFA permission is required to edit any of these options, in addition to existing permissions about editing Permission Group values.

There is also a new tab to enable or disable the various MFA factors. These can be inherited as shown below. Assigned directly means that even if the higher-level group has the factor removed, the more specific group can make it available.

The other new permission is REMOVE_USER_MFA which allows a user to remove configured MFA factors for another user. More information about removing other users’ factors is detailed below.

Most Evergreen clients other than the native Web Client will require some amount of development in order to integrate with Evergreen’s MFA infrastructure. For instance, SIP2 clients and the OpenSRF shell program srfsh will not be able to complete the login process for users with MFA requirements.

In order to address this, staff with an appropriately scoped ADMIN_MFA permission can provide those users with either ingress (client) specific exceptions to MFA, or make specific users fully exempt from MFA requirements. This capability is also accessed through the Test Password or Verify Credentials interfaces.

Requiring use of the credential verification interface is meant to encourage active consent from both the administrative staff with the appropriate permissions and the staff for whom MFA configuration would be removed or exempted.