=encoding utf-8

=head1 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.

=head1 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.

=head1 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.

The second is supported by RT out of the box under the configuration option
C<$WebRemoteUserAuth> and other related options.  The first is supported by an RT
extension named L</RT::Authen::ExternalAuth>.  These two types may be used
independently or together, and both can fallback to RT's internal
authentication.

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
L</RT::Extension::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.

=head2 Via your web server, aka C<$WebRemoteUserAuth>, aka C<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 C<REMOTE_USER> environment variable.  Upon a request, RT
checks the value of C<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 C<mod_auth_kerb> (to talk to Active Directory).  C<$WebRemoteUserAuth> is
widely used by organizations with existing authentication standards for web
services that leverge web server modules for central authentication services.
The flexibility of RT's C<$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 L</RT::Authen::ExternalAuth> and
L</RT::Extension::LDAPImport>.

=head3 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>
        <IfVersion >= 2.4> # For Apache 2.4
            Require local
        </IfVersion>
        <IfVersion < 2.4>  # For Apache 2.2
            Order deny,allow
            Deny from all
            Allow from localhost
            Satisfy any
        </IfVersion>
    </Location>


=head3 RT configuration options

All of the following options control the behaviour 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 C<etc/RT_Config.pm>
and you can read the documentation by running C<perldoc /opt/rt4/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.

=head4 C<$WebRemoteUserAuth>

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

=head4 C<$WebRemoteUserContinuous>

Check C<REMOTE_USER> on every request rather than the initial request.

When this is off, users will remain logged into RT even after C<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
C<$WebRemoteUserContinuous> is on.

=head4 C<$WebFallbackToRTLogin>

If true, allows internal logins as well as C<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.

=head4 C<$WebRemoteUserAutocreate>

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

=head4 C<$UserAutocreateDefaultsOnLogin>

Specifies the default properties of auto-created users.

=head4 C<$WebRemoteUserGecos>

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

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

L<RT::Authen::ExternalAuth> is an RT extension which provides authentication
B<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 C<$WebRemoteUserAuth> and L<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).

=head3 Info mode and Authentication mode

There are two modes of operation in L<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 C<$WebRemoteUserAuth>.
This lets your web server handle authentication (usually for SSO) and
C<RT::Authen::ExternalAuth> ensures user data is updated every time someone
logs in.

=head2 RT::Extension::LDAPImport

L<RT::Extension::LDAPImport> provides no authentication, but is worth
mentioning 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 L<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.