Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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 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 method.

 

Prerequisites

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

until 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:

  • 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
  • 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').

...

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." (smile)

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 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):

...

Code Block
themeMidnight
languageerl
        MellonEnable "info"
        MellonSecureCookie On
        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
        # 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 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.

Info

Keep in mind that eduPersonPrincipalName might work well in a controller environment, such a a national identity federation, where the attribute is always present, validated, etc. It might not be so smart if you use a SAML proxy, in which case you could end up with different users with the same 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.

Once

And once that is done, you should be able to authenticate by going to https://otrs.example.org/mellon.

 

Adding the new

methods

module to OTRS

Download the archive and unpack it over your OTRS tree. It contains two files, both called HTTPBasicAuthMellon.pm, which go into System/Kernel/Auth and System/Kernel/CustomerAuth.

Once they're there, change your configuration (System/Config.pm) to include these statements:

 

Create the file Kernel/System/CustomerAuth/HTTPBasicAuthMellon.pm and copy the code below in it: 

Code Block
themeMidnight
languageperl
    # Customer
    $Self->{'Customer::AuthModule'} = 'Kernel::System::CustomerAuth::HTTPBasicAuthMellon';
    # Customer user are automagically created (auto-provisioned) using the environment vars below
    $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->{'CustomerPanelLoginURL'}    = 'https://otrs.example.com/mellon/login?ReturnTo=/customer.pl';
    $Self->{'CustomerPanelLogoutURL'}   = 'https://otrs.example.com/mellon/logout?ReturnTo=http://www.terena.org';
    # Because auto-provisioned users will all have the same e-mail address
    $Self->{CustomerUser}->{CustomerUserEmailUniqCheck} = 0;

    # 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.# --
# 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->{'AuthModule'CustomerUserObject} = 'Kernel::System::Auth::HTTPBasicAuthMellon'CustomerUser->new( %{$Self} );
    # Only this one is neededMellon environment vars
    $Self->{MailEnvVar}
        = $Self->{ConfigObject}->Get( 'Customer::AuthModule::HTTPBasicAuthMellon::UsernameEnvVar'} = 'MELLON_eduPersonPrincipalName';
    $Self->{'LoginURL'} = 'https://otrs.example.com/mellon/login?ReturnTo=/index.pl';
    $Self->{'LogoutURL'}        = 'https://otrs.example.com/mellon/logout?ReturnTo=http://www.terena.org';

 

At this point, you should be able to log in to the site as an admin with your new account.

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(),
            UserEmail      => $Mail,
            ValidID        => 1,
            UserID         => 1,
         );
    }
    # return user
    return $User;
}
1;

 

Configuration

When creating a new customer, we also need data for several other fields: first name, last name, e-mail, and customID. Since mod_auth_mellon copies all the SAML attributes into Apache environment variables anyway, we can use them. The module uses the standard SAML attributes (prefixed with MELLON_ because that's their environment variable name) wherever possible:

 Apache environment variable
First nameMELLON_givenName
Last nameMELLON_sn
e-mail addressMELLON_mail
customerIDMELLON_otrs_customer_id
You can override these values in your configuration (System/Config.pm) , which at the minimum looks like this:

 

Code Block
themeMidnight
languageperl
    # 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';
Warning

I just found out that this set-up won't work unless you put the configuration file ZZZAAuth.pm in Kernel/Config/Files, and give it permissions so that otrs/www-data has write access .There are many statements in there, but I do not yet know which ones are needed... To be continued.

 

At this point, you should be able to log in to the site as an admin with your new account.

If you log in to the customer page, your account will be automatically created.

 

I don't even trust my own Perl skills, so use all of this with care (smile)

 

Known limitations

Customers cannot edit their details

Once customers are auto-provisioned, they cannot edit their name, e-mail, or any other values. This might be an issue in your environment. Only agents can edit this.

 

Unknown agents get stuck in an authentication loop

When agents that don't have an account try to log in, they get stuck in an endless authentication loop. Another agent should first create a new agent account.

If the username isn't know yet, then the new agent could first log in to the customer interface. The existing agent can then see what username was used, and use this to create an agent account.

 

 

 If you log in to the customer page, your account will be automatically created.