OTRS Help Desk Integration

Date: 09/12/2016 Version: 1.2

Requirements

OTRS Help Desk version 3.1.2 or higher, KeyShield SSO server 5.1 and higher. OTRS offers different authentication providers (backend). This integration works together with the LDAP and/or DB authentication provider. It allows SSO access of so called agents and customers (users).

Planning the integration

KeyShield SSO can work with the same or different LDAP source then your OTRS. You just have to make sure, that an attribute used for the SSO integration contains user names used by OTRS. It’s usually cn in case of eDirectory and sAMAccountName in case of Active Directory. If the KeyShield SSO default user ID attribute is not the one you need for OTRS, then use an optional “UserAttr” directive to get the userID you need. If you are not sure, what is a value of different attributes, you can use the KeyShield’s built-in LDAP viewer to check. The integration is working in few easy steps:
  • KeyShieldAuth module asks KeyShield SSO server who is the user
  • if “UNKNOWN”, the standard LDAP authentication dialog is invoked
  • if correct UserID is returned, then OTRS engine gets is as an user name
Please make sure, that your OTRS is properly configured for LDAP authentication before you start with the KeyShield integration. AuthModule directive has to be set to Kernel::System::Auth::LDAP. If it isn’t, then please follow a commented configuration example /opt/otrs/Kernel/Config/Defaults.pm or the documentation at http://doc.otrs.org/3.1/en/html/auth-backends.html#configuration-agent-auth-backend-ldap Once your LDAP authentication will be functional, you can proceed in accordance with following steps.

Integration installation

1. Unzip the integration package and copy files to /opt/otrs/Custom folder. It’s a repository for custom modules and this operation doesn’t affect OTRS functionality. 2. Now change ownership and access rights to these files. You can od it from the OTRS server console by following commands:
cd /opt/otrs/Custom
chown otrs:www  *.pm
chmod u=rw,g=rw,o=r *.pm
3. Edit the OTRS configuration file /opt/otrs/Kernel/Config.pm and apply following changes: (a) Change the default authentication provider from LDAP or DB to KshieldAuth. I. for Agents: Find the line:
$Self->{'AuthModule'} = 'Kernel::System::Auth::LDAP';
and/or
$Self->{'AuthModule'} = 'Kernel::System::Auth::DB';
and replace it by:
$Self->{'AuthModule'} = 'KShieldAuthLDAP';
and/or
$Self->{'AuthModule'} = 'KShieldAuthDB';
(b) Add new line with the URL and port of your KeyShield SSO server.
$Self->{'AuthModule::KShield::ServerURL'} = 'http://kshield.mydom.com:8485';
(c) If you are using the APIKey protection, you must add new line with the APIKey
$Self->{'AuthModule::KShield::APIKey'} = 'APIKeyValue';
(d) If OTRS user name is not a value of the default UserID, then you must add a new line with name of the right attribute
$Self->{'AuthModule::KShield::UserAttr'} = 'sAMAccountName';
II. for Customers:
$Self->{'Customer::AuthModule'} = 'KShieldAuthLDAP';
and/or
$Self->{'Customer::AuthModule'} = 'KShieldAuthDB';
(b) Add new line with the URL and port of your KeyShield SSO server.
$Self->{'Customer::AuthModule::KShield::ServerURL'} = 'http://kshield.mydom.com:8485';
(c) If you are using the APIKey protection, you must add new line with the APIKey
$Self->{'Customer::AuthModule::KShield::APIKey'} = 'APIKeyValue';
(d) If OTRS user name is not a value of the default UserID, then you must add a new line with name of the right attribute
$Self->{'Customer::AuthModule::KShield::UserAttr'} = 'sAMAccountName';
4. Now the integration is ready to work. Your previously configured LDAP authentication is still fully functional, just KeyShield SSO authentication is the default one.

Function test

Just try to access OTRS from any workstation/device with installed and authenticated KeyShield SSO client (the client icon must be green). If you are an existing OTRS user (not admin!), you will get in without any manual authentication. If this is not working and you get the authentication dialog, check the current log at KeyShield SSO server with log level “API calls”. You should see here the request from the OTRS integration module. Check your IP address, your name, the optional attribute requested and the value returned. In most cases, the attribute used doesn’t contain the value needed. If problem persist, contact your supplier for further support.