WORK IN PROGRESS
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 customer interface. This is for people who submit tickets.
- The agent interface. This is for people working on tickets ('admins' if you will)
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 headers to variable to provide a usernamethe 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 for customers in OTRS before they users have logged in. This is because there is no way of knowing a user's details 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.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.
...
And once that is done, you should be able to authenticate by going to https://otrs.example.org/mellon.
Adding the new module to OTRS
Create the file Kernel/System/CustomerAuth/HTTPBasicAuthMellon.pm and copy the code below in it:
Code Block | ||||
---|---|---|---|---|
| ||||
# -- # 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(), 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 name | MELLON_givenName |
Last name | MELLON_sn |
e-mail address | MELLON_mail |
customerID | MELLON_otrs_customer_id |
System/Config.pm
)
Code Block | ||||
---|---|---|---|---|
| ||||
# Customer Auth $Self->{'Customer::AuthModule'} = 'Kernel::System::CustomerAuth::HTTPBasicAuthMellon'; # Uncomment to override the environment vars to be usedBecause auto-provisioned users will all have the same e-mail address $Self->{'Customer::AuthModule::HTTPBasicAuthMellon::UsernameEnvVar'CustomerUser}->{CustomerUserEmailUniqCheck} = 'MELLON_eduPersonPrincipalName'0; $Self->{'Customer::AuthModule::HTTPBasicAuthMellon::MailEnvVarCustomerPanelLoginURL'} = 'MELLON_mailhttps://otrs.example.com/mellon/login?ReturnTo=/customer.pl'; $Self->{'Customer::AuthModule::HTTPBasicAuthMellon::FirstNameEnvVarCustomerPanelLogoutURL'} = 'MELLON_givenName';https://otrs.example.com/mellon/logout?ReturnTo=http://www.terena.org'; $Self# Uncomment to override the environment vars to be used #$Self->{'Customer::AuthModule::HTTPBasicAuthMellon::LastNameEnvVarUsernameEnvVar'} = 'MELLON_sneduPersonPrincipalName'; $Self#$Self->{'Customer::AuthModule::HTTPBasicAuthMellon::CustomerIDEnvVarMailEnvVar'} = 'MELLON_otrs_customer_idmail'; $Self#$Self->{'CustomerPanelLoginURL'} = 'https://otrs.example.com/mellon/login?ReturnTo=/customer.plCustomer::AuthModule::HTTPBasicAuthMellon::FirstNameEnvVar'} = 'MELLON_givenName'; $Self#$Self->{'CustomerPanelLogoutURLCustomer::AuthModule::HTTPBasicAuthMellon::LastNameEnvVar'} = 'https://otrs.example.com/mellon/logout?ReturnTo=http://www.terena.orgMELLON_sn'; # Because auto-provisioned users will all have the same e-mail address $Self->{CustomerUser}->{CustomerUserEmailUniqCheck} = 0;#$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 |
At this point, you should 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
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.