Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
RT::Authen::ExternalAuUser)Contributed Perl DocumenRT::Authen::ExternalAuth(3)

NAME
       RT::Authen::ExternalAuth	- RT Authentication using External Sources

DESCRIPTION
       This module provides the	ability	to authenticate	RT users against one
       or more external	data sources at	once. It will also allow information
       about that user to be loaded from the same, or any other	available,
       source as well as allowing multple redundant servers for	each method.

       The extension currently supports	authentication and information from
       LDAP via	the Net::LDAP module, and from any data	source that an
       installed DBI driver is available for.

       It is also possible to use cookies set by an alternate application for
       Single Sign-On (SSO) with that application.  For	example, you may
       integrate RT with your own website login	system so that once users log
       in to your website, they	will be	automagically logged in	to RT when
       they access it.

INSTALLATION
       Note that the features provided by this module have been	made into core
       features	in RT 4.4 and greater.

       "perl Makefile.PL"
       "make"
       "make install"
	   May need root permissions

       Edit your /opt/rt4/etc/RT_SiteConfig.pm
	   If you are using the	RT 4.2 series, add this	line:

	       Plugin('RT::Authen::ExternalAuth');

	   For RT 4.0, add this	line:

	       Set(@Plugins, qw(RT::Authen::ExternalAuth) );

	   or add "RT::Authen::ExternalAuth" to	your existing @Plugins line.

	   See "CONFIGURATION" for additional configuration to add to your
	   RT_SiteConfig.pm file.

UPGRADING
       If you are upgrading from an earlier version of this extension, you
       must remove the following files manually:

	   /opt/rt4/local/plugins/RT-Authen-ExternalAuth/lib/RT/User_Vendor.pm
	   /opt/rt4/local/lib/RT/User_Vendor.pm
	   /opt/rt4/local/lib/RT/Authen/External_Auth.pm

       Otherwise you will most likely encounter	an error about modifying a
       read only value and be unable to	start RT.

       You may not have	all of these files.  It	depends	what versions you are
       upgrading between.

       If you are using	a vendor packaged RT, your local directories are
       likely to be somewhere under /usr/local instead of in /opt/rt4 so you
       will need to visit Configuration	-> Tools -> System Configuration to
       find your plugin	root.

CONFIGURATION
       RT::Authen::ExternalAuth	provides a lot of flexibility with many
       configuration options.  The following desc these	configuration options,
       and provides a complete example.

       $ExternalAuthPriority
	   The order in	which the services defined in "$ExternalSettings"
	   should be used to authenticate users.  Once the user	has been
	   authenticated by one	service, the rest are skipped.

	   You should remove services you don't	use. For example, if you're
	   only	using "My_LDAP", remove	"My_MySQL" and "My_SSO_Cookie".

	       Set($ExternalAuthPriority,  [ 'My_LDAP',
					     'My_MySQL',
					     'My_SSO_Cookie'
					   ]
	       );

       $ExternalInfoPriority
	   When	multiple auth services are available, this value defines the
	   order in which the services defined in "$ExternalSettings" should
	   be used to get information about users. This	includes "RealName",
	   telephone numbers etc, but also whether or not the user should be
	   considered disabled.

	   Once	a user record is found,	no more	services are checked.

	   You CANNOT use a SSO	cookie to retrieve information.

	   You should remove services you don't	use, but you must define at
	   least one service.

	       Set($ExternalInfoPriority,  [ 'My_LDAP',
					     'My_MySQL',
					   ]
	       );

       $AutoCreateNonExternalUsers
	   If this is set to 1,	then users should be autocreated by RT as
	   internal users if they fail to authenticate from an external
	   service. This is useful if you have users outside your organization
	   who might interface with RT,	perhaps	by sending email to a support
	   email address.

       $ExternalSettings
	   These are the full settings for each	external service as a hash of
	   hashes.  Note that you may have as many external services as	you
	   wish.  They will be checked in the order specified in
	   "$ExternalAuthPriority" and "$ExternalInfoPriority" directives
	   above.

	   The outer structure is a key	with the authentication	option (name
	   of external source).	The value is a hash reference with
	   configuration keys and values, for example:

	       Set($ExternalSettings, {
		   My_LDAP => {
		       type => 'ldap',
		       ... other options ...
		   },
		   My_MySQL => {
		       type => 'db',
		       ... other options ...
		   },
		   ... other sources ...
	       } );

	   As shown above, each	description should have	'type' defined.	 The
	   following types are supported:

	   ldap
	       Authenticate against and	sync information with LDAP servers.
	       See RT::Authen::ExternalAuth::LDAP for details.

	   db  Authenticate against and	sync information with external RDBMS,
	       supported by Perl's DBI interface. See
	       RT::Authen::ExternalAuth::DBI for details.

	   cookie
	       Authenticate by cookie. See
	       RT::Authen::ExternalAuth::DBI::Cookie for details.

	   See the modules noted above for configuration options specific to
	   each	type.  The following apply to all types.

	   attr_match_list
	       The list	of RT attributes that uniquely identify	a user.	These
	       values are used,	in order, to find users	in the selected
	       authentication source. Each value specified here	must have a
	       mapping in the "attr_map" section below.	You can	remove values
	       you don't expect	to match, but we recommend using "Name"	and
	       "EmailAddress" at a minimum. For	example:

		   'attr_match_list' =>	[
		       'Name',
		       'EmailAddress',
		   ],

	       You should not use items	that can map to	multiple users (such
	       as a "RealName" or building name).

	   attr_map
	       Mapping of RT attributes	on to attributes in the	external
	       source.	Valid keys are attributes of an	RT::User
	       <http://bestpractical.com/rt/docs/latest/RT/User.html>.	The
	       values are attributes from your authentication source.  For
	       example,	an LDAP	mapping	might look like:

		   'attr_map' => {
		       'Name'	      => 'sAMAccountName',
		       'EmailAddress' => 'mail',
		       'Organization' => 'physicalDeliveryOfficeName',
		       'RealName'     => 'cn',
		       ...
		   },

   Example
	   # Use the below LDAP	source for both	authentication,	as well	as user
	   # information
	   Set(	$ExternalAuthPriority, ["My_LDAP"] );
	   Set(	$ExternalInfoPriority, ["My_LDAP"] );

	   # Users created from	LDAP should be Privileged; this	is a core RT
	   # option.  Additionally, this is the	4.2 name for the option; for RT
	   # 4.0, is it	named $AutoCreate   See	the core RT documentation at
	   # http://docs.bestpractical.com/RT_Config#UserAutocreateDefaultsOnLogin
	   # for for further details.
	   Set(	$UserAutocreateDefaultsOnLogin,	{ Privileged =>	1 } );

	   # Users should still	be autocreated by RT as	internal users if they
	   # fail to exist in an external service; this	is so requestors (who
	   # are not in	LDAP) can still	be created when	they email in.
	   Set($AutoCreateNonExternalUsers, 1);

	   # Minimal LDAP configuration; see RT::Authen::ExternalAuth::LDAP for
	   # further details and examples
	   Set($ExternalSettings, {
	       'My_LDAP'       =>  {
		   'type'	      =>  'ldap',
		   'server'	      =>  'ldap.example.com',
		   # By	not passing 'user' and 'pass' we are using an anonymous
		   # bind, which some servers to not allow
		   'base'	      =>  'ou=Staff,dc=example,dc=com',
		   'filter'	      =>  '(objectClass=inetOrgPerson)',
		   # Users are allowed to log in via email address or account
		   # name
		   'attr_match_list'  => [
		       'Name',
		       'EmailAddress',
		   ],
		   # Import the	following properties of	the user from LDAP upon
		   # login
		   'attr_map' => {
		       'Name'	      => 'sAMAccountName',
		       'EmailAddress' => 'mail',
		       'RealName'     => 'cn',
		       'WorkPhone'    => 'telephoneNumber',
		       'Address1'     => 'streetAddress',
		       'City'	      => 'l',
		       'State'	      => 'st',
		       'Zip'	      => 'postalCode',
		       'Country'      => 'co',
		   },
	       },
	   } );

AUTHORS
       Best Practical Solutions, LLC <modules@bestpractical.com>

       Originally by Mike Peachey (Jennic Ltd.)	<zordrak@cpan.org>

BUGS
       All bugs	should be reported via email to

	   L<bug-RT-Authen-ExternalAuth@rt.cpan.org|mailto:bug-RT-Authen-ExternalAuth@rt.cpan.org>

       or via the web at

	   L<rt.cpan.org|http://rt.cpan.org/Public/Dist/Display.html?Name=RT-Authen-ExternalAuth>.

LICENSE	AND COPYRIGHT
       Copyright (c) 2008-2014 by Best Practical Solutions, LLC	Copyright (c)
       2008 by Jennic Ltd.

       This is free software, licensed under:

	 The GNU General Public	License, Version 2, June 1991

   "constant_time_eq($a, $b)"
       Taken verbatim from RT 4.4's RT::Util.

perl v5.24.1			  2017-06-15	   RT::Authen::ExternalAuth(3)

NAME | DESCRIPTION | INSTALLATION | UPGRADING | CONFIGURATION | AUTHORS | BUGS | LICENSE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=RT::Authen::ExternalAuth&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help