Freeside:4:Documentation:Developer:Authentication Plugins

Purpose

Authentication plugins are useful for integration with external authentication (and, optionally, authorization) systems, to integrate backoffice logins with your company-wide directory or single-sign-on.

Creation

To create an authentication plugin, add a module in FS/FS/Auth/ such as FS/FS/Auth/my_external_auth.pm

Inherit from FS::Auth::external. One method needs to be provided, "authenticate". See the template below for an example.

Activation

Set the authentication_module configuration setting to the name of your plugin (for now: either manually in the database, or by adding it to the options for authentication_module in FS/FS/Conf.pm).

Optionally, set the external_auth-access_group-template_user configuration setting to the username of a template user. Access groups will be copied from the template user. (A different template user can also be supplied by your plugin, overriding this default.)

Template

Here is a template for authentication plugins:

package FS::Auth::my_external_auth;                                             
use base qw( FS::Auth::external ); #need to inherit from ::external             
                                                                                
use strict;                                                                     
                                                                                
sub authenticate {                                                              
  my($self, $username, $check_password, $info ) = @_;                           
                                                                                
  #your magic happens here                                                      
                                                                                
  if ( $auth_good ) {                                                           
                                                                                
    #optionally return a real name                                              
    #$info->{'first'} = "Jean";                                                 
    #$info->{'last'}  = "D'eau";                                                
                                                                                
    #optionally return a template username to copy access groups from that user 
    #$info->{'template_user'} = 'username';                                     
                                                                                
    return 1;                                                                   
                                                                                
  } else {                                                                      
    return 0;                                                                   
  }                                                                             
                                                                                
}                                                                               
                                                                                
1;

Example

Here is an example plugin which authenticates anyone with a username starting with "joe":

package FS::Auth::onlyjoe;
use base qw( FS::Auth::external ); #need to inherit from ::external

use strict;

sub authenticate {
  my($self, $username, $check_password, $info ) = @_;

  if ( $username =~ /^joe(.*)$/ ) {
    $info->{'first'} = 'Joe';
    $info->{'last'}  = $1;
    $info->{'template_user'} = 'ivan';
    return 1;
  } else {
    return 0;
  }

}

1;