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