OTRS and Active Directory Integration

Introduction

When deploying OTRS in a corporate IT landscape, it is recommended to use MS Active Directory as user authentication source and account repository.

Active Directory could be used for:

  • Agents authentication and account storage
  • Customer authentication and account storage
  • Security groups mapping
OTRS Active Directory
Chart 1 shows the cases for using external client and agent account stores, depending on the directions of IT services.

Chart. 1. Practical cases for account storages
IT Services For: Agent Backend Customer backend
External customers (without CRM or customer database)External (AD)Internal (OTRS database)
External customers (with CRM or external customer database)External (AD)External customer database or CRM
Internal customers (business units)External (AD)External (AD)
  • Detailed information on the customer storage in the external database is well described in the official manual: Using External backends.
  • Required configuration parameters are specified in the Kernel/Config.pm file.
  • For more information on syntax and settings, please pay attention to the configuration file: Kernel/Config/Defaults.pm.
  • Before specifying the settings, you should obtain the required LDAP attributes and objects. Example for Microsoft Windows Server (ldifde):
    ldifde –f ldap.txt
    
    You can also use open source or freeware tools like LDAP Explorer Tool or Apache Directory Studio.
  • Access OTRS to the LDAP tree in read-only mode. That means you can't modify user data with OTRS.

User (agent) authentication

Agent authentication - Kernel::System::Auth::LDAP module.

$Self->{'AuthModule'} = 'Kernel::System::Auth::LDAP';
$Self->{'AuthModule::LDAP::Host'} = 'contoso.com';
$Self->{'AuthModule::LDAP::BaseDN'} = 'dc=contoso,dc=com';
$Self->{'AuthModule::LDAP::UID'} = 'sAMAccountName';
$Self->{'AuthModule::LDAP::GroupDN'} = 'cn=otrs_agents,ou=OTRS,ou=Groups,dc=contoso,dc=com';
$Self->{'AuthModule::LDAP::AccessAttr'} = 'member';
$Self->{'AuthModule::LDAP::UserAttr'} = 'DN';
$Self->{'AuthModule::LDAP::SearchUserDN'} = 'CN=otrs_user,ou=Other,OU=Services,dc=contoso,dc=com';
$Self->{'AuthModule::LDAP::SearchUserPw'} = 'otrs_password';
$Self->{'AuthModule::LDAP::AlwaysFilter'} = '';
$Self->{'AuthModule::LDAP::Params'} = {
    port => 389,
    timeout => 120,
    async => 0,
    version => 3,
};
Agent sync - Kernel::System::Auth::Sync::LDAP module. The use of these settings reduces the number of requests to Active Directory and increases the agent authentication speed. Data synchronization is performed when the agent first logs into OTRS.

$Self->{'AuthSyncModule'} = 'Kernel::System::Auth::Sync::LDAP';
$Self->{'AuthSyncModule::LDAP::Host'} = 'contoso.com';
$Self->{'AuthSyncModule::LDAP::BaseDN'} = 'dc=contoso, dc=com';
$Self->{'AuthSyncModule::LDAP::UID'} = 'sAMAccountName';
$Self->{'AuthSyncModule::LDAP::SearchUserDN'} = 'cn=otrs_user,ou=Other,ou=Services,dc=contoso,dc=com';
$Self->{'AuthSyncModule::LDAP::SearchUserPw'} = 'otrs_password';
$Self->{'AuthSyncModule::LDAP::UserSyncMap'} = {
# DB -> LDAP
UserFirstname => 'givenName',
UserLastname => 'sn',
UserEmail => 'mail',
UserPhone => 'telephoneNumber',
UserTitle => 'title',
};
$Self->{'AuthSyncModule::LDAP::AccessAttr'} = 'member';
$Self->{'AuthSyncModule::LDAP::UserSyncInitialGroups'} = [
'users',
];
  • SearchUserDN - DN (Distinguished Name) of Active Directory browsing account
  • SearchUserPw - password for Active Directory browsing account.
  • AlwaysFilter - filter setting, e.g.: (&(objectclass=user)(mail=*)(!(userAccountControl:1.2.840.113556.1.4.803:=2))).
  • UserSyncInitialGroups - Default OTRS group for agents

User (agent) groups mapping

You can use Active Directory user groups to include agents in the appropriate OTRS groups. AuthSyncModule::LDAP::UserSyncGroupsDefinition module

Example 1. Users (agents) in the 'otrs_agents' Active Directory group are assigned a 'users' group in OTRS.

$Self->{'AuthSyncModule::LDAP::UserSyncGroupsDefinition'} = {
    'cn=otrs_agents,ou=OTRS,ou=Groups,dc=contoso,dc=com' => {
        # otrs group
        'users' => {
        # permission
            rw => 1,
            move_into => 1,
            create => 1,
            note => 1,
            owner => 1,
            priority => 1,
            ro => 1,
        },
    },
};
Example 2. Users in 'otrs_admins' AD group, are assigned two OTRS groups: users и admins (block should be specified inside UserSyncGroupsDefinition block)
       'cn=otrs_admins,ou=OTRS,ou=Groups,dc=contoso,dc=com' => {
        # otrs group
        'admin' => {
        # permission
            rw => 1,
            ro => 1,
        },
        'users' => {
        # permission
            rw => 1,
            move_into => 1,
            create => 1,
            note => 1,
            owner => 1,
            priority => 1,
            ro => 1,
        },
    },
Example 3. Users in 'otrs_ro', are assigned OTRS 'users' group with 'note' and 'read only' privileges (block should be specified inside UserSyncGroupsDefinition block)
    'cn=otrs_ro,ou=OTRS,ou=Groups,dc=contoso,dc=com' => {
        'users' => {
        # permission
            rw => 0,
            move_into => 0,
            create => 0,
            note => 1,
            owner => 0,
            priority => 0,
            ro => 1,
        },
    }

Customers authentication and mapping

$Self->{'Customer::AuthModule'} = 'Kernel::System::CustomerAuth::LDAP';
$Self->{'Customer::AuthModule::LDAP::Host'} = 'contoso.com';
$Self->{'Customer::AuthModule::LDAP::BaseDN'} = 'dc=contoso,dc=com';
$Self->{'Customer::AuthModule::LDAP::UID'} = 'sAMAccountName';
$Self->{'Customer::AuthModule::LDAP::SearchUserDN'} = 'cn=otrs_user,ou=Other,ou=Services,dc=contoso,dc=com';
$Self->{'Customer::AuthModule::LDAP::SearchUserPw'} = 'otrs_password';
$Self->{'CustomerUser'} = {
    Module => 'Kernel::System::CustomerUser::LDAP',
    Params => {
        Host => 'contoso.com',
        BaseDN => 'DC=contoso,DC=com',
        SSCOPE => 'sub',
        UserDN =>'cn=otrs_user,ou=Other,ou=Services,dc=contoso,dc=com',
        UserPw => 'otrs_password',
        AlwaysFilter => '(&(samAccountType=805306368)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))',
        SourceCharset => 'utf-8',
        DestCharset => 'utf-8',
    },
    CustomerKey => 'sAMAccountName',
    CustomerID => 'mail',
    CustomerUserListFields => ['sAMAccountName', 'cn', 'mail'],
    CustomerUserSearchFields => ['sAMAccountName', 'cn', 'mail'],
    CustomerUserSearchPrefix => '',
    CustomerUserSearchSuffix => '*',
    CustomerUserSearchListLimit => 10000,
    CustomerUserPostMasterSearchFields => ['mail'],
    CustomerUserNameFields => ['givenname', 'sn'],
    Map => [
        # note: Login, Email and CustomerID needed!
        [ 'UserFirstname', 'Firstname', 'givenname', 1, 1, 'var' ],
        [ 'UserLastname', 'Lastname', 'sn', 1, 1, 'var' ],
        [ 'UserLogin', 'Login', 'sAMAccountName', 1, 1, 'var' ],
        [ 'UserEmail', 'Email', 'mail', 1, 1, 'var' ],
        [ 'UserCustomerID', 'CustomerID', 'mail', 0, 1, 'var' ],
        [ 'UserPhone', 'Phone', 'telephoneNumber', 1, 0, 'var' ],
    ],
};
 

Common Errors

Incorrect SearchUserDN/SearchUserPw (account for browsing Active Directory tree):

[Error][Kernel::System::Auth::LDAP::Auth][Line:192]:: 
First bind failed! 80090308: LdapErr: DSID-0C09042F, comment: AcceptSecurityContext error, data 52e, v2580