Below is the recipe for getting OTRS to work with federated authentication.
I used Ubuntu 14.04, OTRS 3.3.8 and mod_auth_mellon 0.7.
OTRS has two different web interfaces:
The goal is to have both interfaces use federated authentication. This is already possible with the default OTRS.
However, because of the federated authentication, it is not possible to provision accounts for customers in OTRS before they have logged in. This is because there is no way to know a user's details. So we want the accounts to be auto-provisioned. This is not possible with the default OTRS, so I created a patch that adds two custom authentication methods, which are based on the bundled HTTPBasicAuth.pm method.
Before you start, make sure you have these bits in place:
Go to https://www.otrs.com/try/, scroll to Source, and pick the latest version of OTRS Help Desk.
Follow the instructions at http://otrs.github.io/doc/manual/admin/stable/en/html/index.html, do a standard install and make sure everything works.
Pay attention to the phrase "Please install OTRS from source, and do not use the OTRS packages that Debian/Ubuntu provides."
The docs all seem to assume that you'd want to run OTRS inside a subdirectory (https://example.com/otrs), but we want it to be the root of our vhost (https://otrs.example.com), in which case this configuration is a little bit different, see below (you should have the HTTPS stuff already configured, probably in /etc/apache2/mods-enabled/ssl.conf):
ServerName otrs.example.com
Alias /otrs-web/ "/opt/otrs/var/httpd/htdocs/"
Alias / "/opt/otrs/bin/cgi-bin/"
<IfModule mod_perl.c>
# Setup environment and preload modules
Perlrequire /opt/otrs/scripts/apache2-perl-startup.pl
# Reload Perl modules when changed on disk
PerlModule Apache2::Reload
PerlInitHandler Apache2::Reload
# mod_perl2 options for GenericInterface
<Location /nph-genericinterface.pl>
PerlOptions -ParseHeaders
</Location>
</IfModule>
<Directory "/opt/otrs/bin/cgi-bin/">
AllowOverride None
DirectoryIndex customer.pl
AddHandler perl-script .pl .cgi
PerlResponseHandler ModPerl::Registry
Options +ExecCGI
PerlOptions +ParseHeaders
PerlOptions +SetupEnv
# mod_auth_mellon placeholder
<IfModule mod_version.c>
<IfVersion < 2.4>
Order allow,deny
Allow from all
</IfVersion>
<IfVersion >= 2.4>
Require all granted
</IfVersion>
</IfModule>
<IfModule !mod_version.c>
Order allow,deny
Allow from all
</IfModule>
<IfModule mod_deflate.c>
AddOutputFilterByType DEFLATE text/html text/javascript text/css text/xml application/json text/json
</IfModule>
</Directory>
<Directory "/opt/otrs/var/httpd/htdocs/">
AllowOverride None
<IfModule mod_version.c>
<IfVersion < 2.4>
Order allow,deny
Allow from all
</IfVersion>
<IfVersion >= 2.4>
Require all granted
</IfVersion>
</IfModule>
<IfModule !mod_version.c>
Order allow,deny
Allow from all
</IfModule>
<IfModule mod_deflate.c>
AddOutputFilterByType DEFLATE text/html text/javascript text/css text/xml application/json text/json
</IfModule>
# Make sure CSS and JS files are read as UTF8 by the browsers.
AddCharset UTF-8 .css
AddCharset UTF-8 .js
# Set explicit mime type for woff fonts since it is relatively new and apache may not know about it.
AddType application/font-woff .woff
</Directory>
<IfModule mod_headers.c>
# Cache css-cache for 30 days
<Directory "/opt/otrs/var/httpd/htdocs/skins/*/*/css-cache">
<FilesMatch "\.(css|CSS)$">
Header set Cache-Control "max-age=2592000 must-revalidate"
</FilesMatch>
</Directory>
# Cache css thirdparty for 4 hours, including icon fonts
<Directory "/opt/otrs/var/httpd/htdocs/skins/*/*/css/thirdparty">
<FilesMatch "\.(css|CSS|woff|svg)$">
Header set Cache-Control "max-age=14400 must-revalidate"
</FilesMatch>
</Directory>
# Cache js-cache for 30 days
<Directory "/opt/otrs/var/httpd/htdocs/js/js-cache">
<FilesMatch "\.(js|JS)$">
Header set Cache-Control "max-age=2592000 must-revalidate"
</FilesMatch>
</Directory>
# Cache js thirdparty for 4 hours
<Directory "/opt/otrs/var/httpd/htdocs/js/thirdparty/">
<FilesMatch "\.(js|JS)$">
Header set Cache-Control "max-age=14400 must-revalidate"
</FilesMatch>
</Directory>
</IfModule> |
The site is now configured so that the bare URL will go to the customer interface. This makes the most sense because typically customers will have less clue about where to go.
The agent interface is where you should log in to with the default root@localhost account.
Once you're in, you should create a new agent with full permissions, and make sure the username is your eduPersonPrincipalName.
mod_auth_mellon is an Apache module, which is available in Ubuntu 14.04 and later. To get this working with Ubuntu 12.04, I recompiled the Debian source packages from the University of Tilburg and made them available in our own APT repository. Either way, it's easy to install:
apt-get install libapache2-mod-auth-mellon a2enmod auth_mellon |
Create a directory /etc/apache/mellon, and store the Identity Provider metadata in XML format to a file called idp.xml.
Create the cryptographic material for mod_auth_mellon:
openssl req -new -newkey rsa:2048 -days 3650 -nodes -x509 -keyout sp.key -out sp.crt |
Now add this to the configuration of the vhost at the mod_auth_mellon placeholder:
MellonEnable "info"
MellonSecureCookie On
MellonSessionDump Off
MellonSamlResponseDump Off
MellonEndpointPath "/mellon"
MellonSPPrivateKeyFile /etc/apache2/mellon/sp.key
MellonSPCertFile /etc/apache2/mellon/sp.crt
MellonIdPMetadataFile /etc/apache2/mellon/idp.xml
# To avoid security holes, first unset any existing header
RequestHeader unset eduPersonPrincipalName
# Then conditionally set it
RequestHeader set eduPersonPrincipalName "%{MELLON_eduPersonPrincipalName}e" env=MELLON_eduPersonPrincipalName |
As you can see, the attribute eduPersonPrincipalName is being used as the username. This is the attribute that should always be send by the IdP.
By this time, you should be able to download the Service Provider metadata from https://otrs.example.com/mellon/metadata, and use it to add it to your IdP, thereby creating a trust relationship.