<?xml version='1.0' encoding='UTF-8'?>
<!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.47 2012/02/23 13:44:35 mg Exp $ -->
<chapter id="external-backends">
<title>Einbinden externer Backends</title>

<section id='customer-data'>
<title>Kundenbenutzerdaten</title>

<para>
OTRS ist in der Lage, mit verschiedenen Kundendaten (insbesondere Login,
E-Mail, Telefon) umzugehen. Diese Informationen können im Agenten-Interface
angezeigt und für das Kunden-Interface verwendet werden. Weiterhin werden
die Daten für die Authentifizierung der Kunden am System benötigt.
</para>

<para>
Die benutzten/angezeigten Kundendaten sind frei konfigurierbar, es gibt
jedoch folgende benötigte Optionen die unbedingt vorhanden sein müssen,
damit OTRS ordnungsgemäß funktioniert:
</para>

<para>
<itemizedlist>
  <listitem>
    <para>
      Benutzer-Login
    </para>
  </listitem>
  <listitem>
    <para>
      E-Mail-Adresse
    </para>
  </listitem>
  <listitem>
    <para>
      Benutzer-Kunden-ID
    </para>
  </listitem>
</itemizedlist>
</para>

<para>
Verwenden Sie die Konfigurationsparameter aus dem Skript in Ihrer Datei
<filename>Kernel/Config.pm</filename>, wenn Sie Kundeninformationen anzeigen
möchten.
</para>

<para>
<programlisting>
    # Ticket::Frontend::CustomerInfo*
    # (show customer 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>

<para>
<emphasis>Skript: Konfigurationsparameter in Kernel/Config.pm.</emphasis>
</para>

</section>

<section id="customer-user-backend">
<title>Kundenbenutzer Backend</title>

<para>
Es existieren zwei Kundenbenutzer Back-ends, DB und LDAP. Falls Sie bereits
ein Kundenverzeichnis (z. B. SAP, ...) haben, ist es natürlich möglich,
dafür ein eigenes Back-end zu schreiben.
</para>

<section id='customer-backend-db'>
<title>Datenbank (Standard)</title>

<para>
Beispiel 11-1 zeigt die Konfiguration eines Kundenbenutzer-Backends, welches
die Kundendaten in der OTRS-Datenbank speichert.
</para>

<example id='db-customer-backend'>
<title>Konfiguration eines Datenbank-Kunden-Backends</title>

<para>
<programlisting>
# CustomerUser (customer database backend and settings)
$Self->{CustomerUser} = {
    Name => 'Database Datasource',
    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',
            # if your frontend is unicode and the charset of your
            # customer database server is iso-8859-1, use these options.
#           SourceCharset => 'iso-8859-1',
#           DestCharset => 'utf-8',

            # CaseSensitive will control if the SQL statements need LOWER()
            #   function calls to work case insensitively. Setting this to
            #   1 will improve performance dramatically on large databases.
            CaseSensitive => 0,
        },
# customer unique 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 => ['title','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 live in sec. - cache any database queries
#    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
        [ 'UserTitle',      'Title',      'title',      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 => {
        UserTitle => {
            'Mr.' => 'Mr.',
            'Mrs.' => 'Mrs.',
        },
    },
};
</programlisting>
</para>

</example>

<para>
Falls Sie die Kundendaten anpassen möchten, ändern Sie in der Datenbank die
Tabellenspalten oder fügen Sie weitere hinzu (im folgenden Beispiel wird ein
Feld für die Raumnummer hinzugefügt).
</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>
<emphasis>Skript: Ein Feld zur Tabelle customer_user hinzufügen.</emphasis>
</para>

<para>
Danach fügen Sie Ihre eigenen Spalten dem MAP Array in der Datei
<filename>Kernel/Config.pm</filename> hinzu:
</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>
<emphasis>Skript: Hinzufügen eines Feldes in Kernel/Config.pm
file.</emphasis>
</para>

<para>
Natürlich können Sie all diese Kundeninformationen dann auch über das
Admin-Interface bzw. die Kundenverwaltung pflegen.
</para>

<section id='multi-customer-ids-db'>
<title>Kunden mit multiplen IDs (Firmen-Tickets)</title>

<para>
Es ist möglich, einem Kunden mehr als nur eine Kundennummer zuzuweisen. Dies
kann z. B. dann sinnvoll sein, wenn ein Kunde auf Tickets anderer Kunden
zugreifen muss, z. B. der Abteilungsleiter auf die Tickets der Mitarbeiter
seiner Abteilung. Hat ein Kunde Zugriff auf Tickets anderer Kunden,
verwendet man in OTRS das sog. Firmen Ticket Feature. Im Kunden-Interface
können diese Tickets über den "Firmen-Ticket" Link eingesehen werden.
</para>

<para>
Um Firmen-Tickets zu verwenden, muss die customer_user Tabelle in der OTRS
Datenbank um eine Spalte erweitert werden, in die später die Kundennummern
eingetragen werden, auf die ein Kunde zusätzlich zu den eigenen Tickets
Zugriff haben soll.
</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>
	<emphasis>Skript: Hinzufügen eines Feldes customer_ids zur Tabelle
customer_user.</emphasis>
</para>

<para>
Danach fügen Sie die neue Spalte dem MAP Array in der Datei
<filename>Kernel/Config.pm</filename> hinzu.
</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>
<emphasis>Skript: Hinzufügen des Feldes UserCustomerIDs zu
Kernel/Config.pm.</emphasis>
</para>

<para>
Die Spalte für die Multi-Kundennummern kann ab nun über das Admin-Interface
bzw. über die Kundenverwaltung gepflegt werden.
</para>

<para>
Um nun den Zugriff für einen Kunden auf die Tickets anderer Kunden zu
ermöglichen, tragen Sie in die neue Spalte die IDs der Kunden ein, auf deren
Tickets der Zugriff ermöglicht werden soll. Die einzelnen IDs trennen Sie
durch ein Semikolon.
</para>

<example id='company-tickets-db'>
<title>Firmen-Tickets mit einem Datenbank-Backend</title>

<para>
Angenommen es sind die Kunden A, B und C im System angelegt. A soll mit
Hilfe von Firmen Tickets über das Kunden-Interface Zugriff auf die Tickets
von B und C haben, B und C sollen jedoch jeweils nur ihre eigenen Tickets
einsehen und bearbeiten können.
</para>

<para>
Um dieses Setup zu realisieren, ändern Sie wie oben beschrieben die
customer_user Tabelle in der OTRS Datenbank und das Mapping
in<filename>Kernel/Config.pm</filename>. Anschließend laden Sie über die
Kundenverwaltung die Einstellungen des Kunden A und tragen bei
"Kundennummern" die Werte "B;C;" ein.
</para>

</example>

</section>

</section>

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

<para>
Falls Sie ein existierendes LDAP Verzeichnis mit Ihren Kundenbenutzern
haben, können Sie dieses auch mit OTRS nutzen.
</para>

<example id='ldap-customer-backend'>
<title>Konfiguration eines LDAP Kunden-Backends</title>

<para>
<programlisting>
# CustomerUser
# (customer ldap backend and settings)
$Self->{CustomerUser} = {
    Name => 'LDAP Data Source',
    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 both your frontend and your LDAP are unicode, use this:
            SourceCharset => 'utf-8',
            DestCharset   => 'utf-8',
            # if your frontend is unicode and the charset of your
            # ldap server is iso-8859-1, use these options.
            # SourceCharset => 'iso-8859-1',
            # DestCharset => 'utf-8',
            # Net::LDAP new params (if needed - for more info see perldoc Net::LDAP)
            Params => {
                port => 389,
                timeout => 120,
                async => 0,
                version => 3,
            },
    },
    # customer unique 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 an ldap filter for valid users (expert setting)
#    CustomerUserValidFilter => '(!(description=locked))',
    # administrator can't change customer preferences
    AdminSetPreferences => 0,
#    # cache time to live in sec. - cache any database queries
#    CacheTTL => 0,
    Map => [
        # note: Login, Email and CustomerID are mandatory!
        # var, frontend, storage, shown (1=always,2=lite), required, storage-type, http-link, readonly
        [ 'UserTitle',      '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>
Falls Sie in Ihrem LDAP Verzeichnis weitere Informationen zu Ihren Kunden
gespeichert haben und mit OTRS darauf zugreifen möchten, erweitern Sie das
MAP Array in <filename>Kernel/Config.pm</filename> bzw. entfernen nicht
gewünschte Einträge.
</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>

<para>
<emphasis>Skript: Hinzufügen neuer Felder zu Kernel/Config.pm.</emphasis>
</para>


<section id='multi-customer-ids-ldap'>
<title>Kunden mit multiplen IDs (Firmen-Tickets)</title>

<para>
Um Firmentickets mit einem LDAP zu nutzen, muss ein Feld zum
LDAP-Verzeichnis hinzugefügt werden, welches die IDs enthält, die für einen
Kunden zugänglich sein sollen.
</para>

<para>
Wenn das neue Feld erstellt wurde, muss es zum MAP Array in
<filename>Kernel/Config.pm</filename> hinzugefügt werden.
</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>
<emphasis>Skript: Hinzufügen eines neuen Feldes in
Kernel/Config.pm.</emphasis>
</para>

<para>
Das Feld muss direkt im LDAP-Verzeichnis bearbeitet werden, weil OTRS von
LDAP nur lesen kann, nicht jedoch darauf schreiben.
</para>

<para>
Um nun den Zugriff für einen Kunden auf die Tickets anderer Kunden zu
ermöglichen, tragen Sie in das neue LDAP-Feld die IDs der Kunden ein, auf
deren Tickets der Zugriff ermöglicht werden soll. Die einzelnen IDs trennen
Sie durch ein Semikolon.
</para>

<example id='company-tickets-ldap'>
<title>Verwendung von Firmentickets mit einem LDAP-Backend</title>

<para>
Angenommen es sind die Kunden A, B und C im System angelegt. A soll mit
Hilfe von Firmen Tickets über das Kunden-Interface Zugriff auf die Tickets
von B und C haben, B und C sollen jedoch jeweils nur ihre eigenen Tickets
einsehen und bearbeiten können.
</para>

<para>
Um dieses Setup zu realisieren, ändern Sie wie oben beschrieben das LDAP
Verzeichnis und das Mapping in
<filename>Kernel/Config.pm</filename>. Anschließend tragen Sie im LDAP
Verzeichnis innerhalb der Einstellungen für den Kunden A für CustomerIDs die
Werte "B;C;" ein.
</para>

</example>

</section>

</section>

<section id='multiple-customer-backends'>
<title>Verwenden mehrerer Kunden Backends</title>

<para>
Soll mehr als nur ein Back-end mit verschiedenen Kundendaten verwendet
werden (z. B. gleichzeitig DB und LDAP), so ist dies ebenfalls mit OTRS
möglich. In einem solchen Fall muss der CustomerUser Parameter für jedes
Back-end um eine Nummer erweitert werden, z. B. "CustomerUser1",
"CustomerUser2", usw.
</para>

<example id='multiple-customer-backend-example'>
<title>Gleichzeitige Einbindung mehrerer verschiedener Kunden Backends</title>

<para>
In der folgenden KOnfiguration verwendet OTRS gleichzeitig ein Datenbank-
und ein LDAP-Kunden-Backend.
</para>

<para>
<programlisting>
# 1. Customer user backend: DB
# (customer database backend and settings)
$Self->{CustomerUser1} = {
    Name => 'Customer Database',
    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 unique 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 => ['title','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 live in sec. - cache any database queries
#    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
        [ 'UserTitle',      'Title',      'title',        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 => {
        UserTitle => {
            'Mr.' => 'Mr.',
            'Mrs.' => 'Mrs.',
        },
    },
};

# 2. Customer user backend: LDAP
# (customer ldap backend and settings)
$Self->{CustomerUser2} = {
    Name => 'LDAP Datasource',
    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 both your frontend and your LDAP are unicode, use this:
#        SourceCharset => 'utf-8',
#        DestCharset   => 'utf-8',
        # if your frontend is e. g. iso-8859-1 and the character set of your
        # ldap server is utf-8, use these options:
#        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 unique 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=locked))',
    # 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
        [ 'UserTitle',      '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>
Es können bis zu 10 Kunden Back-ends gleichzeitig eingebunden werden. Über
die Kundenverwaltung in OTRS ist der Zugriff auf die verschiedenen Back-ends
möglich.
</para>

</section>

</section>

<section id="auth-backends">
<title>Backends für die Authentifizierung von Agenten und Kunden</title>

<para>
OTRS bietet die Möglichkeit Agenten und Kunden über verschiedene Back-ends
zu authentifizieren.
</para>

<section id='agent-auth-backends'>
<title>Authentifizierungs-Backends für Agenten</title>

<section id='agent-auth-backend-db'>
<title>Datenbank (Standard)</title>

<para>
Das Backend für die Authentifizierung von Agenten, welches OTRS
standardmäßig verwendet, ist die OTRS-Datenbank. Die Agenten können
innerhalb des <link linkend="adminarea">Admin-Bereiches</link> in der <link
linkend="adminarea-agents">Benutzerverwaltung</link> angelegt und bearbeitet
werden.
</para>

<example id='configuration-agent-auth-backend-db'>
<title>Agentenauthentifizierung gegen ein Datenbank-Backend</title>

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

</example>

</section>

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

<para>
Falls ein LDAP Verzeichnis mit Ihren Agenten-Benutzerdaten verfügbar ist,
können Sie das LDAP Modul für die Authentifizierung Ihrer Agenten
nutzen. Dieses Modul greift nur lesend auf die Daten im LDAP Verzeichnis zu,
d.h. die Daten können nicht mit OTRS bearbeitet werden, es können also keine
Agenten mit Hilfe der <link
linkend='adminarea-agents'>Benutzerverwaltung</link> von OTRS angelegt oder
bearbeitet werden.
</para>

<example id='configuration-agent-auth-backend-ldap'>
<title>Agentenauthentifizierung gegen ein LDAP Backend</title>

<para>
<programlisting>
# This is an example configuration for an LDAP auth. backend.
# (Make sure 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>
Mit den folgenden Konfigurationsparametern können die Benutzerdaten der
Agenten aus dem LDAP in die lokale OTRS Datenbank synchronisiert
werden. Dies reduziert die Zugriffe auf ihr LDAP Verzeichnis, entlastet den
Server mit den LDAP Daten und beschleunigt die Anmeldung an OTRS. Die
Synchronisierung der Daten findet bei der ersten Anmeldung des Agenten
statt, trotz der synchronisierten Daten bleibt ihr LDAP Verzeichnis die
letzte Instanz bei der Anmeldung. D.h. wird ein User im LDAP Verzeichnis
gelöscht oder deaktiviert, klappt die Anmeldung an OTRS nicht. Ebenfalls
müssen die Daten für einen Agenten weiterhin direkt im LDAP Verzeichnis
gepflegt werden.
</para>

<para>
<programlisting>
# defines AuthSyncBackend (AuthSyncModule) for AuthModule
# if this key exists and is empty, there won't be a sync.
# example values: AuthSyncBackend, AuthSyncBackend2
$Self->{'AuthModule::UseSyncBackend'} = 'AuthSyncBackend';

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

<para>
<emphasis>Skript: Synchronisation der Benutzerdaten aus dem LDAP-Verzeichnis
in die OTRS-Datenbank.</emphasis>
</para>

</section>

<section id='agent-auth-backend-httpbasic'>
<title>HTTPBasicAuth für Agenten</title>

<para>
Falls Sie eine "single sign on"-Lösung für Ihre Agenten implementieren
möchten, benutzen Sie http basic authentication (für alle Ihre Systeme) und
aktivieren Sie das HTTPBasicAuth Modul.
</para>

<example id='configuration-agent-auth-backend-htbasic'>
<title>Agentenauthentifizierung über 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 configuration settings if the user is not authorized
# 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>

</section>

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

<para>
Mit den folgenden Einstellungen kann die Authentifizierung von Agenten gegen
einen Radius-Server realisiert werden.
</para>

<example id='configuration-agent-auth-backend-radius'>
<title>Agentenauthentifizierung gegen ein 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>

</section>

</section>

<section id="customer-auth-backends">
<title>Authentifizierungs-Backends für Kunden</title>

<section id='customer-auth-backend-db'>
<title>Datenbank (Standard)</title>

<para>
Das Backend für die Authentifizierung von Kunden, welches OTRS standardmäßig
verwendet, ist die OTRS-Datenbank. Die Kundendaten können über das Interface
zur Verwaltung von Kunden angelegt und bearbeitet werden.
</para>

<example id='configuration-customer-auth-backend-db'>
<title>Kundenauthentifizierung gegen ein Datenbank-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>

</section>

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

<para>
Falls ein LDAP Verzeichnis mit Ihren Kundenbenutzern verfügbar ist, können
Sie das LDAP Modul für die Authentifizierung Ihrer Kunden nutzen. Dieses
Modul greift nur lesend auf die Daten im LDAP Verzeichnis zu, d.h. die Daten
können nicht mit OTRS bearbeitet werden, es können also keine Kunden mit
Hilfe der Kundenverwaltung von OTRS angelegt oder bearbeitet werden.
</para>

<example id='configuration-customer-auth-backend-ldap'>
<title>Kundenauthentifizierung gegen ein LDAP Backend</title>

<para>
<programlisting>
# This is an example configuration for an LDAP auth. backend.
# (make sure 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>

</section>

<section id='customer-auth-backend-httpbasic'>
<title>HTTPBasicAuth für Kunden</title>

<para>
Falls Sie eine "single sign on"-Lösung für Ihre Kunden implementieren
möchten, benutzen Sie HTTPBasic Authentication (für alle Ihre Systeme) und
aktivieren Sie das HTTPBasicAuth Modul (kein OTRS-Login mehr benötigt).
</para>

<example id='configuration-customer-auth-backend-htbasic'>
<title>Kundenauthentifizierung über 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>

</section>

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

<para>
Mit den folgenden Einstellungen kann die Authentifizierung von Kunden gegen
einen Radius-Server realisiert werden.
</para>

<example id='configuration-customer-auth-backend-radius'>
<title>Kundenauthentifizierung gegen ein 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>

</section>

</section>

</section>

<section id="customer-self-registration">
<title>Kunden-Selbstregistrierung anpassen</title>

<para>
Es ist möglich, die Kunden-Selbstregistrierung für neue Kunden über
"customer.pl" anzupassen. Somit können Sie mehr optionale oder benötigte
Felder (z. B. Adresse, Ort, Telefonnummer) hinzufügen.
</para>

<para>
In folgenden Beispiel wird ein benötigtes Feld für die Raumnummer
hinzugefügt.
</para>

<section id='customer-self-registration-dtl'>
<title>Anpassen der Weboberfläche</title>

<para>
Damit im Webinterface das zusätzliche Feld für die Raumnummer angezeigt
wird, muss die zuständige dtl-Datei angepasst werden. Editieren Sie
<filename>Kernel/Output/HTML/Standard/CustomerLogin.dtl</filename> und fügen
Sie das gewünschte Feld hinzu.
</para>

<para>
<programlisting>
[...]
&lt;div class="NewLine"&gt;
    &lt;label for="Room"&gt;$Text{"Room{CustomerUser}"}&lt;/label&gt;
    &lt;input title="$Text{"Room Number"}" name="Room" type="text" id="UserRoom" maxlength="50" /&gt;
&lt;/div&gt;
[...]
</programlisting>
</para>

<para>
<emphasis>Skript: Anzeigen eines neuen Feldes in der
Weboberfläche.</emphasis>
</para>

</section>

<section id="customer-self-registration-mapping">
<title>Kunden-Mapping</title>

<para>
Zusätzlich muss das Kunden-Mapping um den Eintrag für die Raumnummer
erweitert werden. Dazu werden zuerst die Einstellungen für "CustomerUser"
aus der Datei <filename>Kernel/Config/Defaults.pm</filename> in die Datei
<filename>Kernel/Config.pm</filename> übertragen. Anschließend wird das
Kunden-Mapping um das Raumnummer-Feld erweitert.
</para>

<para>
<programlisting>
# CustomerUser
# (customer 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 unique 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 => ['title', '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 live in sec. - cache database queries
#    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
        [ 'UserTitle',      'Title',      'title',       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 => {
        UserTitle => {
            'Mr.' => 'Mr.',
            'Mrs.' => 'Mrs.',
        },
    },
};
</programlisting>
</para>

<para>
<emphasis>Skript: Anpassung des MAP-Arrays.</emphasis>
</para>

</section>

<section id="customer-self-registration-customer-table">
<title>Anpassen der Kunden-Tabelle in der OTRS-Datenbank</title>

<para>
Abschließend muss eine neue Spalte zur "customer_user" Tabelle in der OTRS
Datenbank hinzugefügt werden, in der die Raumnummer gespeichert werden kann.
</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>
<emphasis>Skript: Hinzufügen einer neuen Spalte zur Tabelle
customer_user.</emphasis>
</para>

<para>
Alle benötigten Anpassungen sind durchgeführt und das Feld für die
Raumnummer sollte nun im Kunden-Interface (customer.pl) angezeigt und
verwendet werden können. Neue Kunden müssen nun ihre Raumnummer angeben,
wenn sie einen neuen Zugang einrichten wollen. Wird mod_perl eingesetzt,
sollte der Webserver neu gestartet werden um die Änderungen zu übernehmen.
</para>
</section>

</section>

</chapter>