• NAME
• DESCRIPTION
• CONFIGURATION
  • Example

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 functionality 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.

CONFIGURATION

RT::Authen::ExternalAuth provides a lot of flexibility with many configuration options. The following describes these configuration options, and provides a complete example. As with all RT configuration, you set these values in RT_SiteConfig.pm or for RT 4.4 or later in a custom configuration file in the directory RT_SiteConfig.d.

$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. For example, an LDAP mapping might look like:

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

The values in the mapping (i.e. the fields in external source, the right hand side) can be one of the following:

an attribute/field

External field to use. Only first value is used if field is multivalue(could happen in LDAP). For example:

    EmailAddress => 'mail',

an array reference

The LDAP attributes can also be an arrayref of external fields, for example:

    WorkPhone => [qw/CompanyPhone Extension/]

which will be concatenated together with a space. First values of each field are used in case they have multiple values.

a subroutine reference

The external field can also be a subroutine reference that does mapping. E.g.

    YYY => sub {
        my %args = @_;

        return 'XXX' unless $args{external_entry};

        my @values = grep defined && length, $args{external_entry}->get_value('XXX');
        return @values;
    },

The following arguments are passed into the function in a hash:

external_entry

For type "ldap", it's an instance of Net::LDAP::Entry. For type "db", it's a hashref of the result row.

mapping

Hash reference of the attr_map value.

rt_field and external_field

The currently processed key and value from the mapping.

The subroutine is called in 2 modes: when called with external_entry specified, it should return value or list of values, otherwise, it should return the external field list it depends on, so RT could retrieve them at the beginning.

The keys in the mapping (i.e. the RT fields, the left hand side) may be a user custom field name prefixed with UserCF., for example 'UserCF.Employee Number' => 'employeeId'. Note that this only adds values at the moment, which on single value CFs will remove any old value first. Multiple value CFs may behave not quite how you expect. If the attribute no longer exists on a user in external source, it will be cleared on the RT side as well.

You may also prefix any RT custom field name with CF. inside your mapping to add available values to a Select custom field. This effectively takes user attributes in external source and adds the values as selectable options in a CF. It does not set a CF value on any RT object (User, Ticket, Queue, etc). You might use this to populate a ticket Location CF with all the locations of your users so that tickets can be associated with the locations in use.

Example

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

    # Make users created from LDAP Privileged
    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',
            },
        },
    } );