From 1c538bfabc2cd31f27067505f0c3d1a46cba6ef0 Mon Sep 17 00:00:00 2001 From: Ivan Kohler Date: Thu, 9 Jul 2015 22:18:55 -0700 Subject: RT 4.2.11, ticket#13852 --- rt/docs/authentication.pod | 168 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 rt/docs/authentication.pod (limited to 'rt/docs/authentication.pod') 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. 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. 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 + +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 environment variable. Upon a request, RT +checks the value of C 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 (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 and +L. + +=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: + + + Require valid-user + AuthType Basic + AuthName "RT access" + AuthBasicProvider ldap + AuthLDAPURL \ + "ldap://ldap.example.com/dc=example,dc=com" + + + = 2.4> # For Apache 2.4 + Require local + + # For Apache 2.2 + Order deny,allow + Deny from all + Allow from localhost + Satisfy any + + + + +=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 +and you can read the documentation by running C. + +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 environment variable. + +=head4 C<$WebRemoteUserContinuous> + +Check C on every request rather than the initial request. + +When this is off, users will remain logged into RT even after C 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 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 is +encountered. + +=head4 C<$UserAutocreateDefaultsOnLogin> + +Specifies the default properties of auto-created users. + +=head4 C<$WebRemoteUserGecos> + +Tells RT to compare C to the C field of RT users instead of +the C field. + +=head2 Via RT's login form, aka RT::Authen::ExternalAuth + +L is an RT extension which provides authentication +B 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 +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: 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 ensures user data is updated every time someone +logs in. + +=head2 RT::Extension::LDAPImport + +L 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 (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. -- cgit v1.2.1