Freeside:4:Documentation:Developer:Authentication Plugins

From Freeside
Revision as of 00:04, 10 May 2013 by Ivan (talk | contribs) (Created page with "= Purpose = Authentication plugins are useful for integration with external authentication (and, optionally, authorization) systems. = Creation = To create an authentication p…")

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Purpose

Authentication plugins are useful for integration with external authentication (and, optionally, authorization) systems.

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, "authentication". 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)

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(.*)$/ ) { #verbose for clarity
    $info->{'first'} = 'Joe';
    $info->{'last'}  = $1;
    $info->{'template_user'} = 'ivan';
    return 1;
  } else {
    return 0;
  }

}

1;