rt/docs/authentication.pod

   1 =encoding utf-8
   2
   3 =head1 RT Authentication
   4
   5 RT allows for several different ways to authenticate users including an
   6 internal user management system and a number of ways to integrate with existing
   7 authentication systems.
   8
   9 =head1 Internal Authentication
  10
  11 RT's native internal authentication system provides administration tools to
  12 manage usernames and passwords.  If you plan to run your RT as a stand-alone
  13 system and don't need to use accounts associated with any other system, this
  14 may be all you need.  The administration pages under Admin → Users
  15 provide new user creation as well as password setting and control of RT's
  16 privileged flag for existing users.
  17
  18 =head1 External Authentication
  19
  20 There are two primary types of external authentication: in one you type your
  21 username and password into RT's login form, and in the other your web server
  22 (such as Apache) handles authentication, often seamlessly, and tells RT the
  23 user logged in.
  24
  25 The second is supported by RT out of the box under the configuration option
  26 C<$WebRemoteUserAuth> and other related options.  The first is supported by an RT
  27 extension named L</RT::Authen::ExternalAuth>.  These two types may be used
  28 independently or together, and both can fallback to RT's internal
  29 authentication.
  30
  31 No matter what type of external authentication you use, RT still maintains user
  32 records in its database that correspond to your external source.  This is
  33 necessary so RT can link tickets, groups, rights, dashboards, etc. to users.
  34
  35 All that is necessary for integration with external authentication systems is a
  36 shared username or email address.  However, in RT you may want to leverage
  37 additional information from your external source.  Synchronization of users,
  38 user data, and groups is provided by an extension named
  39 L</RT::Extension::LDAPImport>.  It uses an external LDAP source, such an
  40 OpenLDAP or Active Directory server, as the authoritative repository and keeps
  41 RT up to date accordingly.  This can be used in tandem with any of the external
  42 authentication options as it does not provide any authentication itself.
  43
  44 =head2 Via your web server, aka C<$WebRemoteUserAuth>, aka C<REMOTE_USER>
  45
  46 This type of external authentication is built-in to RT and bypasses the RT
  47 login form.  Instead, RT defers authentication to the web server which is
  48 expected to set a C<REMOTE_USER> environment variable.  Upon a request, RT
  49 checks the value of C<REMOTE_USER> against its internal database and logs in
  50 the matched user.
  51
  52 It is often used to provide single sign-on (SSO) support via Apache modules
  53 such as C<mod_auth_kerb> (to talk to Active Directory).  C<$WebRemoteUserAuth> is
  54 widely used by organizations with existing authentication standards for web
  55 services that leverge web server modules for central authentication services.
  56 The flexibility of RT's C<$WebRemoteUserAuth> support means that it can be setup
  57 with almost any authentication system.
  58
  59 In order to keep user data in sync, this type of external auth is almost always
  60 used in combination with one or both of L</RT::Authen::ExternalAuth> and
  61 L</RT::Extension::LDAPImport>.
  62
  63 =head3 Apache configuration
  64
  65 When configuring Apache to protect RT, remember that the RT mail gateway
  66 uses the web interface to upload the incoming email messages.  You will
  67 thus need to provide an exception for the mail gateway endpoint.
  68
  69 An example of using LDAP authentication and HTTP Basic auth:
  70
  71     <Location />
  72         Require valid-user
  73         AuthType Basic
  74         AuthName "RT access"
  75         AuthBasicProvider ldap
  76         AuthLDAPURL \
  77             "ldap://ldap.example.com/dc=example,dc=com"
  78     </Location>
  79     <Location /REST/1.0/NoAuth/mail-gateway>
  80         <IfVersion >= 2.4> # For Apache 2.4
  81             Require local
  82         </IfVersion>
  83         <IfVersion < 2.4>  # For Apache 2.2
  84             Order deny,allow
  85             Deny from all
  86             Allow from localhost
  87             Satisfy any
  88         </IfVersion>
  89     </Location>
  90
  91
  92 =head3 RT configuration options
  93
  94 All of the following options control the behaviour of RT's built-in external
  95 authentication which relies on the web server.  They are documented in detail
  96 under the "Authorization and user configuration" section of C<etc/RT_Config.pm>
  97 and you can read the documentation by running C<perldoc /opt/rt4/etc/RT_Config.pm>.
  98
  99 The list below is meant to make you aware of what's available.  You should read
 100 the full documentation as described above.
 101
 102 =head4 C<$WebRemoteUserAuth>
 103
 104 Enables or disables RT's expectation that the web server will provide
 105 authentication using the C<REMOTE_USER> environment variable.
 106
 107 =head4 C<$WebRemoteUserContinuous>
 108
 109 Check C<REMOTE_USER> on every request rather than the initial request.
 110
 111 When this is off, users will remain logged into RT even after C<REMOTE_USER> is
 112 no longer provided.  This provides a separation of sessions, but it may not be
 113 desirable in all cases.  For example, if a user logs out of the external
 114 authentication system their RT session will remain active unless
 115 C<$WebRemoteUserContinuous> is on.
 116
 117 =head4 C<$WebFallbackToRTLogin>
 118
 119 If true, allows internal logins as well as C<REMOTE_USER> by providing a login
 120 form if external authentication fails. This is useful to provide local admin
 121 access (usually as root) or self service access for people without external
 122 user accounts.
 123
 124 =head4 C<$WebRemoteUserAutocreate>
 125
 126 Enables or disables auto-creation of RT users when a new C<REMOTE_USER> is
 127 encountered.
 128
 129 =head4 C<$UserAutocreateDefaultsOnLogin>
 130
 131 Specifies the default properties of auto-created users.
 132
 133 =head4 C<$WebRemoteUserGecos>
 134
 135 Tells RT to compare C<REMOTE_USER> to the C<Gecos> field of RT users instead of
 136 the C<Name> field.
 137
 138 =head2 Via RT's login form, aka RT::Authen::ExternalAuth
 139
 140 L<RT::Authen::ExternalAuth> is an RT extension which provides authentication
 141 B<using> RT's login form.  It can be configured to talk to an LDAP source (such
 142 as Active Directory), an external database, or an SSO cookie.
 143
 144 The key difference between C<$WebRemoteUserAuth> and L<RT::Authen::ExternalAuth>
 145 is the use of the RT login form and what part of the system talks to your
 146 authentication source (your web server vs. RT itself).
 147
 148 =head3 Info mode and Authentication mode
 149
 150 There are two modes of operation in L<RT::Authen::ExternalAuth>: info and auth.
 151 Usually you want to configure both so that successfully authenticated users
 152 also get their information pulled and updated from your external source.
 153
 154 Auth-only configurations are rare, and generally not as useful.
 155
 156 Info-only configurations are commonly setup in tandem with C<$WebRemoteUserAuth>.
 157 This lets your web server handle authentication (usually for SSO) and
 158 C<RT::Authen::ExternalAuth> ensures user data is updated every time someone
 159 logs in.
 160
 161 =head2 RT::Extension::LDAPImport
 162
 163 L<RT::Extension::LDAPImport> provides no authentication, but is worth
 164 mentioning because it provides user data and group member synchronization from
 165 any LDAP source into RT.  It provides a similar but more complete sync solution
 166 than L<RT::Authen::ExternalAuth> (which only updates upon login and doesn't
 167 handle groups).  It may be used with either of RT's external authentication
 168 sources, or on it's own.