Versions Compared

Key

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

...

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
themeMidnight
languageperl
# --
# 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 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.