Implementing Single Sign On on Windows with Apache

From OtterHub - OTRS Community Wiki
Jump to: navigation, search

This page describes how to implement Single Sign On in a Windows environment with an Apache web server.

This how-to only is valid if you're working with a Windows domain, and if your OTRS also runs on a Windows server, and if you use Apache as a web server.

If you implement Single Sign On (often abbreviated as SSO) your users no longer have to authenticate (log on) when using OTRS. Because they already authenticated against the Windows active directory when logging in to their computer, after installing a small Apache module the web server can pass your authentication data to OTRS. This ensures you are logged in without having to type a user name or password in OTRS.

Grab the apache module mod_auth_sspi from SourceForge. If you're using one of the newer OTRS Windows installers, chances are the module is already in the Apache modules directory, then you can skip this step of course.

Unzip the module, and unzip the two files from the /bin directory to the /modules directory of your Apache installation.

Add the following lines to your Apache configuration file:

LoadModule sspi_auth_module modules/mod_auth_sspi.so

The mod_auth_sspi module should be loaded before all other modules, so please put it to the top of the list of all LoadModule statements.

Add the following statements to the <Directory> block of your cgi-bin directory. Note that the Directory can be different on your system, depending on your installation location.

<Directory "d:/otrs/bin/cgi-bin/">
    SSPIAuth On
    SSPIAuthoritative On
    SSPIDomain pdc.example.com
    SSPIUsernameCase lower
    SSPIOfferBasic On
    Require valid-user
    Options +ExecCGI -Includes
    AllowOverride None
    Order allow,deny
    Allow from all
</Directory>

Now you should make sure OTRS is configured to use HTTPBasicAuth to authenticate the agents. Add the following lines to your Kernel/Config.pm file:

    $Self->{'AuthModule'} = 'Kernel::System::Auth::HTTPBasicAuth';
    $Self->{'AuthModule::HTTPBasicAuth::Replace'} = 'mydomain\\';
    # 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://example.com/Im_sorry_youre_not_authenticated';
# or a youtube vid of Rick Astley?
    $Self->{LogoutURL} = 'http://example.com/portal';


Please note that you might need to strip off some data of the login name, because your users will show up as YOURDOMAIN\username to OTRS. Use the Replace statement to strip the domain part off. You'll see how people are logged in easily by checking the OTRS log file.

Because we do single sign on, there is no login and logout page anymore. Therefore the values of LoginURL and LogoutURL are used. The first is displayed if an agent tries to open OTRS but has no agent account, the second is used when the "Logout" button is clicked. This last URL could point back to a portal or the like.

Now you can re-start the web server, and you should be good to go!

Please note that if you use the customer portal, you should also change some settings in the SysConfig under Frontend::Customer::Auth. They're similar for what you just added for the agents.

Big gotcha: if you're using Single Sign On, at the moment, OTRS does not do Agent Synching from any active directory, if you configured that. So if you want to synchronize user data or user roles and such from AD, you'll have to create a custom script and let that run in a cron job or so. Either that, or manually create your users and roles.

For the customer front end, if you use an LDAP backend you will be good, as there is no customer user data synced to OTRS.

If you're using the SOAP interface, you might want Apache to move that to a separate directory without single sign on, because otherwise any SOAP clients will also need to do SSO plus supplying the SOAP user and password, and that will lead you into trouble.