.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "RT::Authen::ExternalAuth 3pm" .TH RT::Authen::ExternalAuth 3pm "2016-09-06" "perl v5.22.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" RT::Authen::ExternalAuth \- RT Authentication using External Sources .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides the ability to authenticate \s-1RT\s0 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. .PP The extension currently supports authentication and information from \&\s-1LDAP\s0 via the Net::LDAP module, and from any data source that an installed \s-1DBI\s0 driver is available for. .PP It is also possible to use cookies set by an alternate application for Single Sign-On (\s-1SSO\s0) with that application. For example, you may integrate \s-1RT\s0 with your own website login system so that once users log in to your website, they will be automagically logged in to \s-1RT\s0 when they access it. .SH "INSTALLATION" .IX Header "INSTALLATION" Note that the features provided by this module have been made into core features in \s-1RT 4.4\s0 and greater. .ie n .IP """perl Makefile.PL""" 4 .el .IP "\f(CWperl Makefile.PL\fR" 4 .IX Item "perl Makefile.PL" .PD 0 .ie n .IP """make""" 4 .el .IP "\f(CWmake\fR" 4 .IX Item "make" .ie n .IP """make install""" 4 .el .IP "\f(CWmake install\fR" 4 .IX Item "make install" .PD May need root permissions .IP "Edit your \fI/opt/rt4/etc/RT_SiteConfig.pm\fR" 4 .IX Item "Edit your /opt/rt4/etc/RT_SiteConfig.pm" If you are using the \s-1RT 4.2\s0 series, add this line: .Sp .Vb 1 \& Plugin(\*(AqRT::Authen::ExternalAuth\*(Aq); .Ve .Sp For \s-1RT 4.0,\s0 add this line: .Sp .Vb 1 \& Set(@Plugins, qw(RT::Authen::ExternalAuth) ); .Ve .Sp or add \f(CW\*(C`RT::Authen::ExternalAuth\*(C'\fR to your existing \f(CW@Plugins\fR line. .Sp See \*(L"\s-1CONFIGURATION\*(R"\s0 for additional configuration to add to your \&\fIRT_SiteConfig.pm\fR file. .SH "UPGRADING" .IX Header "UPGRADING" If you are upgrading from an earlier version of this extension, you must remove the following files manually: .PP .Vb 3 \& /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 .Ve .PP Otherwise you will most likely encounter an error about modifying a read only value and be unable to start \s-1RT.\s0 .PP You may not have all of these files. It depends what versions you are upgrading between. .PP If you are using a vendor packaged \s-1RT,\s0 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. .SH "CONFIGURATION" .IX Header "CONFIGURATION" RT::Authen::ExternalAuth provides a lot of flexibility with many configuration options. The following desc these configuration options, and provides a complete example. .ie n .IP "$ExternalAuthPriority" 4 .el .IP "\f(CW$ExternalAuthPriority\fR" 4 .IX Item "$ExternalAuthPriority" The order in which the services defined in \*(L"$ExternalSettings\*(R" should be used to authenticate users. Once the user has been authenticated by one service, the rest are skipped. .Sp You should remove services you don't use. For example, if you're only using \f(CW\*(C`My_LDAP\*(C'\fR, remove \f(CW\*(C`My_MySQL\*(C'\fR and \f(CW\*(C`My_SSO_Cookie\*(C'\fR. .Sp .Vb 5 \& Set($ExternalAuthPriority, [ \*(AqMy_LDAP\*(Aq, \& \*(AqMy_MySQL\*(Aq, \& \*(AqMy_SSO_Cookie\*(Aq \& ] \& ); .Ve .ie n .IP "$ExternalInfoPriority" 4 .el .IP "\f(CW$ExternalInfoPriority\fR" 4 .IX Item "$ExternalInfoPriority" When multiple auth services are available, this value defines the order in which the services defined in \*(L"$ExternalSettings\*(R" should be used to get information about users. This includes \f(CW\*(C`RealName\*(C'\fR, telephone numbers etc, but also whether or not the user should be considered disabled. .Sp Once a user record is found, no more services are checked. .Sp You \s-1CANNOT\s0 use a \s-1SSO\s0 cookie to retrieve information. .Sp You should remove services you don't use, but you must define at least one service. .Sp .Vb 4 \& Set($ExternalInfoPriority, [ \*(AqMy_LDAP\*(Aq, \& \*(AqMy_MySQL\*(Aq, \& ] \& ); .Ve .ie n .IP "$AutoCreateNonExternalUsers" 4 .el .IP "\f(CW$AutoCreateNonExternalUsers\fR" 4 .IX Item "$AutoCreateNonExternalUsers" If this is set to 1, then users should be autocreated by \s-1RT\s0 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 \s-1RT,\s0 perhaps by sending email to a support email address. .ie n .IP "$ExternalSettings" 4 .el .IP "\f(CW$ExternalSettings\fR" 4 .IX Item "$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 \*(L"$ExternalAuthPriority\*(R" and \*(L"$ExternalInfoPriority\*(R" directives above. .Sp 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: .Sp .Vb 11 \& Set($ExternalSettings, { \& My_LDAP => { \& type => \*(Aqldap\*(Aq, \& ... other options ... \& }, \& My_MySQL => { \& type => \*(Aqdb\*(Aq, \& ... other options ... \& }, \& ... other sources ... \& } ); .Ve .Sp As shown above, each description should have 'type' defined. The following types are supported: .RS 4 .IP "ldap" 4 .IX Item "ldap" Authenticate against and sync information with \s-1LDAP\s0 servers. See RT::Authen::ExternalAuth::LDAP for details. .IP "db" 4 .IX Item "db" Authenticate against and sync information with external \s-1RDBMS,\s0 supported by Perl's \s-1DBI\s0 interface. See RT::Authen::ExternalAuth::DBI for details. .IP "cookie" 4 .IX Item "cookie" Authenticate by cookie. See RT::Authen::ExternalAuth::DBI::Cookie for details. .RE .RS 4 .Sp See the modules noted above for configuration options specific to each type. The following apply to all types. .IP "attr_match_list" 4 .IX Item "attr_match_list" The list of \s-1RT\s0 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 \&\*(L"attr_map\*(R" section below. You can remove values you don't expect to match, but we recommend using \f(CW\*(C`Name\*(C'\fR and \f(CW\*(C`EmailAddress\*(C'\fR at a minimum. For example: .Sp .Vb 4 \& \*(Aqattr_match_list\*(Aq => [ \& \*(AqName\*(Aq, \& \*(AqEmailAddress\*(Aq, \& ], .Ve .Sp You should not use items that can map to multiple users (such as a \&\f(CW\*(C`RealName\*(C'\fR or building name). .IP "attr_map" 4 .IX Item "attr_map" Mapping of \s-1RT\s0 attributes on to attributes in the external source. Valid keys are attributes of an RT::User . The values are attributes from your authentication source. For example, an \s-1LDAP\s0 mapping might look like: .Sp .Vb 7 \& \*(Aqattr_map\*(Aq => { \& \*(AqName\*(Aq => \*(AqsAMAccountName\*(Aq, \& \*(AqEmailAddress\*(Aq => \*(Aqmail\*(Aq, \& \*(AqOrganization\*(Aq => \*(AqphysicalDeliveryOfficeName\*(Aq, \& \*(AqRealName\*(Aq => \*(Aqcn\*(Aq, \& ... \& }, .Ve .RE .RS 4 .RE .SS "Example" .IX Subsection "Example" .Vb 4 \& # 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, { \& \*(AqMy_LDAP\*(Aq => { \& \*(Aqtype\*(Aq => \*(Aqldap\*(Aq, \& \*(Aqserver\*(Aq => \*(Aqldap.example.com\*(Aq, \& # By not passing \*(Aquser\*(Aq and \*(Aqpass\*(Aq we are using an anonymous \& # bind, which some servers to not allow \& \*(Aqbase\*(Aq => \*(Aqou=Staff,dc=example,dc=com\*(Aq, \& \*(Aqfilter\*(Aq => \*(Aq(objectClass=inetOrgPerson)\*(Aq, \& # Users are allowed to log in via email address or account \& # name \& \*(Aqattr_match_list\*(Aq => [ \& \*(AqName\*(Aq, \& \*(AqEmailAddress\*(Aq, \& ], \& # Import the following properties of the user from LDAP upon \& # login \& \*(Aqattr_map\*(Aq => { \& \*(AqName\*(Aq => \*(AqsAMAccountName\*(Aq, \& \*(AqEmailAddress\*(Aq => \*(Aqmail\*(Aq, \& \*(AqRealName\*(Aq => \*(Aqcn\*(Aq, \& \*(AqWorkPhone\*(Aq => \*(AqtelephoneNumber\*(Aq, \& \*(AqAddress1\*(Aq => \*(AqstreetAddress\*(Aq, \& \*(AqCity\*(Aq => \*(Aql\*(Aq, \& \*(AqState\*(Aq => \*(Aqst\*(Aq, \& \*(AqZip\*(Aq => \*(AqpostalCode\*(Aq, \& \*(AqCountry\*(Aq => \*(Aqco\*(Aq, \& }, \& }, \& } ); .Ve .SH "AUTHORS" .IX Header "AUTHORS" Best Practical Solutions, \s-1LLC\s0 .PP Originally by Mike Peachey (Jennic Ltd.) .SH "BUGS" .IX Header "BUGS" All bugs should be reported via email to .PP .Vb 1 \& L .Ve .PP or via the web at .PP .Vb 1 \& L. .Ve .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright (c) 2008\-2014 by Best Practical Solutions, \s-1LLC\s0 Copyright (c) 2008 by Jennic Ltd. .PP This is free software, licensed under: .PP .Vb 1 \& The GNU General Public License, Version 2, June 1991 .Ve