/ 
RT-Extension-TOTPMFA-0.04
/ RT::Extension::TOTPMFA

NAME

RT::Extension::TOTPMFA - Multi-factor authentication with time-based one-time passcodes

DESCRIPTION

This extension allows users to add multi-factor authentication to their account.

A secret token is stored for each user, and used for time-based one-time passcodes (TOTP).

To enable MFA, the "About me" page is extended with a new section alongside identity and password, for TOTP token management. In this section, the user may scan a QR code based on this token into their mobile device's TOTP-compatible app, such as Google Authenticator. Or, they can enrol the key for their Yubikey device on this page instead.

When an account has MFA enabled, the RT login page works as usual, but the user is then prompted to enter a one-time passcode before they can proceed any further.

The MFA prompt will be repeated after a configurable duration, or when a new session begins.

If a user loses their MFA token, an administrator can switch off MFA in their account settings on their behalf, on the user basics modification page.

RT VERSION

Requires at least RT 5.0.1.

REQUIREMENTS

These Perl modules are required:

  • Authen::OATH (Debian package: libauthen-oath-perl)

  • Convert::Base32 (Debian package: libconvert-base32-perl)

  • Imager::QRCode (Debian package: libimager-qrcode-perl)

  • Crypt::CBC (Debian package: libcrypt-cbc-perl)

  • LWP::UserAgent (Debian package: libwww-perl)

INSTALLATION

For installation to work, you will need Module::Install::RTx.

RTHOME=/usr/share/request-tracker5/lib perl Makefile.PL

Adjust RTHOME to point to the directory containing RT.pm.

make
make install

May need root permissions.

Edit your /opt/rt5/etc/RT_SiteConfig.pm

Add these lines:

Set($TOTPMFA_Issuer, 'Request Tracker');
Set($TOTPMFA_Period, 30);
Set($TOTPMFA_Digits, 6);
Plugin('RT::Extension::TOTPMFA');

See below for configuration details.

Restart your web server

CONFIGURATION

$TOTPMFA_Issuer

The issuer name used in the QR code when a user registers their secret. This is what is shown next to the username in the user's authenticator app. The default is "Request Tracker".

$TOTPMFA_Period

How many seconds a one-time passcode is valid for. The default is 30.

$TOTPMFA_Digits

How many digits to use in the one-time passcodes. The default is 6.

ISSUES AND CONTRIBUTIONS

The project is held on Codeberg; its issue tracker is at https://codeberg.org/ivarch/rt-extension-totpmfa/issues.

LICENSE AND COPYRIGHT

Copyright 2025 Andrew Wood.

License GPLv3+: GNU GPL version 3 or later: https://gnu.org/licenses/gpl.html

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

INTERNAL FUNCTIONS

This section provides details of the internal functions provided by this extension, for developers.

UserSettings $UserObj

Return a hashref containing the TOTP MFA settings for the RT::User object $UserObj.

Type

MFA type to use: None, TOTP (default None).

Duration

The re-validation interval: the number of seconds that a successful authentication is valid for (default 1 day - 86400 seconds).

Secret

The OATH TOTP secret, base32 encoded (the default is an empty string).

Yubikey

If a Yubikey is being used, the Yubikey identifier (default is an empty string).

Default values will be returned if the user object is not valid.

UpdateUserSetting $UserObj, $Key, $Value

Change the TOTPMFA setting $Key to $Value for the RT::User object $UserObj, returning an array ($OK, $Message), where $Message is an error message if $OK is false.

IsEnabledForUser $UserObj

Return true if MFA is enabled at all for the RT::User object $UserObj, meaning that their TOTPMFA Type is set to anything other than "None".

NewSecret $UserObj

Generate and store a new TOTP MFA Secret value for the RT::User object $UserObj, returning ($OK, $Message).

SessionIsAuthenticated $Session

Return true if the session hashref $Session was authenticated by MFA within the expiry duration.

QRCode $UserObj

Return the binary data for a QR code in PNG format, suitable for scanning into an OATH TOTP authenticator application for the RT::User object $UserObj.

MFALogin $Session, $OTP

Return true, and update the session to record that MFA was validated, if a TOTP MFA form submission was received with a correct value.