NAME

       RT::Authen::ExternalAuth::DBI - External database source for RT authentication

DESCRIPTION

       Provides the database implementation for RT::Authen::ExternalAuth.

SYNOPSIS

           Set($ExternalSettings, {
               'My_MySQL'   =>  {
                   'type'                      =>  'db',

                   'dbi_driver'                =>  'DBI_DRIVER',

                   'server'                    =>  'server.domain.tld',
                   'port'                      =>  'DB_PORT',
                   'user'                      =>  'DB_USER',
                   'pass'                      =>  'DB_PASS',

                   'database'                  =>  'DB_NAME',
                   'table'                     =>  'USERS_TABLE',
                   'u_field'                   =>  'username',
                   'p_field'                   =>  'password',

                   # Example of custom hashed password check
                   # (See below for security concerns with this implementation)
                   #'p_check'                   =>  sub {
                   #    my ($hash_from_db, $password) = @_;
                   #    return $hash_from_db eq function($password);
                   #},

                   'p_enc_pkg'                 =>  'Crypt::MySQL',
                   'p_enc_sub'                 =>  'password',
                   'p_salt'                    =>  'SALT',

                   'd_field'                   =>  'disabled',
                   'd_values'                  =>  ['0'],

                   'attr_match_list' =>  [
                       'Gecos',
                       'Name',
                   ],
                   'attr_map' => {
                       'Name'           => 'username',
                       'EmailAddress'   => 'email',
                       'ExternalAuthId' => 'username',
                       'Gecos'          => 'userID',
                   },
               },
           } );

CONFIGURATION

       DBI-specific options are described here. Shared options are described in the etc/RT_SiteConfig.pm file
       included in this distribution.

       The example in the "SYNOPSIS" lists all available options and they are described below. See the DBI
       module for details on debugging connection issues.

       dbi_driver
           The name of the Perl DBI driver to use (e.g. mysql, Pg, SQLite).

       server
           The server hosting the database.

       port
           The port to use to connect on (e.g. 3306).

       user
           The database user for the connection.

       pass
           The password for the database user.

       database
           The database name.

       table
           The database table containing the user information to check against.

       u_field
           The field in the table that holds usernames

       p_field
           The field in the table that holds passwords

       p_check
           Optional.   An  anonymous subroutine definition used to check the (presumably hashed) passed from the
           database with the password entered by the user logging in.  The  subroutine  should  return  true  on
           success  and false on failure.  The configuration options "p_enc_pkg" and "p_enc_sub" will be ignored
           when "p_check" is defined.

           An example, where "FooBar()" is some external hashing function:

               p_check => sub {
                   my ($hash_from_db, $password) = @_;
                   return $hash_from_db eq FooBar($password);
               },

           Importantly, the "p_check"  subroutine  allows  for  arbitrarily  complex  password  checking  unlike
           "p_enc_pkg" and "p_enc_sub".

           Please  note,  the  use  of  the  "eq"  operator  in  the "p_check" example above introduces a timing
           sidechannel vulnerability. (It was left there for clarity of the  example.)  There  is  a  comparison
           function available in this extension that is hardened against timing attacks. The comparison from the
           above example could be re-written with it like this:

               p_check => sub {
                   my ($hash_from_db, $password) = @_;
                   return RT::Authen::ExternalAuth::constant_time_eq($hash_from_db, FooBar($password));
               },

       p_enc_pkg, p_enc_sub
           The  Perl  package  and  subroutine  used to encrypt passwords from the database. For example, if the
           passwords are stored using the MySQL v3.23 "PASSWORD" function, then you will need  the  Crypt::MySQL
           "password"  function,  but  for  the  MySQL4+  password  you  will  need Crypt::MySQL's "password41".
           Alternatively, you could use Digest::MD5 "md5_hex" or any other encryption subroutine you can load in
           your Perl installation.

       p_salt
           If p_enc_sub takes a salt as a second parameter then set it here.

       d_field, d_values
           The field and values in the table that determines if a user should be disabled. For example,  if  the
           field  is 'user_status' and the values are ['0','1','2','disabled'] then the user will be disabled if
           their user_status is set to '0','1','2' or the string 'disabled'.  Otherwise, they will be considered
           enabled.

perl v5.22.1                                       2017-06-24                 RT::Authen::ExternalAuth::DBI(3pm)