- RT Authentication
- Internal Authentication
- Token Authentication
- External Authentication
  - Via your web server, aka $WebRemoteUserAuth, aka REMOTE_USER
    - Apache Configuration
    - RT Configuration Options
      - $WebRemoteUserAuth
      - $WebRemoteUserContinuous
      - $WebFallbackToRTLogin
      - $WebRemoteUserAutocreate
      - $UserAutocreateDefaultsOnLogin
      - $WebRemoteUserGecos
  - Via RT's login form, aka RT::Authen::ExternalAuth
    - Info mode and Authentication mode
  - RT::Extension::LDAPImport

# 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.

# 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 /usr/share/request-tracker5/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