Documentation
</> Developer Portal

RT Authentication

RT allows for several different ways to authenticate users including an internal user management system and a number of ways to integrate with existing authentication systems.

Internal Authentication

RT's native internal authentication system provides administration tools to manage usernames and passwords. If you plan to run your RT as a stand-alone system and don't need to use accounts associated with any other system, this may be all you need. The administration pages under Admin → Users provide new user creation as well as password setting and control of RT's privileged flag for existing users.

Secret Key

RT uses a secret key for cryptographic operations such as generating password-reset tokens, MFA-reset tokens, and encrypting TOTP secrets stored in the database. By default RT derives this from $DatabasePassword, but we recommend setting $SecretKey to a dedicated long, random value in RT_SiteConfig.pm:

    Set($SecretKey, 'replace-with-a-long-random-string');

Using a dedicated secret avoids coupling application-level cryptography to the database credential. Set it before any user enrolls in MFA.

Changing the secret key (or changing $DatabasePassword while $SecretKey is empty) invalidates outstanding password-reset and MFA-reset links, and makes every stored TOTP secret undecryptable.

For the same reason, MFA enrollment does not carry over when migrating data with rt-importer or rt-serializer --format JSON: TOTP secrets are dropped and enrolled users enroll again at their next login. A --clone import keeps them, which only works if the new instance uses the same $SecretKey (or the same $DatabasePassword while $SecretKey is empty).

Password Policy

RT enforces password complexity requirements through the $PasswordPolicy configuration option. This replaces the older $MinimumPasswordLength setting with a richer set of checks.

The policy is a hash reference with up to three keys -- Default, Privileged, and Unprivileged -- each containing a policy hash. When a user sets or changes a password, RT resolves the effective policy by checking group policies first, then the user-type-specific key, then Default, and finally a built-in fallback of MinLength => 5.

Available policy fields:

MinLength - Minimum password length (0 to disable)
RequireUpper - Require at least one uppercase letter
RequireLower - Require at least one lowercase letter
RequireDigit - Require at least one digit
RequireSymbol - Require at least one non-alphanumeric character
NoUsername - Password must not contain the username

Example configuration with different requirements for privileged and unprivileged users:

    Set($PasswordPolicy, {
        Default => {
            MinLength => 5,
        },
        Privileged => {
            MinLength     => 10,
            RequireUpper  => 1,
            RequireLower  => 1,
            RequireDigit  => 1,
            NoUsername    => 1,
        },
        Unprivileged => {
            MinLength => 8,
        },
    });

Per-Group Password Policies

Individual user-defined groups can have their own password policy, configured via Admin -> Groups -> [Group] -> Settings -> Password Policy. When a user belongs to multiple groups that each define a policy, the most restrictive settings across all groups are merged (highest MinLength wins; any boolean requirement wins if any group enables it).

Group policies take precedence over the global $PasswordPolicy keys.

Enforcing Policy on Existing Passwords

By default, tightening $PasswordPolicy only affects users the next time they change their password. To act on existing noncompliant passwords at login time, set $ExistingPasswordPolicyAction:

ignore (default) - no change to existing behavior.
notify - users see a one-time flash message after a noncompliant login, with a link to a dedicated compliance-change page.
force - users are gated to a compliance-change page on every request until they pick a compliant password. REST username+password requests are rejected with a message directing the user to log in via the web interface.

A typical rollout starts with notify for one or more login cycles to let users self-update, then escalates to force.

The check only applies to internal RT passwords.

When MFA is enabled, the enforcement applies after MFA verification: the user proves their TOTP first, then is gated by the password-policy compliance page.

Self-Service Password Reset

RT includes a self-service password reset flow that allows users to request a reset link via email. It is disabled by default; set $DisableResetPasswordOnLogin to 0 to enable it. When enabled, a "Forgot password?" link appears on the login page. Users enter their email address, and if a matching account is found, RT emails a time-limited link that allows them to set a new password.

Administrators can also send reset emails from the user admin page (Admin -> Users -> [User] -> Modify), which is useful for onboarding new users or unlocking accounts.

The reset flow uses the PasswordReset template for emails. You can customize the wording by editing this template under Admin -> Global -> Templates.

Configuration

The following options control the reset flow. All are documented in detail in RT_Config.

$DisableResetPasswordOnLogin

Hides the "Forgot password?" link on the login page and blocks the self-service request page. Admins can still send reset emails from the user admin page. Default: on (self-service reset disabled).

$ResetLinkExpirySeconds

How long a reset link remains valid. Default: 4 hours.

$ResetRequestCooldown

Minimum seconds between consecutive reset emails for the same user, preventing abuse. Default: 300 (5 minutes).

$HidePasswordResetErrors

When enabled, all outcomes (user not found, disabled, etc.) show the same generic success message and every response takes at least one second, so the page doesn't reveal which addresses have active accounts. Errors are still logged. Default: on.

A reset email that takes longer than a second to send (for example through a slow SMTP relay) can still make responses for active accounts measurably slower, and each request holds a web server process for that second. Sites that enable self-service reset should rate-limit /NoAuth/ResetPassword/Request.html at the web server or proxy.

$ResetPasswordFromAddress

Overrides the From address on reset emails. When unset, $CorrespondAddress is used.

$ResetPasswordAllowUsersWithoutPassword

Allows users who have an RT account but no password to use the reset flow. Default: off.

$ResetPasswordCreateNewUserAndSetPassword

Allows visitors with unknown email addresses to create new accounts via the reset page. Only enable this on non-public RT instances. Default: off.

$ResetPasswordCreateNewUserAsPrivileged

When combined with the above, new accounts are created as privileged. Use with extreme caution. Default: off.

Multi-Factor Authentication (MFA)

RT supports Time-based One-Time Password (TOTP) multi-factor authentication. When enabled, users enroll by scanning a QR code with a standard authenticator app (Google Authenticator, Authy, 1Password, etc.). After enrollment, users are prompted for a 6-digit code after entering their password on each login.

Requirements

MFA support requires additional Perl modules (Auth::GoogleAuth, Crypt::URandom, CryptX, Text::QRCode) and the libqrencode system library. Pass --enable-mfa to configure to include these dependencies:

    ./configure --enable-mfa [other options...]

Run make testdeps after configuring to verify the modules are installed.

If the required modules are not installed, RT automatically sets $DisableMFA to true and all MFA functionality is hidden. You can also explicitly disable MFA by setting $DisableMFA to 1 in RT_SiteConfig.pm.

Configuring MFA Policy

MFA behavior is controlled by the $MFAPolicy configuration option. Like $PasswordPolicy, it supports Default, Privileged, and Unprivileged keys:

    Set($MFAPolicy, {
        Privileged => {
            Mode  => 'Required',
            Drift => 0,
        },
    });

The Mode field accepts three values:

Off - MFA is disabled (default)
Optional - Users may enroll via Logged in as > Settings > About me (or Preferences in the self-service interface), but are not required to
Required - Users must enroll on their next login and verify on every subsequent login

The Drift field controls clock-drift tolerance between the authenticator device and the server. It is the number of 30-second TOTP windows accepted on each side of the current one. Use 0 for the current window only (strictest), 1 to also accept one window before and after, and so on up to a maximum of 5.

Per-Group MFA Policies

Individual user-defined groups can have their own MFA policy, configured via Admin -> Groups -> [Group] -> Settings -> MFA Policy. When a user belongs to multiple groups, the most restrictive mode wins (Required > Optional > Off) and the smallest Drift wins.

Group policies take precedence over the global $MFAPolicy keys.

User Experience

  • Required, not yet enrolled: After entering a correct password, the user is redirected to an enrollment page showing a QR code and a base32 secret for manual entry. The user must enter a valid 6-digit code from their authenticator app to complete enrollment and log in.

  • Required, enrolled: After entering a correct password, the user is redirected to a verification page and must enter a valid TOTP code to complete login.

  • Optional: Enrolled users see MFA verification on login. Users can enroll or disable MFA from Logged in as > Settings > About me, or Preferences in the self-service interface.

If a user loses access to their authenticator app, a "Lost access to your authenticator?" link on the verification page lets them request an MFA reset email. The reset link clears their enrollment so they can set up a new authenticator. The MFAReset template controls the wording of this email.

Administrators can also clear a user's MFA enrollment from the user admin page (Admin -> Users -> [User] -> Modify).

Failed-Attempt Lockout

To slow online TOTP brute-force attempts, RT counts consecutive failed verifications on each user account. After five failed attempts the account is locked out of MFA verification for fifteen minutes. The lockout is recorded on the user record, so it persists across browser sessions and cannot be reset by logging in again. While locked out, password authentication for that user is also refused with the same generic error message used for wrong passwords, so an attacker cannot probe lockout state.

A successful TOTP verification clears the counter, as does any of the existing MFA reset paths (self-service "Lost access" link, admin reset on the user page, or the SystemUser-level ClearTOTPEnrollment). The counter also auto-clears the next time the user's verify page is visited after the fifteen-minute window has elapsed.

MFA and External Authentication

MFA enforcement is bypassed for sessions authenticated via REMOTE_USER ($WebRemoteUserAuth) or an RT::Authen::ExternalAuth SSO cookie, since the external authentication system (e.g. a SAML or Kerberos identity provider) is expected to handle its own second-factor requirements. If the same user logs in with a password (when $WebFallbackToRTLogin is enabled), MFA is enforced normally.

MFA and REST APIs

REST 1.0 and REST 2.0 password-based logins are rejected when MFA is required for the user, or optional and the user has enrolled, since there is no interactive way to complete the TOTP challenge. API users should use token authentication instead, which bypasses MFA.

Token Authentication

Authentication tokens are typically used for accessing RT's REST APIs, often RT::REST2. To set up token access, first select an RT user account you will use when accessing APIs and give that user account appropriate rights to operate on tickets based on what you plan to do (read ticket information, create tickets, update tickets, etc.).

You can then give that user the right ManageAuthTokens which will add a new option in the menu Logged in as > Settings > AuthTokens.

When setting up token authentication, add the following directive to your RT Apache configuration to allow RT to access the Authorization header.

    SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

Since tokens grant access on behalf of a user, RT prompts for a password when a user is creating a token. However, if you have a mix of RT and federated authentication, RT can't authenticate users via the federated password system. For this case, you can explicitly disable the password check with the $DisablePasswordForAuthToken configuration option.

External Authentication

There are two primary types of external authentication: in one you type your username and password into RT's login form, and in the other your web server (such as Apache) handles authentication, often seamlessly, and tells RT the user logged in.

Starting with RT 4.4, both of these options are supported by RT out of the box, activated using different configuration options. The first is supported by the RT::Authen::ExternalAuth module. The second is activated using the configuration option $WebRemoteUserAuth along with some related options. These two types may be used independently or together, and both can fallback to RT's internal authentication.

If you are running a version of RT earlier than 4.4, you can install RT::Authen::ExternalAuth as an extension.

No matter what type of external authentication you use, RT still maintains user records in its database that correspond to your external source. This is necessary so RT can link tickets, groups, rights, dashboards, etc. to users.

All that is necessary for integration with external authentication systems is a shared username or email address. However, in RT you may want to leverage additional information from your external source. Synchronization of users, user data, and groups is provided by an extension named RT::LDAPImport. It uses an external LDAP source, such an OpenLDAP or Active Directory server, as the authoritative repository and keeps RT up to date accordingly. This can be used in tandem with any of the external authentication options as it does not provide any authentication itself.

Note that if you start with "Internal Authentication" and then switch to "External Authentication", your original users will still have passwords in the RT database. RT ignores these passwords when handling logins, but in some cases RT may show a password box that would normally be hidden for external authentication because it detects an existing password. To avoid this, you can clear passwords in the Users table when you switch to external authentication.

Via your web server, aka $WebRemoteUserAuth, aka REMOTE_USER

This type of external authentication is built-in to RT and bypasses the RT login form. Instead, RT defers authentication to the web server which is expected to set a REMOTE_USER environment variable. Upon a request, RT checks the value of REMOTE_USER against its internal database and logs in the matched user.

It is often used to provide single sign-on (SSO) support via Apache modules such as mod_auth_kerb (to talk to Active Directory). $WebRemoteUserAuth is widely used by organizations with existing authentication standards for web services that leverage web server modules for central authentication services. The flexibility of RT's $WebRemoteUserAuth support means that it can be setup with almost any authentication system.

In order to keep user data in sync, this type of external auth is almost always used in combination with one or both of RT::Authen::ExternalAuth and RT::LDAPImport.

Apache Configuration

When configuring Apache to protect RT, remember that the RT mail gateway uses the web interface to upload the incoming email messages. You will thus need to provide an exception for the mail gateway endpoint.

An example of using LDAP authentication and HTTP Basic auth:

    <Location />
        Require valid-user
        AuthType Basic
        AuthName "RT access"
        AuthBasicProvider ldap
        AuthLDAPURL \
            "ldap://ldap.example.com/dc=example,dc=com"
    </Location>
    <Location /REST/1.0/NoAuth/mail-gateway>
        Require local
    </Location>

RT Configuration Options

All of the following options control the behavior of RT's built-in external authentication which relies on the web server. They are documented in detail under the "Authorization and user configuration" section of RT_Config and you can read the documentation by running perldoc /opt/rt6/etc/RT_Config.pm.

The list below is meant to make you aware of what's available. You should read the full documentation as described above.

$WebRemoteUserAuth

Enables or disables RT's expectation that the web server will provide authentication using the REMOTE_USER environment variable.

$WebRemoteUserContinuous

Check REMOTE_USER on every request rather than the initial request.

When this is off, users will remain logged into RT even after REMOTE_USER is no longer provided. This provides a separation of sessions, but it may not be desirable in all cases. For example, if a user logs out of the external authentication system their RT session will remain active unless $WebRemoteUserContinuous is on.

$WebFallbackToRTLogin

If true, allows internal logins as well as REMOTE_USER by providing a login form if external authentication fails. This is useful to provide local admin access (usually as root) or self service access for people without external user accounts.

$WebRemoteUserAutocreate

Enables or disables auto-creation of RT users when a new REMOTE_USER is encountered.

$UserAutocreateDefaultsOnLogin

Specifies the default properties of auto-created users.

$WebRemoteUserGecos

Tells RT to compare REMOTE_USER to the Gecos field of RT users instead of the Name field.

Via RT's login form, aka RT::Authen::ExternalAuth

RT::Authen::ExternalAuth provides authentication using RT's login form. It can be configured to talk to an LDAP source (such as Active Directory), an external database, or an SSO cookie.

The key difference between $WebRemoteUserAuth and RT::Authen::ExternalAuth is the use of the RT login form and what part of the system talks to your authentication source (your web server vs. RT itself).

As noted above, for versions of RT before 4.4, you can install RT::Authen::ExternalAuth as an extension.

Info mode and Authentication mode

There are two modes of operation in RT::Authen::ExternalAuth: info and auth. Usually you want to configure both so that successfully authenticated users also get their information pulled and updated from your external source.

Auth-only configurations are rare, and generally not as useful.

Info-only configurations are commonly setup in tandem with $WebRemoteUserAuth. This lets your web server handle authentication (usually for SSO) and RT::Authen::ExternalAuth ensures user data is updated every time someone logs in.

RT::Extension::LDAPImport

RT::LDAPImport provides no authentication, but is useful alongside authentication because it provides user data and group member synchronization from any LDAP source into RT. It provides a similar but more complete sync solution than RT::Authen::ExternalAuth (which only updates upon login and doesn't handle groups). It may be used with either of RT's external authentication sources, or on it's own.

Starting with RT 4.4, RT::LDAPImport is part of RT. For earlier versions of RT, you can install RT::Extension::LDAPImport as an extension.

← Back to index