...

WORK IN PROGRESS

Below is the recipe for getting this OTRS to work with Ubuntu 12with federated authentication.

I used Ubuntu 14.04,  Confluence 5 OTRS 3.1.1, Apache, and 3.8 and mod_auth_mellon.

I choose modmellon because it seemed like a cleaner solution than mod_shib, requiring no additional daemons and much simpler configuration.

The wiki will be open to the public, and logins will only be federated. New users will have their account automatically created, and are put in the confluence-users group.

Prerequisites

Before you start, make sure you have these bits:

• A correctly configured apache web server that is able to serve an HTTPS web site (https://example.com).
• A SAML Identity Provider (IdP).
• An account on that IdP.
• An attribute that can be used as username in Confluence (for example eduPersonPrincipalName). Attributes for full name and e-mail are optional but recommended. In this case we assume 'mail' and 'displayName' can be used.
• The user name of the to-be administrator account. So, if you choose eduPersonPrincipalName as the attribute for username, you need to know your own value (for instance 'dvisser@surfnet.nl').

PostgreSQL

apt-get install postgresql

Create a dedicated database user, and a database:

sudo su - postgres
createuser -S -d -r -P -E confuser
createdb -O confuser confluence

Confluence - part 1

This is a default install of Confluence, which has only local account and no federated logins - that comes later in part 2.

Install OpenJDK:

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

Download the source http://www.atlassian.com/software/confluence/downloads/binary/atlassian-confluence-5.5.3.tar.gz and unpack it to /opt/confluence. All relative paths mentioned below are relative to this directory.

Create a home directory for Confluence (/home/confluence).

Edit confluence/WEB-INF/classes/confluence-init.properties and configure confluence.home=/home/confluence.

Upstart script for Confluence

Ubuntu uses the new upstart init scripts, which we should use.

Create the upstart script /etc/init/confluence:

# Upstart script for confluence
description     "Atlassian Confluence"
start on runlevel [2345]
stop on runlevel [!2345]
kill timeout 30
env RUN_AS_USER=root
env BASEDIR=/opt/confluence
script
    LOGFILE=$BASEDIR/logs/catalina.out
    exec su - $RUN_AS_USER -c "$BASEDIR/bin/catalina.sh run" >> $LOGFILE 2>&1
end script

Once this script is here, issue "start confluence" to get going, and watch the log file /opt/confluence/log/catalina.out. After some time you should see something like this:

INFO: Starting Coyote HTTP/1.1 on http-8090
Apr 09, 2013 5:14:43 PM org.apache.catalina.startup.Catalina start
INFO: Server startup in 65971 ms

By this time you can point your browser to http://example.com:8090, and it should come up with a configuration wizard that will ask for a license key, database credentials, a local admin account, etc. Once that is all done, things should be working, but nothing federated yet, only local accounts.

At this point you need to do some preparation so that stuff will work properly later on through Apache:

1. Create a new admin account with the correct federated username. For instance, if you have decided on using eduPersonPrincipalName as the username, and the value of that attribute for your federated account is 'dvisser@surfnet.nl', create an account with that exactly that username.
2. Make sure this newly created account is a member of "confluence-administrators".
3. Configure the Server Base Url to be the (HTTPS) URL that Apache will listen to. This is done in Confluence Admin -> General Configuration -> Edit.

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 etc already configured):

 0.7.

OTRS has two different web interfaces:

• The customer interface. This is for people who submit tickets
• The agent 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.

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.

Prerequisites

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

• A correctly configured Apache web server that is able to serve an HTTPS web site (https://otrs.example.com).
• A SAML Identity Provider (IdP).
• An account on that IdP.
• An attribute that can be used as username in OTRS (for example eduPersonPrincipalName). Attributes for first name, last name, and e-mail are optional but highly recommended as the service would be pretty useless without these. In this case we assume that 'givenName', 'sn', and 'mail' can be used.
• The user name of the to-be administrator account. So, if you choose eduPersonPrincipalName as the attribute for username, you need to know your own value (for instance 'dvisser@surfnet.nl').

OTRS

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.

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:

# --
# added for OTRS (http://otrs.org/)
# --
ServerName bartali.terena.org
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
        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

ServerName example.com
 
ProxyRequests Off
<Proxy http://ip6-localhost:8090>
        Order deny,allow
   RequestHeader set eduPersonPrincipalName "%{MELLON_eduPersonPrincipalName}e" env=MELLON_eduPersonPrincipalName


    <IfModule mod_version.c>
       Allow from<IfVersion all
</Proxy>


ProxyPass /mellon/ !
ProxyPass / http://ip6-localhost:8090/
ProxyPassReverse / http://ip6-localhost:8090/


# Mobile theme does not honour new seraph values for login URL, so we have to redirect that
RewriteEngine on
RewriteCond     %{QUERY_STRING} ^originalUrl=(.*)$< 2.4>
            Order allow,deny
            Allow from all
        </IfVersion>
        [NC]
Rewriterule  <IfVersion >= 2.4>
   ^/plugins/servlet/mobile/login          /mellon/login?ReturnTo=%1 [R,NE]

# Remove the jsessionid from the URL, to prevent 404 errors when
# unauthenticated visitors try to access a protected resource.
ReWriteRule     ^(.*);jsessionid=[A-Za-z0-9]+(.*)$ $1$2 [R,NE]


<Location />
Require all granted
        </IfVersion>
    </IfModule>
    <IfModule !mod_version.c>
        Order allow,deny
        Allow from MellonEnable "info"all
    </IfModule>
    MellonSecureCookie On<IfModule mod_deflate.c>
        MellonSessionDumpAddOutputFilterByType Off
DEFLATE text/html text/javascript text/css text/xml    MellonSamlResponseDump Offapplication/json text/json
        MellonEndpointPath "/mellon"</IfModule>
</Directory>


<Directory "/opt/otrs/var/httpd/htdocs/">
    AllowOverride None
    MellonSPPrivateKeyFile /etc/apache2/mellon/sp.key
<IfModule mod_version.c>
        <IfVersion MellonSPCertFile /etc/apache2/mellon/sp.crt
< 2.4>
         MellonIdPMetadataFile /etc/apache2/mellon/idp.xml

  Order allow,deny
     # To avoid security holes, first unset anyAllow existingfrom headerall
        RequestHeader</IfVersion>
 unset REMOTE_USER
      <IfVersion  # Then conditionally set it
>= 2.4>
            RequestHeader set REMOTE_USER "%{MELLON_eduPersonPrincipalName}e" env=MELLON_eduPersonPrincipalName
Require all granted
        </IfVersion>
    </IfModule>
    RequestHeader unset CONF_FULL_NAME<IfModule !mod_version.c>
        RequestHeader set CONF_FULL_NAME "%{MELLON_displayName}e" env=MELLON_displayName
Order allow,deny
        Allow from all
    </IfModule>
    RequestHeader<IfModule unset CONF_EMAIL
mod_deflate.c>
        AddOutputFilterByType RequestHeaderDEFLATE set CONF_EMAIL "%{MELLON_mail}e" env=MELLON_mail
</Location>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.

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.And once that is done, you should be able to use federated authentication by going to https://example.com/mellon/login?ReturnTo=%2F

Confluence - part 2

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

...