.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "RT::Authen::ExternalAuth::DBI 3pm"
.TH RT::Authen::ExternalAuth::DBI 3pm "2017-06-14" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
RT::Authen::ExternalAuth::DBI \- External database source for RT authentication
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Provides the database implementation for RT::Authen::ExternalAuth.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    Set($ExternalSettings, {
\&        \*(AqMy_MySQL\*(Aq   =>  {
\&            \*(Aqtype\*(Aq                      =>  \*(Aqdb\*(Aq,
\&
\&            \*(Aqdbi_driver\*(Aq                =>  \*(AqDBI_DRIVER\*(Aq,
\&
\&            \*(Aqserver\*(Aq                    =>  \*(Aqserver.domain.tld\*(Aq,
\&            \*(Aqport\*(Aq                      =>  \*(AqDB_PORT\*(Aq,
\&            \*(Aquser\*(Aq                      =>  \*(AqDB_USER\*(Aq,
\&            \*(Aqpass\*(Aq                      =>  \*(AqDB_PASS\*(Aq,
\&
\&            \*(Aqdatabase\*(Aq                  =>  \*(AqDB_NAME\*(Aq,
\&            \*(Aqtable\*(Aq                     =>  \*(AqUSERS_TABLE\*(Aq,
\&            \*(Aqu_field\*(Aq                   =>  \*(Aqusername\*(Aq,
\&            \*(Aqp_field\*(Aq                   =>  \*(Aqpassword\*(Aq,
\&
\&            # Example of custom hashed password check
\&            # (See below for security concerns with this implementation)
\&            #\*(Aqp_check\*(Aq                   =>  sub {
\&            #    my ($hash_from_db, $password) = @_;
\&            #    return $hash_from_db eq function($password);
\&            #},
\&
\&            \*(Aqp_enc_pkg\*(Aq                 =>  \*(AqCrypt::MySQL\*(Aq,
\&            \*(Aqp_enc_sub\*(Aq                 =>  \*(Aqpassword\*(Aq,
\&            \*(Aqp_salt\*(Aq                    =>  \*(AqSALT\*(Aq,
\&
\&            \*(Aqd_field\*(Aq                   =>  \*(Aqdisabled\*(Aq,
\&            \*(Aqd_values\*(Aq                  =>  [\*(Aq0\*(Aq],
\&
\&            \*(Aqattr_match_list\*(Aq =>  [
\&                \*(AqGecos\*(Aq,
\&                \*(AqName\*(Aq,
\&            ],
\&            \*(Aqattr_map\*(Aq => {
\&                \*(AqName\*(Aq           => \*(Aqusername\*(Aq,
\&                \*(AqEmailAddress\*(Aq   => \*(Aqemail\*(Aq,
\&                \*(AqExternalAuthId\*(Aq => \*(Aqusername\*(Aq,
\&                \*(AqGecos\*(Aq          => \*(AquserID\*(Aq,
\&            },
\&        },
\&    } );
.Ve
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
DBI-specific options are described here. Shared options
are described in the \fIetc/RT_SiteConfig.pm\fR file included
in this distribution.
.PP
The example in the \*(L"\s-1SYNOPSIS\*(R"\s0 lists all available options
and they are described below. See the \s-1DBI\s0 module for details
on debugging connection issues.
.IP "dbi_driver" 4
.IX Item "dbi_driver"
The name of the Perl \s-1DBI\s0 driver to use (e.g. mysql, Pg, SQLite).
.IP "server" 4
.IX Item "server"
The server hosting the database.
.IP "port" 4
.IX Item "port"
The port to use to connect on (e.g. 3306).
.IP "user" 4
.IX Item "user"
The database user for the connection.
.IP "pass" 4
.IX Item "pass"
The password for the database user.
.IP "database" 4
.IX Item "database"
The database name.
.IP "table" 4
.IX Item "table"
The database table containing the user information to check against.
.IP "u_field" 4
.IX Item "u_field"
The field in the table that holds usernames
.IP "p_field" 4
.IX Item "p_field"
The field in the table that holds passwords
.IP "p_check" 4
.IX Item "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 \f(CW\*(C`p_enc_pkg\*(C'\fR and \f(CW\*(C`p_enc_sub\*(C'\fR will be ignored when
\&\f(CW\*(C`p_check\*(C'\fR is defined.
.Sp
An example, where \f(CW\*(C`FooBar()\*(C'\fR is some external hashing function:
.Sp
.Vb 4
\&    p_check => sub {
\&        my ($hash_from_db, $password) = @_;
\&        return $hash_from_db eq FooBar($password);
\&    },
.Ve
.Sp
Importantly, the \f(CW\*(C`p_check\*(C'\fR subroutine allows for arbitrarily complex password
checking unlike \f(CW\*(C`p_enc_pkg\*(C'\fR and \f(CW\*(C`p_enc_sub\*(C'\fR.
.Sp
Please note, the use of the \f(CW\*(C`eq\*(C'\fR operator in the \f(CW\*(C`p_check\*(C'\fR 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:
.Sp
.Vb 4
\&    p_check => sub {
\&        my ($hash_from_db, $password) = @_;
\&        return RT::Authen::ExternalAuth::constant_time_eq($hash_from_db, FooBar($password));
\&    },
.Ve
.IP "p_enc_pkg, p_enc_sub" 4
.IX Item "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 \*(L"\s-1PASSWORD\*(R"\s0 function, then you will need the Crypt::MySQL
\&\f(CW\*(C`password\*(C'\fR function, but for the MySQL4+ password you will need
Crypt::MySQL's \f(CW\*(C`password41\*(C'\fR. Alternatively, you could use
Digest::MD5 \f(CW\*(C`md5_hex\*(C'\fR or any other encryption subroutine you can
load in your Perl installation.
.IP "p_salt" 4
.IX Item "p_salt"
If p_enc_sub takes a salt as a second parameter then set it here.
.IP "d_field, d_values" 4
.IX Item "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.