no need for FS calendar buttons in RT 4.2
[freeside.git] / 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.