diff options
Diffstat (limited to 'rt/docs/authentication.pod')
| -rw-r--r-- | rt/docs/authentication.pod | 168 |
1 files changed, 168 insertions, 0 deletions
diff --git a/rt/docs/authentication.pod b/rt/docs/authentication.pod new file mode 100644 index 000000000..26599cd6e --- /dev/null +++ b/rt/docs/authentication.pod @@ -0,0 +1,168 @@ +=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. |