NAME
    RT::Authen::ExternalAuth - RT Authentication using External Sources

DESCRIPTION
    This module provides the ability to authenticate RT users against one or
    more external data sources at once. It will also allow information about
    that user to be loaded from the same, or any other available, source as
    well as allowing multple redundant servers for each method.

    The extension currently supports authentication and information from
    LDAP via the Net::LDAP module, and from any data source that an
    installed DBI driver is available for.

    It is also possible to use cookies set by an alternate application for
    Single Sign-On (SSO) with that application. For example, you may
    integrate RT with your own website login system so that once users log
    in to your website, they will be automagically logged in to RT when they
    access it.

INSTALLATION
    Note that the features provided by this module have been made into core
    features in RT 4.4 and greater.

    perl Makefile.PL
    make
    make install
        May need root permissions

    Edit your /opt/rt4/etc/RT_SiteConfig.pm
        If you are using the RT 4.2 series, add this line:

            Plugin('RT::Authen::ExternalAuth');

        For RT 4.0, add this line:

            Set(@Plugins, qw(RT::Authen::ExternalAuth) );

        or add RT::Authen::ExternalAuth to your existing @Plugins line.

        See "CONFIGURATION" for additional configuration to add to your
        RT_SiteConfig.pm file.

UPGRADING
    If you are upgrading from an earlier version of this extension, you must
    remove the following files manually:

        /opt/rt4/local/plugins/RT-Authen-ExternalAuth/lib/RT/User_Vendor.pm
        /opt/rt4/local/lib/RT/User_Vendor.pm
        /opt/rt4/local/lib/RT/Authen/External_Auth.pm

    Otherwise you will most likely encounter an error about modifying a read
    only value and be unable to start RT.

    You may not have all of these files. It depends what versions you are
    upgrading between.

    If you are using a vendor packaged RT, your local directories are likely
    to be somewhere under /usr/local instead of in /opt/rt4 so you will need
    to visit Configuration -> Tools -> System Configuration to find your
    plugin root.

CONFIGURATION
    RT::Authen::ExternalAuth provides a lot of flexibility with many
    configuration options. The following desc these configuration options,
    and provides a complete example.

    $ExternalAuthPriority
        The order in which the services defined in "$ExternalSettings"
        should be used to authenticate users. Once the user has been
        authenticated by one service, the rest are skipped.

        You should remove services you don't use. For example, if you're
        only using My_LDAP, remove My_MySQL and My_SSO_Cookie.

            Set($ExternalAuthPriority,  [ 'My_LDAP',
                                          'My_MySQL',
                                          'My_SSO_Cookie'
                                        ]
            );

    $ExternalInfoPriority
        When multiple auth services are available, this value defines the
        order in which the services defined in "$ExternalSettings" should be
        used to get information about users. This includes RealName,
        telephone numbers etc, but also whether or not the user should be
        considered disabled.

        Once a user record is found, no more services are checked.

        You CANNOT use a SSO cookie to retrieve information.

        You should remove services you don't use, but you must define at
        least one service.

            Set($ExternalInfoPriority,  [ 'My_LDAP',
                                          'My_MySQL',
                                        ]
            );

    $AutoCreateNonExternalUsers
        If this is set to 1, then users should be autocreated by RT as
        internal users if they fail to authenticate from an external
        service. This is useful if you have users outside your organization
        who might interface with RT, perhaps by sending email to a support
        email address.

    $ExternalSettings
        These are the full settings for each external service as a hash of
        hashes. Note that you may have as many external services as you
        wish. They will be checked in the order specified in
        "$ExternalAuthPriority" and "$ExternalInfoPriority" directives
        above.

        The outer structure is a key with the authentication option (name of
        external source). The value is a hash reference with configuration
        keys and values, for example:

            Set($ExternalSettings, {
                My_LDAP => {
                    type => 'ldap',
                    ... other options ...
                },
                My_MySQL => {
                    type => 'db',
                    ... other options ...
                },
                ... other sources ...
            } );

        As shown above, each description should have 'type' defined. The
        following types are supported:

        ldap
            Authenticate against and sync information with LDAP servers. See
            RT::Authen::ExternalAuth::LDAP for details.

        db  Authenticate against and sync information with external RDBMS,
            supported by Perl's DBI interface. See
            RT::Authen::ExternalAuth::DBI for details.

        cookie
            Authenticate by cookie. See
            RT::Authen::ExternalAuth::DBI::Cookie for details.

        See the modules noted above for configuration options specific to
        each type. The following apply to all types.

        attr_match_list
            The list of RT attributes that uniquely identify a user. These
            values are used, in order, to find users in the selected
            authentication source. Each value specified here must have a
            mapping in the "attr_map" section below. You can remove values
            you don't expect to match, but we recommend using Name and
            EmailAddress at a minimum. For example:

                'attr_match_list' => [
                    'Name',
                    'EmailAddress',
                ],

            You should not use items that can map to multiple users (such as
            a RealName or building name).

        attr_map
            Mapping of RT attributes on to attributes in the external
            source. Valid keys are attributes of an RT::User
            <http://bestpractical.com/rt/docs/latest/RT/User.html>. The
            values are attributes from your authentication source. For
            example, an LDAP mapping might look like:

                'attr_map' => {
                    'Name'         => 'sAMAccountName',
                    'EmailAddress' => 'mail',
                    'Organization' => 'physicalDeliveryOfficeName',
                    'RealName'     => 'cn',
                    ...
                },

  Example
        # Use the below LDAP source for both authentication, as well as user
        # information
        Set( $ExternalAuthPriority, ["My_LDAP"] );
        Set( $ExternalInfoPriority, ["My_LDAP"] );

        # Users created from LDAP should be Privileged; this is a core RT
        # option.  Additionally, this is the 4.2 name for the option; for RT
        # 4.0, is it named $AutoCreate   See the core RT documentation at
        # http://docs.bestpractical.com/RT_Config#UserAutocreateDefaultsOnLogin
        # for for further details.
        Set( $UserAutocreateDefaultsOnLogin, { Privileged => 1 } );

        # Users should still be autocreated by RT as internal users if they
        # fail to exist in an external service; this is so requestors (who
        # are not in LDAP) can still be created when they email in.
        Set($AutoCreateNonExternalUsers, 1);

        # Minimal LDAP configuration; see RT::Authen::ExternalAuth::LDAP for
        # further details and examples
        Set($ExternalSettings, {
            'My_LDAP'       =>  {
                'type'             =>  'ldap',
                'server'           =>  'ldap.example.com',
                # By not passing 'user' and 'pass' we are using an anonymous
                # bind, which some servers to not allow
                'base'             =>  'ou=Staff,dc=example,dc=com',
                'filter'           =>  '(objectClass=inetOrgPerson)',
                # Users are allowed to log in via email address or account
                # name
                'attr_match_list'  => [
                    'Name',
                    'EmailAddress',
                ],
                # Import the following properties of the user from LDAP upon
                # login
                'attr_map' => {
                    'Name'         => 'sAMAccountName',
                    'EmailAddress' => 'mail',
                    'RealName'     => 'cn',
                    'WorkPhone'    => 'telephoneNumber',
                    'Address1'     => 'streetAddress',
                    'City'         => 'l',
                    'State'        => 'st',
                    'Zip'          => 'postalCode',
                    'Country'      => 'co',
                },
            },
        } );

AUTHORS
    Best Practical Solutions, LLC <modules@bestpractical.com>

    Originally by Mike Peachey (Jennic Ltd.) <zordrak@cpan.org>

BUGS
    All bugs should be reported via email to

        L<bug-RT-Authen-ExternalAuth@rt.cpan.org|mailto:bug-RT-Authen-ExternalAuth@rt.cpan.org>

    or via the web at

        L<rt.cpan.org|http://rt.cpan.org/Public/Dist/Display.html?Name=RT-Authen-ExternalAuth>.

LICENSE AND COPYRIGHT
    Copyright (c) 2008-2014 by Best Practical Solutions, LLC Copyright (c)
    2008 by Jennic Ltd.

    This is free software, licensed under:

      The GNU General Public License, Version 2, June 1991

  constant_time_eq($a, $b)
    Taken verbatim from RT 4.4's RT::Util.