--- /dev/null
+=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.
projects / freeside.git / blobdiff