WORK IN PROGRESS

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 OTRS is the Open-source Ticket Request System, which is a Perl application that runs on an Apache web server. OTRS has two different web interfaces:

• The The customer interface interface. This is for people who submit tickets.
• The The agent interface interface. This is for people working on tickets ('admins' if you will)

The goal is to have both interfaces use federated authentication. This is already possible with the default OTRS.

Both the interfaces can use various authentication methods, such as a local database, or Active Directory/LDAP. It is also possible to use external authentication (HTTPBasicAuth) in which case OTRS does not take responsibility for authentication any more, but instead relies on an Apache environment variable to provide the username. The is the way forward if you want to use SAML or federated authentication, but there are some issues with.

The biggest issue is that is not possible to provision accounts in OTRS before users have logged in. 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 of knowing 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 methoduntil they have authenticated. To overcome this I wrote a new customer authentication module for OTRS that creates customer accounts on the fly (auto-provisioning).

At the moment we have no use case yet for auto-provisioning agents. This is left as a future exercise, one idea is to auto-provisioning agents based on the value of a specific SAML attribute.

The standard HTTPBasicAuth can be used for the agent interface. 

Below is the recipe for getting OTRS to work with federated authentication using Ubuntu 14.04, OTRS 3.3.8 and mod_auth_mellon 0.7. If you manage to implement it on another combination of software, please let me know.

Prerequisites

Before you start, make sure you have these bits in place:

...

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 special attention to the phrase "Please install OTRS from source, and do not use the OTRS packages that Debian/Ubuntu provides." 

It will require some fiddling to get all the Perl modules sorted, I suggest to use the packages modules as much as possible.

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 bartaliotrs.terenaexample.orgcom
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>
    MellonEnable "info"
   <IfVersion < 2.4>
   MellonSecureCookie On
        MellonSessionDumpOrder Offallow,deny
        MellonSamlResponseDump Off
   Allow from all
   MellonEndpointPath "/mellon"
    </IfVersion>
        <IfVersion MellonSPPrivateKeyFile /etc/apache2/mellon/sp.key>= 2.4>
        MellonSPCertFile /etc/apache2/mellon/sp.crt
   Require all granted
   MellonIdPMetadataFile /etc/apache2/mellon/idp.xml
    </IfVersion>
    #</IfModule>
 To avoid security holes, first unset any existing header<IfModule !mod_version.c>
        RequestHeader unset eduPersonPrincipalNameOrder allow,deny
        #Allow Then conditionally set itfrom all
        RequestHeader set eduPersonPrincipalName "%{MELLON_eduPersonPrincipalName}e" env=MELLON_eduPersonPrincipalName


</IfModule>
    <IfModule mod_versiondeflate.c>
        <IfVersionAddOutputFilterByType < 2.4>
     DEFLATE text/html text/javascript text/css text/xml application/json text/json
    </IfModule>
</Directory>


<Directory "/opt/otrs/var/httpd/htdocs/">
    OrderAllowOverride allow,denyNone
    <IfModule mod_version.c>
       Allow <IfVersion from< all2.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>    # Make sure CSS and JS files are read as UTF8 by the browsers.
    AddCharset UTF-8 .css
    AddCharset UTF-8 .js
    # Set Order allow,deny
            Allow from all
  explicit mime type for woff fonts since it is relatively new and apache may not know about it.
    AddType application/font-woff .woff
</IfVersion>Directory>
<IfModule mod_headers.c>
    # Cache css-cache <IfVersionfor >= 2.4>30 days
    <Directory "/opt/otrs/var/httpd/htdocs/skins/*/*/css-cache">
       Require all granted<FilesMatch "\.(css|CSS)$">
        </IfVersion>
    </IfModule>
Header set Cache-Control  <IfModule !mod_version.c>"max-age=2592000 must-revalidate"
        Order allow,deny</FilesMatch>
    </Directory>
    Allow# fromCache all
css thirdparty for  </IfModule>
    <IfModule mod_deflate.c>4 hours, including icon fonts
        AddOutputFilterByType DEFLATE text/html text/javascript text/css text/xml application/json text/json<Directory "/opt/otrs/var/httpd/htdocs/skins/*/*/css/thirdparty">
    </IfModule>
    # Make sure CSS and JS files are read as UTF8 by the browsers.
    AddCharset UTF-8 .css
    AddCharset UTF-8 .js<FilesMatch "\.(css|CSS|woff|svg)$">
            Header set Cache-Control "max-age=14400 must-revalidate"
    # Set explicit mime type</FilesMatch>
 for woff fonts since</Directory>
 it is relatively new# andCache apachejs-cache mayfor not know about it.30 days
    AddType<Directory application/font-woff .woff
</Directory>
<IfModule mod_headers.c>
    # Cache css-cache for 30 days
    <Directory "/"/opt/otrs/var/httpd/htdocs/skins/*/*/cssjs/js-cache">
        <FilesMatch "\.(cssjs|CSSJS)$">
            Header set Cache-Control "max-age=2592000 must-revalidate"
        </FilesMatch>
    </Directory>
    # Cache cssjs thirdparty for 4 hours, including icon fonts
    <Directory "/opt/otrs/var/httpd/htdocs/skinsjs/*/*/css/thirdparty"thirdparty/">
        <FilesMatch "\.(css|CSS|woff|svgjs|JS)$">
            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</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

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"
        </FilesMatch>
MellonSecureCookie On
        </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.

mod_auth_mellon

mod_auth_mellon is an Apache module. To get this working I recompiled the Debian source packages from the University of Tilburg for Ubuntu 12.04 and made them available in our own APT repository. Ubuntu 14.04 and later have the module available as well.

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 the mellon SP:

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 (note that this is not the entire config - you should have the HTTPS stuff already configured, probably in /etc/apache2/mods-enabled/ssl.conf).

This is a slightly adapted version of the default config so that OTRS runs from the root and not from a subdirectory:

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://example.com/mellon/metadata, and use it to add it to your IdP, thereby creating a trust relationship.

Confluence - part 2

Now everything is in place to federate Confluence. Make sure that Confluence isn't running any more.

...

Edit confluence/WEB-INF/classes/seraph-config.xml and change this section in the beginning: 

...

...

MellonSessionDump Off
        MellonUser eduPersonPrincipalName
        MellonSamlResponseDump Off
        MellonEndpointPath "/mellon"
        MellonSPPrivateKeyFile /etc/apache2/mellon/sp.key
        MellonSPCertFile /etc/apache2/mellon/sp.crt
        MellonIdPMetadataFile /etc/apache2/mellon/idp.xml

As you can see, the attribute eduPersonPrincipalName is being used as the username. This is the attribute that should always be sent by the IdP. In other words, you have to make that authentication doesn't go through when there is an eduPersonPrincipalName. mod_auth_mellon populate the REMOTE_USER environment variable with the value of this SAML attribute.

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.

# --
# Kernel/System/CustomerAuth/HTTPBasicAuthMellon.pm
# Provides HTTPBasic authentication for use with Apache's mod_auth_mellon.
# This module auto-provisions customer users.
# Dick Visser <visser@terena.org> 2014-08-22
# Copyright (C) TERENA, http://www.terena.org
# --
# This software comes with ABSOLUTELY NO WARRANTY. For details, see
# the enclosed file COPYING for license information (AGPL). If you
# did not receive this file, see http://www.gnu.org/licenses/agpl.txt.
# --
package Kernel::System::CustomerAuth::HTTPBasicAuthMellon;
use strict;
use warnings;
sub new {
    my ( $Type, %Param ) = @_;
    # allocate new hash for object
    my $Self = {};
    bless( $Self, $Type );
    # check needed objects
    for (qw(LogObject ConfigObject DBObject MainObject EncodeObject)) {
        $Self->{$_} = $Param{$_} || die "No $_!";
    }
    $Self->{CustomerUserObject} = Kernel::System::CustomerUser->new( %{$Self} );
    # Mellon environment vars
    $Self->{MailEnvVar}
        = $Self->{ConfigObject}->Get( 'Customer::AuthModule::HTTPBasicAuthMellon::MailEnvVar')
	|| 'MELLON_mail';
    $Self->{FirstNameEnvVar}
        = $Self->{ConfigObject}->Get('Customer::AuthModule::HTTPBasicAuthMellon::FirstNameEnvVar')
	|| 'MELLON_givenName';
    $Self->{LastNameEnvVar}
        = $Self->{ConfigObject}->Get( 'Customer::AuthModule::HTTPBasicAuthMellon::LastNameEnvVar')
	|| 'MELLON_sn';
    $Self->{CustomerIDEnvVar}
        = $Self->{ConfigObject}->Get( 'Customer::AuthModule::HTTPBasicAuthMellon::CustomerIDEnvVar')
	|| 'MELLON_customer_id';
    # Debug 0=off 1=on
    $Self->{Debug} = 1;
    $Self->{Count} = $Param{Count} || '';
    return $Self;
}
sub GetOption {
    my ( $Self, %Param ) = @_;
    # check needed stuff
    if ( !$Param{What} ) {
        $Self->{LogObject}->Log( Priority => 'error', Message => "Need What!" );
        return;
    }
    # module options
    my %Option = ( PreAuth => 1, );
    # return option
    return $Option{ $Param{What} };
}
sub Auth {
    my ( $Self, %Param ) = @_;
    # Get attributes values from environment variables
    my $User       = $ENV{REMOTE_USER};
    my $Mail       = $ENV{$Self->{MailEnvVar}} || 'invalid_email@noreply.com';
    my $FirstName  = $ENV{$Self->{FirstNameEnvVar}} || 'first_name';
    my $LastName   = $ENV{$Self->{LastNameEnvVar}} || 'last_name';
    my $CustomerID = $ENV{$Self->{CustomerIDEnvVar}} || 'default_customer';
    my $RemoteAddr = $ENV{REMOTE_ADDR} || 'Got no REMOTE_ADDR env!';
    # return on no user
    if ( !$User ) {
        $Self->{LogObject}->Log(
            Priority => 'notice',
            Message =>
                "No \$ENV{REMOTE_USER}, so not authenticated yet. Redirecting to authenticate (client REMOTE_ADDR: $RemoteAddr).",
        );
        return;
    }
    # replace parts of login
    my $Replace = $Self->{ConfigObject}->Get(
        'Customer::AuthModule::HTTPBasicAuth::Replace' . $Self->{Count},
    );
    if ($Replace) {
        $User =~ s/^\Q$Replace\E//;
    }
    # regexp on login
    my $ReplaceRegExp = $Self->{ConfigObject}->Get(
        'Customer::AuthModule::HTTPBasicAuth::ReplaceRegExp' . $Self->{Count},
    );
    if ($ReplaceRegExp) {
        $User =~ s/$ReplaceRegExp/$1/;
    }
    # Log Apache environment vars in debug mode
    if ( $Self->{Debug} > 0 ) {
        $Self->{LogObject}->Log(
            Priority => 'debug',
            Message => 'Apache environment vars:'
        );
        foreach my $var (sort keys %ENV) {
            $Self->{LogObject}->Log(
                Priority => 'debug',
                Message =>   $var . "=" . $ENV{$var},
            );
        }
    }
    # log
    $Self->{LogObject}->Log(
        Priority => 'notice',
        Message  => "User '$User' Authentication ok (REMOTE_ADDR: $RemoteAddr).",
    );

    # Auto-provisiong.
    # First check if customer exists
    my %UserTest = $Self->{CustomerUserObject}->CustomerUserDataGet( User => $User );
    if (! %UserTest) {
        $Self->{LogObject}->Log(
            Priority => 'notice',
            Message  => "User '$User' doesn't have an account here yet, provisioning it now",
        );
        # Add new customer
        my $newuser = $Self->{CustomerUserObject}->CustomerUserAdd(
            Source         => 'CustomerUser',
            

...

UserFirstname  => $FirstName,
            

...

UserLastname   => $LastName,
        

...

    UserCustomerID => $CustomerID,
        

...

    UserLogin      => $User,
    

...

        UserPassword   => 

...

$Self->{CustomerUserObject}->GenerateRandomPassword(),
        

...

To this: 

...

...

    UserEmail      

...

=> $Mail,
            

...

ValidID        => 1,
   

...

...

 UserID       

...

  => 1,
         

...

);
    }
    # return user
    

...

return $User;
}
1;

    # Customer Auth 
    $Self->{'Customer::AuthModule'} = 'Kernel::System::CustomerAuth::HTTPBasicAuthMellon';
    # Because auto-provisioned users will all have the same e-mail address
    $Self->{CustomerUser}->{CustomerUserEmailUniqCheck} = 0;
    $Self->{'CustomerPanelLoginURL'}    = 'https://otrs.example.com/mellon/login?ReturnTo=/customer.pl';
    $Self->{'CustomerPanelLogoutURL'}   = 'https://otrs.example.com/mellon/logout?ReturnTo=http://www.terena.org';

    # Uncomment to override the environment vars to be used
    #$Self->{'Customer::AuthModule::HTTPBasicAuthMellon::UsernameEnvVar'} = 'MELLON_eduPersonPrincipalName';
    #$Self->{'Customer::AuthModule::HTTPBasicAuthMellon::MailEnvVar'} = 'MELLON_mail';
    #$Self->{'Customer::AuthModule::HTTPBasicAuthMellon::FirstNameEnvVar'} = 'MELLON_givenName';
    #$Self->{'Customer::AuthModule::HTTPBasicAuthMellon::LastNameEnvVar'} = 'MELLON_sn';
    #$Self->{'Customer::AuthModule::HTTPBasicAuthMellon::CustomerIDEnvVar'} = 'MELLON_otrs_customer_id';


    # Agents are NOT auto-provisioned. The will have to be created manually.
    # To find their username, they could first log in as a customer, so that you can see their username
    # in the Customer User Manager overview.
    $Self->{'AuthModule'} = 'Kernel::System::Auth::HTTPBasicAuth';
    $Self->{'LoginURL'} = 'https://otrs.example.com/mellon/login?ReturnTo=/index.pl';
    $Self->{'LogoutURL'}        = 'https://otrs.example.com/mellon/logout?ReturnTo=http://www.terena.org';

You should now be able to use federated logins.

Confluence - mobile theme

The new Confluence feature a dedicated theme for use on mobile devices. This is great, but unfortunately both the login and logout buttons in that theme do not work - they still point to the 'old' static login/logout links.

Login button

I couldn't find any way to do this in Confluence, so I ended up rewriting it in Apache. See the snippet in the Apache config above.

Logout button

 apt-get --no-install-recommends install openjdk-7-jdk

• mkdir /tmp/jar
• cd /tmp/jar
• jar xf /opt/confluence/confluence/WEB-INF/lib/confluence-5.5.3.jar

        <action name="logout" class="com.atlassian.confluence.user.actions.LogoutAction">
            <interceptor-ref name="defaultStack"/>
            <result name="error" type="velocity">/logout.vm</result>
            <result name="success" type="redirect">/login.action?logout=true</result>
        </action>

        <action name="logout" class="com.atlassian.confluence.user.actions.LogoutAction">
            <interceptor-ref name="defaultStack"/>
            <result name="error" type="velocity">/logout.vm</result>
            <result name="success" type="redirect">/mellon/logout?ReturnTo=%2Fdashboard.action</result>
        </action>

cd /tmp/jar
jar cf /opt/confluence/confluence/WEB-INF/lib/confluence-5.5.3.jar .

NOT FOUND
The requested URL /mellon/login;jsessionid=8A736F43779F96249F6C3DC41067BB98 was not found on this server.