---
name: "RT::Authen::ExternalAuth::DBI"
section: "3pm"
platform: "linux"
package: "rt4-extension-authenexternalauth"
version: "0.25-1+deb8u1"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/RT::Authen::ExternalAuth::DBI"
---

# RT::Authen::ExternalAuth::DBI(3pm)

External database source for RT authentication

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