File: external-backends.xml

package info (click to toggle)
otrs2-doc 20100124-1
links: PTS
area: main
in suites: squeeze
size: 11,184 kB
ctags: 1
sloc: xml: 21,123; sh: 126; makefile: 12
file content (1158 lines) | stat: -rw-r--r-- 41,676 bytes
<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
  <!-- $Id: external-backends.xml,v 1.13 2009/12/22 12:48:17 mb Exp $ -->

<chapter id="external-backends">
<title>Using external backends</title>

<sect1 id='customer-data'>
<title>Customer data</title>

<para>
OTRS is able to handle different customer data, e.g. login, email, phone
number. These information can be displaied in the customer interface and
they are useable in the customer frontend. Also these data are used for the
authentication of customer users.
</para>

<para>
The used / displaied customer data are freely configurable, but without the
following data OTRS won't work, this information is allways needed for the
authentication of customers.
</para>

<para>
<itemizedlist>
  <title>Necesary data needed for customer authentication</title>
    <listitem>
    <para>
    User login
    </para>
    </listitem>
    <listitem>
    <para>
    Email address
    </para>
    </listitem>
    <listitem>
    <para>
    Customer ID
    </para>
    </listitem>
</itemizedlist>
</para>

<para>
Use the following configuration parameters in your
<filename>Kernel/Config.pm</filename> file, if you want to display customer
information in your agent interface.
</para>

<para>
<programlisting>
    # Ticket::Frontend::CustomerInfo*
    # (show customer user info on Compose (Phone and Email), Zoom and
    # Queue view)
    $Self->{'Ticket::Frontend::CustomerInfoCompose'} = 1;
    $Self->{'Ticket::Frontend::CustomerInfoZoom'} = 1;
    $Self->{'Ticket::Frontend::CustomerInfoQueue'} = 0;
</programlisting>
</para>
</sect1>

<sect1 id="customer-user-backend">
<title>Customer user backend</title>

<para>
You can use two types of customer backends, DB and LDAP. If you allready have
another customer backend (e.g. SAP) it is ofcourse possible to write a
module that uses this type of backend.
</para>

<sect2 id='customer-backend-db'>
<title>Database (Default)</title>

<example id='db-customer-backend'>
<title>Configuring a DB customer backend</title>

<para>
This example shows the configuration of a DB customer backend which
uses customer data stored in the OTRS database.
</para>

<para>
<programlisting>
    # CustomerUser
    # (customer user database backend and settings)
    $Self->{CustomerUser} = {
        Name => 'Datenbank Quelle',
        Module => 'Kernel::System::CustomerUser::DB',
        Params => {
            # if you want to use an external database, add the
            # required settings
#            DSN => 'DBI:odbc:yourdsn',
#            DSN => 'DBI:mysql:database=customerdb;host=customerdbhost',
#            User => '',
#            Password => '',
            Table => 'customer_user',
        },
        # customer uniq id
	CustomerKey => 'login',
        # customer #
	CustomerID => 'customer_id',
	CustomerValid => 'valid_id',
        CustomerUserListFields => ['first_name', 'last_name', 'email'],
        CustomerUserSearchFields => ['login', 'last_name', 'customer_id'],
        CustomerUserSearchPrefix => '',
        CustomerUserSearchSuffix => '*',
        CustomerUserSearchListLimit => 250,
        CustomerUserPostMasterSearchFields => ['email'],
        CustomerUserNameFields => ['salutation','first_name','last_name'],
        CustomerUserEmailUniqCheck => 1,
#        # show not own tickets in customer panel, CompanyTickets
#        CustomerUserExcludePrimaryCustomerID => 0,
#        # generate auto logins
#        AutoLoginCreation => 0,
#        AutoLoginCreationPrefix => 'auto',
#        # admin can change customer preferences
#        AdminSetPreferences => 1,
#        # cache time to life in sec. - cache any database queris
#        CacheTTL => 0,
#        # just a read only source
#        ReadOnly => 1,
        Map => [
            # note: Login, Email and CustomerID needed!
            # var, frontend, storage, shown (1=always,2=lite), required, storage-type, http-link, readonly, http-link-target
            [ 'UserSalutation', 'Salutation', 'salutation', 1, 0, 'var', '', 0 ],
            [ 'UserFirstname',  'Firstname',  'first_name', 1, 1, 'var', '', 0 ],
            [ 'UserLastname',   'Lastname',   'last_name',  1, 1, 'var', '', 0 ],
            [ 'UserLogin',      'Username',   'login',      1, 1, 'var', '', 0 ],
            [ 'UserPassword',   'Password',   'pw',         0, 0, 'var', '', 0 ],
            [ 'UserEmail',      'Email',      'email',      1, 1, 'var', '', 0 ],

#            [ 'UserEmail',      'Email', 'email',           1, 1, 'var', '$Env{"CGIHandle"}?Action=AgentTicketCompose&amp;ResponseID=1&amp;TicketID=$Data{"TicketID"}&amp;ArticleID=$Data{"ArticleID"}', 0 ],
            [ 'UserCustomerID', 'CustomerID', 'customer_id', 0, 1, 'var', '', 0 ],

#            [ 'UserCustomerIDs', 'CustomerIDs', 'customer_ids', 1, 0, 'var', '', 0 ],
            [ 'UserPhone',        'Phone',       'phone',        1, 0, 'var', '', 0 ],
            [ 'UserFax',          'Fax',         'fax',          1, 0, 'var', '', 0 ],
            [ 'UserMobile',       'Mobile',      'mobile',       1, 0, 'var', '', 0 ],
            [ 'UserStreet',       'Street',      'street',       1, 0, 'var', '', 0 ],
            [ 'UserZip',          'Zip',         'zip',          1, 0, 'var', '', 0 ],
            [ 'UserCity',         'City',        'city',         1, 0, 'var', '', 0 ],
            [ 'UserCountry',      'Country',     'country',      1, 0, 'var', '', 0 ],
            [ 'UserComment',      'Comment',     'comments',     1, 0, 'var', '', 0 ],
            [ 'ValidID',          'Valid',       'valid_id',     0, 1, 'int', '', 0 ],
        ],
        # default selections
        Selections => {
            UserSalutation => {
                'Mr.' => 'Mr.',
                'Mrs.' => 'Mrs.',
            },
        },
    };
</programlisting>
</para>

</example>

<para>
If you want to customize the customer data, change the table columns in
the customer_user table in the OTRS database or add new columns. In the
following example a new field for room number is added.
</para>

<para>
<screen>
linux:~# mysql -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 116 to server version: 5.0.18-Debian_7-log

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql&gt; use otrs;
Reading table information for completion of table and column names
You can turn off this feature to get a quicker startup with -A

Database changed
mysql&gt; ALTER TABLE customer_user ADD room VARCHAR (250);
Query OK, 1 rows affected (0.01 sec)
Records: 1  Duplicates: 0  Warnings: 0

mysql&gt; quit
Bye
linux:~#
</screen>
</para>

<para>
Now add the new column to the MAP array in
<filename>Kernel/Config.pm</filename>:
</para>

<para>
<programlisting>
    # var, frontend, storage, shown (1=always,2=lite), required, storage-type, http-link, readonly
    [...]
    [ 'UserRoom',      'Room',      'room',       0, 1, 'var', '', 0 ],
</programlisting>
</para>

<para>
Ofcourse it is possible to edit all these customer information via the
customer area in the agent interface.
</para>

<sect3 id='multi-customer-ids-db'>
<title>Customer with multiple IDs (Company tickets)</title>

<para>
It is possible to assign more than one customer ID to a customer. This can
be usefull if a customer must access tickets of other customers, e.g. a
supervisor wants to watch the tickets of his assistants. If a customer can
access the tickets of another customer user, the company ticket feature of
OTRS is used. Company tickets can be accessed via the  "Company Ticket"
link in the customer panel.
</para>

<para>
To use company tickets a new column has to be added to the customer_user
table in the OTRS database. In this new column the IDs of the customers
are stored that tickets need to be accessed.
</para>

<para>
<screen>
linux:~# mysql -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 124 to server version: 5.0.18-Debian_7-log

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql&gt; use otrs;
Reading table information for completion of table and column names
You can turn off this feature to get a quicker startup with -A

Database changed
mysql&gt; ALTER TABLE customer_user ADD customer_ids VARCHAR (250);
Query OK, 1 rows affected (0.02 sec)
Records: 1  Duplicates: 0  Warnings: 0

mysql&gt; quit
Bye
linux:~#
</screen>
</para>

<para>
Now the new column has to be added to the MAP array in
<filename>Kernel/Config.pm</filename>:
</para>

<para>
<programlisting>
    # var, frontend, storage, shown (1=always,2=lite), required, storage-type, http-link, readonly
    [...]
    [ 'UserCustomerIDs', 'CustomerIDs', 'customer_ids', 1, 0, 'var', '', 0 ],
</programlisting>
</para>

<para>
The new column for the multi customer IDs can be edited via the agent
interface in the section for the customer user management now.
</para>

<para>
To ensure that one customer can access the tickets of other customer users
add the IDs of this other users into the new field for the multiple
customer IDs. Each ID hast to be seperated by a semicolon.
</para>

<example id='company-tickets-db'>
<title>Using company tickets with a DB backend</title>

<para>
The customers A, B and C exists in your system and A wants to have
access to the tickets of B and C via the customer panel. B and C should have
no access to the tickets of other users.
</para>

<para>
To realize this setup change the customer_user table and the mapping in
<filename>Kernel/Config.pm</filename> like described above. Then load the
settings for customer A via the customer area in the agent interface or via
the admin area. If the settings are displaied add into the field for
CustomerIDs the values "B;C;".
</para>

</example>

</sect3>

</sect2>

<sect2 id='customer-backend-ldap'>
<title>LDAP</title>

<para>
If you have a LDAP directory with your customer data you can use it as
customer backend with OTRS.
</para>

<example id='ldap-customer-backend'>
<title>Configuring a LDAP customer backend</title>

<para>
This is a example for a customer backend that has stored all customer
information in a LDAP directory.
</para>

<para>
<programlisting>
    # CustomerUser
    # (customer user ldap backend and settings)
    $Self->{CustomerUser} = {
        Name => 'LDAP Datenquelle',
        Module => 'Kernel::System::CustomerUser::LDAP',
        Params => {
            # ldap host
            Host => 'bay.csuhayward.edu',
            # ldap base dn
            BaseDN => 'ou=seas,o=csuh',
            # search scope (one|sub)
            SSCOPE => 'sub',
#            # The following is valid but would only be necessary if the
#            # anonymous user does NOT have permission to read from the LDAP tree
            UserDN => '',
            UserPw => '',
            # in case you want to add always one filter to each ldap query, use
            # this option. e. g. AlwaysFilter => '(mail=*)' or AlwaysFilter => '(objectclass=user)'
            AlwaysFilter => '',
            # if your frontend is e. g. iso-8859-1 and the charset of your
            # ldap server is utf-8, use this options (if not, ignore it)
#            SourceCharset => 'utf-8',
#            DestCharset => 'iso-8859-1',
            # Net::LDAP new params (if needed - for more info see perldoc Net::LDAP)
            Params => {
                port => 389,
                timeout => 120,
                async => 0,
                version => 3,
            },
        },
        # customer uniq id
        CustomerKey => 'uid',
        # customer #
        CustomerID => 'mail',
        CustomerUserListFields => ['cn', 'mail'],
        CustomerUserSearchFields => ['uid', 'cn', 'mail'],
        CustomerUserSearchPrefix => '',
        CustomerUserSearchSuffix => '*',
        CustomerUserSearchListLimit => 250,
        CustomerUserPostMasterSearchFields => ['mail'],
        CustomerUserNameFields => ['givenname', 'sn'],
        # show not own tickets in customer panel, CompanyTickets
        CustomerUserExcludePrimaryCustomerID => 0,
        # add a ldap filter for valid users (expert setting)
#       CustomerUserValidFilter => '(!(description=gesperrt))',
        # admin can't change customer preferences
        AdminSetPreferences => 0,
#        # cache time to life in sec. - cache any database queris
#        CacheTTL => 0,
        Map => [
            # note: Login, Email and CustomerID needed!
            # var, frontend, storage, shown (1=always,2=lite), required, storage-type, http-link, readonly
            [ 'UserSalutation', 'Title',      'title',           1, 0, 'var', '', 0 ],
            [ 'UserFirstname',  'Firstname',  'givenname',       1, 1, 'var', '', 0 ],
            [ 'UserLastname',   'Lastname',   'sn',              1, 1, 'var', '', 0 ],
            [ 'UserLogin',      'Username',   'uid',             1, 1, 'var', '', 0 ],
            [ 'UserEmail',      'Email',      'mail',            1, 1, 'var', '', 0 ],
            [ 'UserCustomerID', 'CustomerID', 'mail',            0, 1, 'var', '', 0 ],
#            [ 'UserCustomerIDs', 'CustomerIDs', 'second_customer_ids', 1, 0, 'var', '', 0 ],
            [ 'UserPhone',      'Phone',      'telephonenumber', 1, 0, 'var', '', 0 ],
            [ 'UserAddress',    'Address',    'postaladdress',   1, 0, 'var', '', 0 ],
            [ 'UserComment',    'Comment',    'description',     1, 0, 'var', '', 0 ],
        ],
    };
</programlisting>
</para>

</example>

<para>
If additional customer information are stored in your LDAP directory and if you
like to use this information with OTRS also, just expand the MAP array in
<filename>Kernel/Config.pm</filename> with the entries for this data.
</para>

<para>
<programlisting>
    # var, frontend, storage, shown (1=always,2=lite), required, storage-type, http-link, readonly
    [...]
    [ 'UserPhone',      'Phone',      'telephonenumber', 1, 0, 'var', '', 0 ],
</programlisting>
</para>

<sect3 id='multi-customer-ids-ldap'>
<title>Customer with multiple IDs (Company tickets)</title>

<para>
It is possible to assign more than one customer ID to a customer. This can
be usefull if a customer must access tickets of other customers, e.g. a
supervisor wants to watch the tickets of his assistants. If a customer can
access the tickets of another customer user, the company ticket feature of
OTRS is used. Company tickets can be accessed via the  "Company Ticket"
link in the customer panel.
</para>

<para>
Du use company tickets a new field has to be added to the LDAP directory
that can contain the entries with the IDs for the customers that tickets
should be accessible for a customer user.
</para>

<para>
If the new field in the LDAP directory has been created the new entry
has to be added to the MAP array in
<filename>Kernel/Config.pm</filename>:
</para>

<para>
<programlisting>
    # var, frontend, storage, shown (1=always,2=lite), required, storage-type, http-link, readonly
    [...]
    [ 'UserCustomerIDs', 'CustomerIDs', 'customer_ids', 1, 0, 'var', '', 0 ],
</programlisting>
</para>

<para>
The field for the multiple customer IDs has to be edited directly in the
LDAP directory, OTRS can only read from LDAP.
</para>

<para>
To ensure the access for a customer to the tickets of other customers add
the customer IDs of the customers that tickets should be accessed to the
new field in your LDAP directory. Each ID has to be seperated by a
semicolon.
</para>

<example id='company-tickets-ldap'>
<title>Using Company tickets with a LDAP backend</title>

<para>
The customers A, B and C exists in your system and A wants to have
access to the tickets of B and C via the customer panel. B and C should have
no access to tickets of other users.
</para>

<para>
To realize this setup change the LDAP directory and the mapping in
<filename>Kernel/Config.pm</filename> like described above. Then
add into the field for CustomerIDs the values "B;C;" for customer A in your
LDAP directory.
</para>

</example>

</sect3>
</sect2>

<sect2 id='multiple-customer-backends'>
<title>Use more than one customer backend with OTRS</title>

<para>
If more than one customer backend with different customer data should be
used with OTRS (e.g. a LDAP and a DB backend), the CustomerUser config
parameter  has to be expanded with a number, e.g. "CustomerUser1",
"CustomerUser2".
</para>

<example id='multiple-customer-backend-example'>
<title>Using more than one customer backend with OTRS</title>

<para>
The following configuration example shows parallel usage of an LDAP and DB
customer backend with OTRS.
</para>

<para>
<programlisting>
    # 1. Customer user backend: DB
    # (customer user database backend and settings)
    $Self->{CustomerUser1} = {
        Name => 'Datenbank Quelle',
        Module => 'Kernel::System::CustomerUser::DB',
        Params => {
            # if you want to use an external database, add the
            # required settings
#            DSN => 'DBI:odbc:yourdsn',
#            DSN => 'DBI:mysql:database=customerdb;host=customerdbhost',
#            User => '',
#            Password => '',
            Table => 'customer_user',
        },
        # customer uniq id
        CustomerKey = 'login',
        # customer #
        CustomerID = 'customer_id',
        CustomerValid = 'valid_id',
        CustomerUserListFields => ['first_name', 'last_name', 'email'],
        CustomerUserSearchFields => ['login', 'last_name', 'customer_id'],
        CustomerUserSearchPrefix => '',
        CustomerUserSearchSuffix => '*',
        CustomerUserSearchListLimit => 250,
        CustomerUserPostMasterSearchFields => ['email'],
        CustomerUserNameFields => ['salutation','first_name','last_name'],
        CustomerUserEmailUniqCheck => 1,
#        # show not own tickets in customer panel, CompanyTickets
#        CustomerUserExcludePrimaryCustomerID => 0,
#        # generate auto logins
#        AutoLoginCreation => 0,
#        AutoLoginCreationPrefix => 'auto',
#        # admin can change customer preferences
#        AdminSetPreferences => 1,
#        # cache time to life in sec. - cache any database queris
#        CacheTTL => 0,
#        # just a read only source
#        ReadOnly => 1,
        Map => [

            # note: Login, Email and CustomerID needed!
            # var, frontend, storage, shown (1=always,2=lite), required, storage-type, http-link, readonly, http-link-target
            [ 'UserSalutation', 'Salutation', 'salutation',   1, 0, 'var', '', 0 ],
            [ 'UserFirstname',  'Firstname',  'first_name',   1, 1, 'var', '', 0 ],
            [ 'UserLastname',   'Lastname',   'last_name',    1, 1, 'var', '', 0 ],
            [ 'UserLogin',      'Username',   'login',        1, 1, 'var', '', 0 ],
            [ 'UserPassword',   'Password',   'pw',           0, 0, 'var', '', 0 ],
            [ 'UserEmail',      'Email',      'email',        1, 1, 'var', '', 0 ],
            [ 'UserCustomerID', 'CustomerID', 'customer_id',  0, 1, 'var', '', 0 ],
            [ 'UserPhone',      'Phone',      'phone',        1, 0, 'var', '', 0 ],
            [ 'UserFax',        'Fax',        'fax',          1, 0, 'var', '', 0 ],
            [ 'UserMobile',     'Mobile',     'mobile',       1, 0, 'var', '', 0 ],
            [ 'UserStreet',     'Street',     'street',       1, 0, 'var', '', 0 ],
            [ 'UserZip',        'Zip',        'zip',          1, 0, 'var', '', 0 ],
            [ 'UserCity',       'City',       'city',         1, 0, 'var', '', 0 ],
            [ 'UserCountry',    'Country',    'country',      1, 0, 'var', '', 0 ],
            [ 'UserComment',    'Comment',    'comments',     1, 0, 'var', '', 0 ],
            [ 'ValidID',        'Valid',      'valid_id',     0, 1, 'int', '', 0 ],
        ],
        # default selections
        Selections => {
            UserSalutation => {
                'Mr.' => 'Mr.',
                'Mrs.' => 'Mrs.',
            },
        },
    };

    # 2. Customer user backend: LDAP
    # (customer user ldap backend and settings)
    $Self->{CustomerUser2} = {
        Name => 'LDAP Datenquelle',
        Module => 'Kernel::System::CustomerUser::LDAP',
        Params => {
            # ldap host
            Host => 'bay.csuhayward.edu',
            # ldap base dn
            BaseDN => 'ou=seas,o=csuh',
            # search scope (one|sub)
            SSCOPE => 'sub',
#            # The following is valid but would only be necessary if the
#            # anonymous user does NOT have permission to read from the LDAP tree
            UserDN => '',
            UserPw => '',
            # in case you want to add always one filter to each ldap query, use
            # this option. e. g. AlwaysFilter => '(mail=*)' or AlwaysFilter => '(objectclass=user)'
            AlwaysFilter => '',
            # if your frontend is e. g. iso-8859-1 and the charset of your
            # ldap server is utf-8, use this options (if not, ignore it)
#            SourceCharset => 'utf-8',
#            DestCharset => 'iso-8859-1',
            # Net::LDAP new params (if needed - for more info see perldoc Net::LDAP)
            Params => {
                port => 389,
                timeout => 120,
                async => 0,
                version => 3,
            },
        },
        # customer uniq id
        CustomerKey => 'uid',
        # customer #
        CustomerID => 'mail',
        CustomerUserListFields => ['cn', 'mail'],
        CustomerUserSearchFields => ['uid', 'cn', 'mail'],
        CustomerUserSearchPrefix => '',
        CustomerUserSearchSuffix => '*',
        CustomerUserSearchListLimit => 250,
        CustomerUserPostMasterSearchFields => ['mail'],
        CustomerUserNameFields => ['givenname', 'sn'],
        # show not own tickets in customer panel, CompanyTickets
        CustomerUserExcludePrimaryCustomerID => 0,
        # add a ldap filter for valid users (expert setting)
#       CustomerUserValidFilter => '(!(description=gesperrt))',
        # admin can't change customer preferences
        AdminSetPreferences => 0,
        Map => [
            # note: Login, Email and CustomerID needed!
            # var, frontend, storage, shown (1=always,2=lite), required, storage-type, http-link, readonly
            [ 'UserSalutation', 'Title',      'title',           1, 0, 'var', '', 0 ],
            [ 'UserFirstname',  'Firstname',  'givenname',       1, 1, 'var', '', 0 ],
            [ 'UserLastname',   'Lastname',   'sn',              1, 1, 'var', '', 0 ],
            [ 'UserLogin',      'Username',   'uid',             1, 1, 'var', '', 0 ],
            [ 'UserEmail',      'Email',      'mail',            1, 1, 'var', '', 0 ],
            [ 'UserCustomerID', 'CustomerID', 'mail',            0, 1, 'var', '', 0 ],
#            [ 'UserCustomerIDs', 'CustomerIDs', 'second_customer_ids', 1, 0, 'var', '', 0 ],
            [ 'UserPhone',      'Phone',      'telephonenumber', 1, 0, 'var', '', 0 ],
            [ 'UserAddress',    'Address',    'postaladdress',   1, 0, 'var', '', 0 ],
            [ 'UserComment',    'Comment',    'description',     1, 0, 'var', '', 0 ],
        ],
    };
</programlisting>
</para>

</example>

<para>
It is possible to integrate up to 10 different customer user backends. With
the customer user management interface in OTRS all customer data can be
viewed or edited (if write access is possible).
</para>

</sect2>

</sect1>

<sect1 id="auth-backends">
<title>Backends to authenticate agents and customer users</title>

<para>
OTRS offers the option to authenticate agents and customers against
different backends.
</para>

<sect2 id='agent-auth-backends'>
<title>authentication backends for agents</title>

<sect3 id='agent-auth-backend-db'>
<title>DB (Default)</title>

<para>
The backend to authenticate agents which is used per default is the
OTRS database. Agents can be added and edited via the

<link linkend="adminarea-user">
user management interface
</link>

in the

<link linkend="adminarea">
admin area
</link>

</para>

<example id='configuration-agent-auth-backend-db'>
<title>Authenticate agents against a DB backend</title>

<para>
<programlisting>
    $Self->{'AuthModule'} = 'Kernel::System::Auth::DB';
</programlisting>
</para>

</example>

</sect3>

<sect3 id='agent-auth-backend-ldap'>
<title>LDAP</title>

<para>
If a LDAP directory has all your agent data stored you can use the LDAP
module to authenticate your users in OTRS. This module has only read access
to the LDAP tree, that means you can't edit your users via the

<link linkend='adminarea-user'>
user management interface
</link>

</para>

<example id='configuration-agent-auth-backend-ldap'>
<title>Authenticate agents against a LDAP backend</title>

<para>
<programlisting>
    # This is an example configuration for an LDAP auth. backend.
    # (take care that Net::LDAP is installed!)
    $Self->{'AuthModule'} = 'Kernel::System::Auth::LDAP';
    $Self->{'AuthModule::LDAP::Host'} = 'ldap.example.com';
    $Self->{'AuthModule::LDAP::BaseDN'} = 'dc=example,dc=com';
    $Self->{'AuthModule::LDAP::UID'} = 'uid';

    # Check if the user is allowed to auth in a posixGroup
    # (e. g. user needs to be in a group xyz to use otrs)
    $Self->{'AuthModule::LDAP::GroupDN'} = 'cn=otrsallow,ou=posixGroups,dc=example,dc=com';
    $Self->{'AuthModule::LDAP::AccessAttr'} = 'memberUid';
    # for ldap posixGroups objectclass (just uid)
#    $Self->{'AuthModule::LDAP::UserAttr'} = 'UID';
    # for non ldap posixGroups objectclass (with full user dn)
#    $Self->{'AuthModule::LDAP::UserAttr'} = 'DN';

    # The following is valid but would only be necessary if the
    # anonymous user do NOT have permission to read from the LDAP tree
    $Self->{'AuthModule::LDAP::SearchUserDN'} = '';
    $Self->{'AuthModule::LDAP::SearchUserPw'} = '';

    # in case you want to add always one filter to each ldap query, use
    # this option. e. g. AlwaysFilter => '(mail=*)' or AlwaysFilter => '(objectclass=user)'
    $Self->{'AuthModule::LDAP::AlwaysFilter'} = '';

    # in case you want to add a suffix to each login name, then
    # you can use this option. e. g. user just want to use user but
    # in your ldap directory exists user@domain.
#    $Self->{'AuthModule::LDAP::UserSuffix'} = '@domain.com';

    # Net::LDAP new params (if needed - for more info see perldoc Net::LDAP)
    $Self->{'AuthModule::LDAP::Params'} = {
        port => 389,
        timeout => 120,
        async => 0,
        version => 3,
    };
</programlisting>
</para>

</example>

<para>
The following configuration parameters can be used to synchronize the
user data from your LDAP directory into your local OTRS database. This
reduces the number of requests to your LDAP server and speeds up the
authentication
with OTRS. The data sync is done when the agent authenticates the first
time. Although the data can be synced into the local OTRS database the
LDAP directory is the last instance for the authentication, so an inactive
user in the LDAP tree can't authenticate to OTRS even when the account data
is already stored in the OTRS database. The agent data in the LDAP
directory can't be edited via the web interface of OTRS, so the data
has to be managed directly in the LDAP tree.
</para>

<para>
<programlisting>

    # agent data sync against ldap
    $Self->{'AuthSyncModule'} = 'Kernel::System::Auth::Sync::LDAP';
    $Self->{'AuthSyncModule::LDAP::Host'} = 'ldap://ldap.example.com/';
    $Self->{'AuthSyncModule::LDAP::BaseDN'} = 'dc=otrs, dc=org';
    $Self->{'AuthSyncModule::LDAP::UID'} = 'uid';
    $Self->{'AuthSyncModule::LDAP::SearchUserDN'} = 'uid=sys, ou=user, dc=otrs, dc=org';
    $Self->{'AuthSyncModule::LDAP::SearchUserPw'} = 'some_pass';
    $Self->{'AuthSyncModule::LDAP::UserSyncMap'} = {
        # DB -> LDAP
        UserFirstname => 'givenName',
        UserLastname  => 'sn',
        UserEmail     => 'mail',
    };
    [...]

    # AuthSyncModule::LDAP::UserSyncInitialGroups
    # (sync following group with rw permission after initial create of first agent
    # login)
    $Self->{'AuthSyncModule::LDAP::UserSyncInitialGroups'} = [
        'users',
    ];

</programlisting>
</para>

</sect3>

<sect3 id='agent-auth-backend-httpbasic'>
<title>HTTPBasicAuth for agents</title>

<para>
If you want to implement a "single sign on" solution for all your agents,
you can use http basic authentication (for all your systems) and the
HTTPBasicAuth module for OTRS.
</para>

<example id='configuration-agent-auth-backend-htbasic'>
<title>Authenticate agents using HTTPBasic</title>

<para>
<programlisting>
    # This is an example configuration for an apache ($ENV{REMOTE_USER})
    # auth. backend. Use it if you want to have a singe login through
    # apache http-basic-auth
    $Self->{'AuthModule'} = 'Kernel::System::Auth::HTTPBasicAuth';

    # Note:
    #
    # If you use this module, you should use as fallback
    # the following config settings if user isn't login through
    # apache ($ENV{REMOTE_USER})
    $Self->{LoginURL} = 'http://host.example.com/not-authorised-for-otrs.html';
    $Self->{LogoutURL} = 'http://host.example.com/thanks-for-using-otrs.html';
</programlisting>
</para>

</example>

</sect3>

<sect3 id='agent-auth-backend-radius'>
<title>Radius</title>

<para>
The following configuration parameters can be used to authenticate agents
against a radius server.
</para>

<example id='configuration-agent-auth-backend-radius'>
<title>Authenticate agents against a radius backend</title>

<para>
<programlisting>
    # This is example configuration to auth. agents against a radius server
    $Self->{'AuthModule'} = 'Kernel::System::Auth::Radius';
    $Self->{'AuthModule::Radius::Host'} = 'radiushost';
    $Self->{'AuthModule::Radius::Password'} = 'radiussecret';
</programlisting>
</para>

</example>

</sect3>

</sect2>

<sect2 id="customer-auth-backends">
<title>authentication backends for customer users</title>

<sect3 id='customer-auth-backend-db'>
<title>Database (Default)</title>

<para>
The authentication backend for customer users which is used per default
by OTRS is the OTRS database. With this backend all customer data can be
edited via the web interface of OTRS.
</para>

<example id='configuration-customer-auth-backend-db'>
<title>Customer user authentication against a DB backend</title>

<para>
<programlisting>
    # This is the auth. module againt the otrs db
    $Self->{'Customer::AuthModule'} = 'Kernel::System::CustomerAuth::DB';
    $Self->{'Customer::AuthModule::DB::Table'} = 'customer_user';
    $Self->{'Customer::AuthModule::DB::CustomerKey'} = 'login';
    $Self->{'Customer::AuthModule::DB::CustomerPassword'} = 'pw';
#    $Self->{'Customer::AuthModule::DB::DSN'} = "DBI:mysql:database=customerdb;host=customerdbhost";
#    $Self->{'Customer::AuthModule::DB::User'} = "some_user";
#    $Self->{'Customer::AuthModule::DB::Password'} = "some_password";
</programlisting>
</para>

</example>

</sect3>

<sect3 id='customer-auth-backend-ldap'>
<title>LDAP</title>

<para>
If you have a LDAP directory with all your customer data you can use the
LDAP module to authenticate your customer users to OTRS. Because this
module has only read-access to the LDAP backend, it is not possible to edit
the customer data via the web interface of OTRs.
</para>

<example id='configuration-customer-auth-backend-ldap'>
<title>Customer user authentication against a LDAP backend</title>

<para>
<programlisting>
    # This is an example configuration for an LDAP auth. backend.
    # (take care that Net::LDAP is installed!)
     $Self->{'Customer::AuthModule'} = 'Kernel::System::CustomerAuth::LDAP';
     $Self->{'Customer::AuthModule::LDAP::Host'} = 'ldap.example.com';
     $Self->{'Customer::AuthModule::LDAP::BaseDN'} = 'dc=example,dc=com';
     $Self->{'Customer::AuthModule::LDAP::UID'} = 'uid';

    # Check if the user is allowed to auth in a posixGroup
    # (e. g. user needs to be in a group xyz to use otrs)
    $Self->{'Customer::AuthModule::LDAP::GroupDN'} = 'cn=otrsallow,ou=posixGroups,dc=example,dc=com';
    $Self->{'Customer::AuthModule::LDAP::AccessAttr'} = 'memberUid';
    # for ldap posixGroups objectclass (just uid)
    $Self->{'Customer::AuthModule::LDAP::UserAttr'} = 'UID';
    # for non ldap posixGroups objectclass (full user dn)
#    $Self->{'Customer::AuthModule::LDAP::UserAttr'} = 'DN';

    # The following is valid but would only be necessary if the
    # anonymous user does NOT have permission to read from the LDAP tree
    $Self->{'Customer::AuthModule::LDAP::SearchUserDN'} = '';
    $Self->{'Customer::AuthModule::LDAP::SearchUserPw'} = '';

    # in case you want to add always one filter to each ldap query, use
    # this option. e. g. AlwaysFilter => '(mail=*)' or AlwaysFilter => '(objectclass=user)'
    $Self->{'Customer::AuthModule::LDAP::AlwaysFilter'} = '';

    # in case you want to add a suffix to each customer login name, then
    # you can use this option. e. g. user just want to use user but
    # in your ldap directory exists user@domain.
#    $Self->{'Customer::AuthModule::LDAP::UserSuffix'} = '@domain.com';

    # Net::LDAP new params (if needed - for more info see perldoc Net::LDAP)
    $Self->{'Customer::AuthModule::LDAP::Params'} = {
        port => 389,
        timeout => 120,
        async => 0,
        version => 3,
    };
</programlisting>
</para>

</example>

</sect3>

<sect3 id='customer-auth-backend-httpbasic'>
<title>HTTPBasicAuth for customer users</title>

<para>
If you want to implement a "single sign on" solution  for all your customer
users, you can use HTTPBasic authentication (for all your systems) and
use the HTTPBasicAuth module with OTRS (no login is needed with OTRS any
more).
</para>

<example id='configuration-customer-auth-backend-htbasic'>
<title>Customer user authentication with HTTPBasic</title>

<para>
<programlisting>
    # This is an example configuration for an apache ($ENV{REMOTE_USER})
    # auth. backend. Use it if you want to have a singe login through
    # apache http-basic-auth
    $Self->{'Customer::AuthModule'} = 'Kernel::System::CustomerAuth::HTTPBasicAuth';

    # Note:
    # If you use this module, you should use the following
    # config settings as fallback, if user isn't login through
    # apache ($ENV{REMOTE_USER})
    $Self->{CustomerPanelLoginURL} = 'http://host.example.com/not-authorised-for-otrs.html';
    $Self->{CustomerPanelLogoutURL} = 'http://host.example.com/thanks-for-using-otrs.html';
</programlisting>
</para>

</example>

</sect3>

<sect3 id='customer-auth-backend-radius'>
<title>Radius</title>

<para>
The following settings can be used to authenticate your customer users
against a radius server.
</para>

<example id='configuration-customer-auth-backend-radius'>
<title>Customer user authentication against a radius backend</title>

<para>
<programlisting>
    # This is a example configuration to auth. customer against a radius server
    $Self->{'Customer::AuthModule'} = 'Kernel::System::Auth::Radius';
    $Self->{'Customer::AuthModule::Radius::Host'} = 'radiushost';
    $Self->{'Customer::AuthModule::Radius::Password'} = 'radiussecret';
</programlisting>
</para>

</example>

</sect3>

</sect2>

</sect1>

<sect1 id="customer-self-registration">
<title>Customize the customer self registration</title>

<para>
It is possible to customize the self registration for new customer users
which is reachable via the customer.pl panel. New optional or required fields
like room number, address or state can be added.
</para>

<para>
The following example shows how you can specify a required field in the customer
database, in this case to store the room number of a customer user.
</para>

<sect2 id='customer-self-registration-dtl'>
<title>Customizing the web interface</title>

<para>
To display the new field for the room number in the customer.pl web
interface the .dtl file which is responsible for the layout in this
interface has to be modified. Edit the
<filename>Kernel/Output/HTML/Standard/CustomerLogin.dtl</filename> file and
add the new field around line 128.
</para>

<para>
<programlisting>
    [...]
    &lt;tr&gt;
      &lt;td&gt;$Text{"Room Number"}: &lt;/td&gt;
      &lt;td&gt;&lt;input type="text" name="Room" value="$QData{"UserRoom"}" size="20" maxlength="50"&gt;&lt;/td>
    &lt;/tr&gt;
    [...]
</programlisting>
</para>
</sect2>

<sect2 id="customer-self-registration-mapping">
<title>Customer mapping</title>

<para>
In the next step the customer mapping has to be expanded with the new
entry for the room number. To ensure that the changes are not lost after
an update, put the "CustomerUser" settings from the
<filename>Kernel/Config/Defaults.pm</filename> into the
<filename>Kernel/Config.pm</filename>. Now change the MAP array and add the
new room number field:
</para>

<para>
<programlisting>
    # CustomerUser
    # (customer user database backend and settings)
    $Self->{CustomerUser} = {
        Name => 'Database Backend',
        Module => 'Kernel::System::CustomerUser::DB',
        Params => {
            # if you want to use an external database, add the
            # required settings
#            DSN => 'DBI:odbc:yourdsn',
#            DSN => 'DBI:mysql:database=customerdb;host=customerdbhost',
#            User => '',
#            Password => '',
            Table => 'customer_user',
        },
        # customer uniq id
        CustomerKey => 'login',
        # customer #
        CustomerID => 'customer_id',
        CustomerValid => 'valid_id',
        CustomerUserListFields => ['first_name', 'last_name', 'email'],
#        CustomerUserListFields => ['login', 'first_name', 'last_name', 'customer_id', 'email'],
        CustomerUserSearchFields => ['login', 'last_name', 'customer_id'],
        CustomerUserSearchPrefix => '',
        CustomerUserSearchSuffix => '*',
        CustomerUserSearchListLimit => 250,
        CustomerUserPostMasterSearchFields => ['email'],
        CustomerUserNameFields => ['salutation', 'first_name', 'last_name'],
        CustomerUserEmailUniqCheck => 1,
#        # show not own tickets in customer panel, CompanyTickets
#        CustomerUserExcludePrimaryCustomerID => 0,
#        # generate auto logins
#        AutoLoginCreation => 0,
#        AutoLoginCreationPrefix => 'auto',
#        # admin can change customer preferences
#        AdminSetPreferences => 1,
#        # cache time to life in sec. - cache any database queris
#        CacheTTL => 0,
#        # just a read only source
#        ReadOnly => 1,
        Map => [

            # note: Login, Email and CustomerID needed!
            # var, frontend, storage, shown (1=always,2=lite), required, storage-type, http-link, readonly, http-link-target
            [ 'UserSalutation', 'Salutation', 'salutation',  1, 0, 'var', '', 0 ],
            [ 'UserFirstname',  'Firstname',  'first_name',  1, 1, 'var', '', 0 ],
            [ 'UserLastname',   'Lastname',   'last_name',   1, 1, 'var', '', 0 ],
            [ 'UserLogin',      'Username',   'login',       1, 1, 'var', '', 0 ],
            [ 'UserPassword',   'Password',   'pw',          0, 0, 'var', '', 0 ],
            [ 'UserEmail',      'Email',      'email',       1, 1, 'var', '', 0 ],
            [ 'UserCustomerID', 'CustomerID', 'customer_id', 0, 1, 'var', '', 0 ],
            [ 'UserPhone',      'Phone',      'phone',       1, 0, 'var', '', 0 ],
            [ 'UserFax',        'Fax',        'fax',         1, 0, 'var', '', 0 ],
            [ 'UserMobile',     'Mobile',     'mobile',      1, 0, 'var', '', 0 ],
            [ 'UserRoom',       'Room',       'room',        1, 0, 'var', '', 0 ],
            [ 'UserStreet',     'Street',     'street',      1, 0, 'var', '', 0 ],
            [ 'UserZip',        'Zip',        'zip',         1, 0, 'var', '', 0 ],
            [ 'UserCity',       'City',       'city',        1, 0, 'var', '', 0 ],
            [ 'UserCountry',    'Country',    'country',     1, 0, 'var', '', 0 ],
            [ 'UserComment',    'Comment',    'comments',    1, 0, 'var', '', 0 ],
            [ 'ValidID',        'Valid',      'valid_id',    0, 1, 'int', '', 0 ],
        ],
        # default selections
        Selections => {
            UserSalutation => {
                'Mr.' => 'Mr.',
                'Mrs.' => 'Mrs.',
            },
        },
    };
</programlisting>
</para>
</sect2>

<sect2 id="customer-self-registration-customer-table">
<title>Customize the customer_user table in the OTRS DB</title>

<para>
The last step is to add the new room number column to the customer_user
table in the OTRS database. In this column the entries for the room numbers
will be stored.
</para>

<para>
<screen>
linux:~# mysql -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 6 to server version: 5.0.18-Debian_7-log

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql&gt; use otrs;
Reading table information for completion of table and column names
You can turn off this feature to get a quicker startup with -A

Database changed
mysql&gt; ALTER TABLE customer_user ADD room VARCHAR (200);
Query OK, 3 rows affected (0.01 sec)
Records: 3  Duplicates: 0  Warnings: 0

mysql&gt; quit
Bye
linux:~#
</screen>
</para>

<para>
Now you took all the steps involved, and the new field for the room should be
displayed in the customer.pl panel. New customer users should have to
insert their room number if they register a new account. If you use apache
and use mod_perl for OTRS, you should restart the web server to
activate the changes.
</para>
</sect2>

</sect1>

</chapter>