[Bps-public-commit] rt-authen-externalauth branch, master, updated. 0.21-4-g58c4c17

Alex Vandiver alexmv at bestpractical.com
Wed Aug 13 19:47:44 EDT 2014


The branch, master has been updated
       via  58c4c176c5649a94a590d3bf5c94a1f4577b1f43 (commit)
       via  aed731295f794781ec3cb9d3e6801e36634ce8c1 (commit)
       via  ebbea6331ab01a236e8a7219fb72035029c61306 (commit)
       via  8c71de08bdd6cdaf2358f47daa268b4f66ba73a0 (commit)
      from  30681da270f51a2930c01791541b60668367a4b2 (commit)

Summary of changes:
 ChangeLog                          |   6 +
 MANIFEST                           |   1 -
 META.yml                           |   7 +-
 Makefile.PL                        |  11 +-
 README                             | 283 ++++++++++++++++++++++++---------
 etc/RT_SiteConfig.pm               | 243 -----------------------------
 lib/RT/Authen/ExternalAuth.pm      | 310 ++++++++++++++++++++++++++++---------
 lib/RT/Authen/ExternalAuth/LDAP.pm |   3 +-
 xt/ldap.t                          |   1 -
 xt/ldap_escaping.t                 |   1 -
 xt/ldap_group.t                    |   1 -
 xt/ldap_privileged.t               |   1 -
 xt/sessions.t                      |   1 -
 xt/sqlite.t                        |   1 -
 14 files changed, 456 insertions(+), 414 deletions(-)
 delete mode 100644 etc/RT_SiteConfig.pm

- Log -----------------------------------------------------------------
commit 8c71de08bdd6cdaf2358f47daa268b4f66ba73a0
Author: Alex Vandiver <alexmv at bestpractical.com>
Date:   Wed Aug 13 18:52:20 2014 -0400

    Defer loading of Net:SSLeay, to prevent segfaults under mod_perl
    
    Plack::Handler::Apache2 removes $ENV{MOD_PERL}, to prevent some modules
    (like CGI and CGI::Cookie) from looking in the wrong locations for
    input.  Unfortunately, this has catastrophic results for the loading of
    Net::SSLeay, which segfaults Apache if loaded under mod_ssl + mod_perl
    without being able to detect it is running as such.
    
    Remove the early loading of Net::SSLeay, and the entire
    ExternalServiceUsesSSLorTLS argument in general.  There is no need to
    load Net::SSLeay early, and no need for a configuration variable that
    merely repeats what can be inferred from individual service
    configurations.

diff --git a/etc/RT_SiteConfig.pm b/etc/RT_SiteConfig.pm
index d949128..878283c 100644
--- a/etc/RT_SiteConfig.pm
+++ b/etc/RT_SiteConfig.pm
@@ -52,16 +52,6 @@ Set($ExternalInfoPriority,  [ 'My_LDAP',
                             ]
 );
 
-=item C<$ExternalServiceUsesSSLorTLS>
-
-If this is set to true, then the relevant packages will
-be loaded to use SSL/TLS connections. At the moment,
-this just means L<Net::SSLeay>.
-
-=cut
-
-Set($ExternalServiceUsesSSLorTLS,    0);
-
 =item C<$AutoCreateNonExternalUsers>
 
 If this is set to 1, then users should be autocreated by RT
diff --git a/lib/RT/Authen/ExternalAuth/LDAP.pm b/lib/RT/Authen/ExternalAuth/LDAP.pm
index af5bc82..96a63a0 100644
--- a/lib/RT/Authen/ExternalAuth/LDAP.pm
+++ b/lib/RT/Authen/ExternalAuth/LDAP.pm
@@ -6,8 +6,6 @@ use Net::LDAP::Filter;
 
 use strict;
 
-require Net::SSLeay if $RT::ExternalServiceUsesSSLorTLS;
-
 =head1 NAME
 
 RT::Authen::ExternalAuth::LDAP - LDAP source for RT authentication
@@ -606,6 +604,7 @@ sub _GetBoundLdapObj {
     }
 
     if ($ldap_tls) {
+        require Net::SSLeay;
         $Net::SSLeay::ssl_version = $ldap_ssl_ver;
         # Thanks to David Narayan for the fault tolerance bits
         eval { $ldap->start_tls; };
diff --git a/xt/ldap.t b/xt/ldap.t
index 4c11dda..de3b152 100644
--- a/xt/ldap.t
+++ b/xt/ldap.t
@@ -31,7 +31,6 @@ $ldap->add( $dn, attr => [%$entry] );
 
 RT->Config->Set( ExternalAuthPriority        => ['My_LDAP'] );
 RT->Config->Set( ExternalInfoPriority        => ['My_LDAP'] );
-RT->Config->Set( ExternalServiceUsesSSLorTLS => 0 );
 RT->Config->Set( AutoCreateNonExternalUsers  => 0 );
 RT->Config->Set( AutoCreate  => undef );
 RT->Config->Set(
diff --git a/xt/ldap_escaping.t b/xt/ldap_escaping.t
index bfd21e8..047dfda 100644
--- a/xt/ldap_escaping.t
+++ b/xt/ldap_escaping.t
@@ -52,7 +52,6 @@ $ldap->add(
 
 RT->Config->Set( ExternalAuthPriority        => ['My_LDAP'] );
 RT->Config->Set( ExternalInfoPriority        => ['My_LDAP'] );
-RT->Config->Set( ExternalServiceUsesSSLorTLS => 0 );
 RT->Config->Set( AutoCreateNonExternalUsers  => 0 );
 RT->Config->Set( AutoCreate  => undef );
 RT->Config->Set(
diff --git a/xt/ldap_group.t b/xt/ldap_group.t
index a01124b..18121a6 100644
--- a/xt/ldap_group.t
+++ b/xt/ldap_group.t
@@ -60,7 +60,6 @@ $ldap->add(
 #RT->Config->Set( Plugins                     => 'RT::Authen::ExternalAuth' );
 RT->Config->Set( ExternalAuthPriority        => ['My_LDAP'] );
 RT->Config->Set( ExternalInfoPriority        => ['My_LDAP'] );
-RT->Config->Set( ExternalServiceUsesSSLorTLS => 0 );
 RT->Config->Set( AutoCreateNonExternalUsers  => 0 );
 RT->Config->Set( AutoCreate  => undef );
 RT->Config->Set(
diff --git a/xt/ldap_privileged.t b/xt/ldap_privileged.t
index b0e6463..5d7f060 100644
--- a/xt/ldap_privileged.t
+++ b/xt/ldap_privileged.t
@@ -30,7 +30,6 @@ $ldap->add( $dn, attr => [%$entry] );
 
 RT->Config->Set( ExternalAuthPriority        => ['My_LDAP'] );
 RT->Config->Set( ExternalInfoPriority        => ['My_LDAP'] );
-RT->Config->Set( ExternalServiceUsesSSLorTLS => 0 );
 RT->Config->Set( AutoCreateNonExternalUsers  => 0 );
 RT->Config->Set( AutoCreate                  => { Privileged => 1 } );
 RT->Config->Set(
diff --git a/xt/sessions.t b/xt/sessions.t
index 403f258..ceb5bc2 100644
--- a/xt/sessions.t
+++ b/xt/sessions.t
@@ -94,7 +94,6 @@ sub setup_auth_source {
 
     RT->Config->Set( ExternalAuthPriority        => ['My_SQLite'] );
     RT->Config->Set( ExternalInfoPriority        => ['My_SQLite'] );
-    RT->Config->Set( ExternalServiceUsesSSLorTLS => 0 );
     RT->Config->Set( AutoCreateNonExternalUsers  => 0 );
     RT->Config->Set( AutoCreate                  => undef );
     RT->Config->Set(
diff --git a/xt/sqlite.t b/xt/sqlite.t
index 179861f..2989e67 100644
--- a/xt/sqlite.t
+++ b/xt/sqlite.t
@@ -30,7 +30,6 @@ $dbh->do(
 
 RT->Config->Set( ExternalAuthPriority        => ['My_SQLite'] );
 RT->Config->Set( ExternalInfoPriority        => ['My_SQLite'] );
-RT->Config->Set( ExternalServiceUsesSSLorTLS => 0 );
 RT->Config->Set( AutoCreateNonExternalUsers  => 0 );
 RT->Config->Set( AutoCreate                  => undef );
 RT->Config->Set(

commit ebbea6331ab01a236e8a7219fb72035029c61306
Author: Alex Vandiver <alexmv at bestpractical.com>
Date:   Wed Aug 13 19:06:20 2014 -0400

    Standardize and modernize POD
    
    Remove the documentation dealing with the no-longer-supported 3.4, 3.6,
    and 3.8 releases.  Use the standard RT::Extension installation
    instructions, as well as footer.  Condense the "MORE ABOUT THIS MODULE"
    into the "DESCRIPTION" and de-duplicate, removing reference to the
    no-longer-relevant RT::Authen::CookieAuth.

diff --git a/lib/RT/Authen/ExternalAuth.pm b/lib/RT/Authen/ExternalAuth.pm
index 214ee88..c76804d 100644
--- a/lib/RT/Authen/ExternalAuth.pm
+++ b/lib/RT/Authen/ExternalAuth.pm
@@ -8,126 +8,99 @@ RT::Authen::ExternalAuth - RT Authentication using External Sources
 
 =head1 DESCRIPTION
 
-A complete package for adding external authentication mechanisms
-to RT. It currently supports LDAP via Net::LDAP and External Database
-authentication for any database with an installed DBI driver.
+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.
 
-It also allows for authenticating cookie information against an
-external database through the use of the RT-Authen-CookieAuth extension.
+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.
 
-=head1 UPGRADING
+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.
 
-If you are upgrading from an earlier version of this extension, you must
-remove the following files manually:
+=head1 INSTALLATION
 
-    $RTHOME/local/plugins/RT-Authen-ExternalAuth/lib/RT/User_Vendor.pm
-    $RTHOME/local/lib/RT/User_Vendor.pm
-    $RTHOME/local/lib/RT/Authen/External_Auth.pm
+=over
 
-Otherwise you will most likely encounter an error about modifying a read
-only value and be unable to start RT.
+=item C<perl Makefile.PL>
 
-You may not have all of these files.  It depends what versions you are
-upgrading between.
+=item C<make>
 
-If you are using a vendor packaged RT, your local directories are likely
-to be somewhere under /usr/local instead of in $RTHOME so you will need
-to visit Configuration -> Tools -> System Configuration to find your
-plugin root.
+=item C<make install>
 
-=head2 VERSION NOTES
+May need root permissions
 
-If you are using RT 3.6, you want to use the 0.05 version.
+=item Edit your F</opt/rt4/etc/RT_SiteConfig.pm>
 
-If you are using RT 3.8.0 or 3.8.1, you may have trouble using this
-due to RT bugs related to plugins, but you may be able to use 0.08.
+If you are using RT 4.2 or greater, add this line:
 
-0.08_02 or later will not work on 3.8.0 or 3.8.1
+    Plugin('RT::Authen::ExternalAuth');
 
-If you are using RT 4.0.0 or greater, you must use at least 0.09
+For RT 4.0, add this line:
 
-=head1 MORE ABOUT THIS MODULE 
+    Set(@Plugins, qw(RT::Authen::ExternalAuth) );
 
-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.
+or add C<RT::Authen::ExternalAuth> to your existing C<@Plugins> line.
 
-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. 
+Once installed, you should view the file:
 
-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.
+    /opt/rt4/local/plugins/RT-Authen-ExternalAuth/etc/RT_SiteConfig.pm
 
-It was originally designed and tested against: 
+Then use the examples provided to prepare your own custom configuration
+which should be added to your site configuration in
+/opt/rt4/etc/RT_SiteConfig.pm
 
-MySQL v4.1.21-standard
-MySQL v5.0.22
-Windows Active Directory v2003
+=back
 
-But it has been designed so that it should work with ANY
-LDAP service and ANY DBI-drivable database, based upon the
-configuration given in your $RTHOME/etc/RT_SiteConfig.pm
+=head1 UPGRADING
+
+If you are upgrading from an earlier version of this extension, you must
+remove the following files manually:
 
-As of v0.08 ExternalAuth also allows you to pull a browser
-cookie value and test it against a DBI data source allowing
-the use of cookies for Single Sign-On (SSO) authentication
-with another application or website login system. This is
-due to the merging of RT::Authen::ExternalAuth and
-RT::Authen::CookieAuth. 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.
+    /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.
 
-=head1 INSTALLATION
+You may not have all of these files.  It depends what versions you are
+upgrading between.
 
-To install this module, run the following commands:
+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.
 
-    perl Makefile.PL
-    make
-    make install
+=head1 AUTHORS
 
-If you are using RT 3.8.x, you need to enable this
-module by adding RT::Authen::ExternalAuth to your
- at Plugins configuration:
+Best Practical Solutions, LLC E<lt>modules at bestpractical.comE<gt>
 
-    Set( @Plugins, qw(RT::Authen::ExternalAuth) );
+Originally by Mike Peachey (Jennic Ltd.) <zordrak at cpan.org>
 
-If you already have a @Plugins line, add RT::Authen::ExternalAuth to the
-existing list.  Adding a second @Plugins line will cause interesting
-bugs.
+=head1 BUGS
 
-Once installed, you should view the file:
-    
-3.4/3.6    $RTHOME/local/etc/ExternalAuth/RT_SiteConfig.pm
-3.8        $RTHOME/local/plugins/RT-Authen-ExternalAuth/etc/RT_SiteConfig.pm
+All bugs should be reported via email to
 
-Then use the examples provided to prepare your own custom 
-configuration which should be added to your site configuration in
-$RTHOME/etc/RT_SiteConfig.pm
+    L<bug-RT-Authen-ExternalAuth at rt.cpan.org|mailto:bug-RT-Authen-ExternalAuth at rt.cpan.org>
 
-=head1 AUTHORS
+or via the web at
 
-Best Practical Solutions <modules at bestpractical.com>
+    L<rt.cpan.org|http://rt.cpan.org/Public/Dist/Display.html?Name=RT-Authen-ExternalAuth>.
 
-Originally by Mike Peachey (Jennic Ltd.) <zordrak at cpan.org>
+=head1 LICENSE AND COPYRIGHT
 
-=head1 COPYRIGHT AND LICENCE
+Copyright (c) 2008-2014 by Best Practical Solutions, LLC
+Copyright (c) 2008 by Jennic Ltd.
 
-Copyright (C) 2008, Jennic Ltd.
-Copyright 2008-2014 Best Practical Solutions
+This is free software, licensed under:
 
-This software is released under version 2 of the GNU 
-General Public License. The license is distributed with
-this package in the LICENSE file found in the directory 
-root.
+  The GNU General Public License, Version 2, June 1991
 
 =cut
 

commit aed731295f794781ec3cb9d3e6801e36634ce8c1
Author: Alex Vandiver <alexmv at bestpractical.com>
Date:   Wed Aug 13 19:38:08 2014 -0400

    Move configuration documentation into the main file
    
    This condenses and updates the configuration options, as well as
    providing them in one place.

diff --git a/etc/RT_SiteConfig.pm b/etc/RT_SiteConfig.pm
deleted file mode 100644
index 878283c..0000000
--- a/etc/RT_SiteConfig.pm
+++ /dev/null
@@ -1,233 +0,0 @@
-=head1 NAME
-
-External Authentication Configuration - Sample configs for L<RT::Authen::ExternalAuth>
-
-=head1 DESCRIPTION
-
-L<RT::Authen::ExternalAuth> provides a lot of flexibility
-with many configuration options. This file describes these
-configuration options and is itself a sample configuration
-suitable for dropping into your C<etc/RT_SiteConfig.pm>
-file and modifying.
-
-=over 4
-
-=item C<$ExternalAuthPriority>
-
-The order in which the services defined in ExternalSettings
-should be used to authenticate users. User is authenticated
-if successfully confirmed by any service - no more services
-are checked.
-
-You should remove services you don't use. For example,
-if you're only using My_LDAP, remove My_MySQL and My_SSO_Cookie.
-
-=cut
-
-Set($ExternalAuthPriority,  [ 'My_LDAP',
-                              'My_MySQL',
-                              'My_SSO_Cookie'
-                            ]
-);
-
-=item C<$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, Tel 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.
-
-=cut
-
-Set($ExternalInfoPriority,  [ 'My_LDAP',
-                              'My_MySQL',
-                            ]
-);
-
-=item C<$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.
-
-=cut
-
-Set($AutoCreateNonExternalUsers,    0);
-
-=item C<$ExternalSettings>
-
-These are the full settings for each external service as a HashOfHashes.
-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, {
-        MyLDAP => {
-            type => 'ldap',
-            ... other options ...
-        },
-        MyMySQL => {
-            type => 'db',
-            ... other options ...
-        },
-        ... other sources ...
-        } );
-
-As shown above, each description should have 'type' defined.
-The following types are supported:
-
-=over 4
-
-=item ldap
-
-Authenticate against and sync information with LDAP servers.
-See L<RT::Authen::ExternalAuth::LDAP> for details.
-
-=item db
-
-Authenticate against and sync information with external RDBMS,
-supported by Perl's L<DBI> interface. See L<RT::Authen::ExternalAuth::DBI>
-for details.
-
-=item cookie
-
-Authenticate by cookie. See L<RT::Authen::ExternalAuth::DBI::Cookie>
-for details.
-
-=back
-
-See the modules noted above for configuration options specific to each type.
-The following apply to all types.
-
-=over 4
-
-=item 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
-L</"attr_map"> section below. You can remove values you don't
-expect to match, but it's recommended to use 'Name' and 'EmailAddress'
-at 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).
-
-=item attr_map
-
-Mapping of RT attributes on to attributes in the external source.
-Valid keys are attributes of an
-L<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',
-        ...
-    },
-
-=back
-
-=cut
-
-Set($ExternalSettings, {
-    # AN EXAMPLE DB SERVICE
-    'My_MySQL'   =>  {
-        'type'                      =>  'db',
-        'server'                    =>  'server.domain.tld',
-        'database'                  =>  'DB_NAME',
-        'table'                     =>  'USERS_TABLE',
-        'user'                      =>  'DB_USER',
-        'pass'                      =>  'DB_PASS',
-        'port'                      =>  'DB_PORT',
-        'dbi_driver'                =>  'DBI_DRIVER',
-        'u_field'                   =>  'username',
-        'p_field'                   =>  'password',
-        'p_enc_pkg'                 =>  'Crypt::MySQL',
-        'p_enc_sub'                 =>  'password',
-        'd_field'                   =>  'disabled',
-        'd_values'                  =>  ['0'],
-        'attr_match_list' =>  [
-            'Gecos',
-            'Name',
-        ],
-        'attr_map' => {
-            'Name'           => 'username',
-            'EmailAddress'   => 'email',
-            'ExternalAuthId' => 'username',
-            'Gecos'          => 'userID',
-        },
-    },
-    # AN EXAMPLE LDAP SERVICE
-    'My_LDAP'       =>  {
-        'type'                      =>  'ldap',
-        'server'                    =>  'server.domain.tld',
-        'user'                      =>  'rt_ldap_username',
-        'pass'                    =>  'rt_ldap_password',
-        'base'                      =>  'ou=Organisational Unit,dc=domain,dc=TLD',
-        'filter'                    =>  '(FILTER_STRING)',
-        'd_filter'                  =>  '(FILTER_STRING)',
-        'group'                     =>  'GROUP_NAME',
-        'group_attr'                =>  'GROUP_ATTR',
-        'tls'                       =>  0,
-        'ssl_version'               =>  3,
-        'net_ldap_args'             => [    version =>  3   ],
-        'group_scope'               =>  'base',
-        'group_attr_value'          =>  'GROUP_ATTR_VALUE',
-        'attr_match_list' => [
-            'Name',
-            'EmailAddress',
-            'RealName',
-        ],
-        'attr_map' => {
-            'Name' => 'sAMAccountName',
-            'EmailAddress' => 'mail',
-            'Organization' => 'physicalDeliveryOfficeName',
-            'RealName' => 'cn',
-            'ExternalAuthId' => 'sAMAccountName',
-            'Gecos' => 'sAMAccountName',
-            'WorkPhone' => 'telephoneNumber',
-            'Address1' => 'streetAddress',
-            'City' => 'l',
-            'State' => 'st',
-            'Zip' => 'postalCode',
-            'Country' => 'co'
-        },
-    },
-    # An example SSO cookie service
-    'My_SSO_Cookie'  => {
-        'type'                      =>  'cookie',
-        'name'                      =>  'loginCookieValue',
-        'u_table'                   =>  'users',
-        'u_field'                   =>  'username',
-        'u_match_key'               =>  'userID',
-        'c_table'                   =>  'login_cookie',
-        'c_field'                   =>  'loginCookieValue',
-        'c_match_key'               =>  'loginCookieUserID',
-        'db_service_name'           =>  'My_MySQL'
-    },
-} );
-
-1;
diff --git a/lib/RT/Authen/ExternalAuth.pm b/lib/RT/Authen/ExternalAuth.pm
index c76804d..dc3d1a8 100644
--- a/lib/RT/Authen/ExternalAuth.pm
+++ b/lib/RT/Authen/ExternalAuth.pm
@@ -47,13 +47,8 @@ For RT 4.0, add this line:
 
 or add C<RT::Authen::ExternalAuth> to your existing C<@Plugins> line.
 
-Once installed, you should view the file:
-
-    /opt/rt4/local/plugins/RT-Authen-ExternalAuth/etc/RT_SiteConfig.pm
-
-Then use the examples provided to prepare your own custom configuration
-which should be added to your site configuration in
-/opt/rt4/etc/RT_SiteConfig.pm
+See L</CONFIGURATION> for additional configuration to add to your
+F<RT_SiteConfig.pm> file.
 
 =back
 
@@ -77,6 +72,196 @@ 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.
 
+=head1 CONFIGURATION
+
+L<RT::Authen::ExternalAuth> provides a lot of flexibility with many
+configuration options.  The following desc these configuration options,
+and provides a complete example.
+
+=over 4
+
+=item C<$ExternalAuthPriority>
+
+The order in which the services defined in L</$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 C<My_LDAP>, remove C<My_MySQL> and C<My_SSO_Cookie>.
+
+    Set($ExternalAuthPriority,  [ 'My_LDAP',
+                                  'My_MySQL',
+                                  'My_SSO_Cookie'
+                                ]
+    );
+
+=item C<$ExternalInfoPriority>
+
+When multiple auth services are available, this value defines the order
+in which the services defined in L</$ExternalSettings> should be used to
+get information about users. This includes C<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',
+                                ]
+    );
+
+=item C<$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.
+
+=item C<$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>
+and L</$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:
+
+=over 4
+
+=item ldap
+
+Authenticate against and sync information with LDAP servers.  See
+L<RT::Authen::ExternalAuth::LDAP> for details.
+
+=item db
+
+Authenticate against and sync information with external RDBMS, supported
+by Perl's L<DBI> interface. See L<RT::Authen::ExternalAuth::DBI> for
+details.
+
+=item cookie
+
+Authenticate by cookie. See L<RT::Authen::ExternalAuth::DBI::Cookie> for
+details.
+
+=back
+
+See the modules noted above for configuration options specific to each
+type.  The following apply to all types.
+
+=over 4
+
+=item 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
+L</attr_map> section below. You can remove values you don't expect to
+match, but we recommend using C<Name> and C<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
+C<RealName> or building name).
+
+=item attr_map
+
+Mapping of RT attributes on to attributes in the external source.
+Valid keys are attributes of an
+L<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',
+        ...
+    },
+
+=back
+
+=back
+
+=head2 Example
+
+    # Use the below LDAP source for both authentication, as well as user
+    # information
+    Set( $ExternalAuthPriority, ["My_LDAP"] );
+    Set( $ExternalAuthInfo,     ["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',
+            },
+        },
+    } );
+
 =head1 AUTHORS
 
 Best Practical Solutions, LLC E<lt>modules at bestpractical.comE<gt>

commit 58c4c176c5649a94a590d3bf5c94a1f4577b1f43
Author: Alex Vandiver <alexmv at bestpractical.com>
Date:   Wed Aug 13 19:47:08 2014 -0400

    Version 0.22_01 releng

diff --git a/ChangeLog b/ChangeLog
index e52517b..9734940 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+0.22_01 2014-08-13
+ - Move main configuration documentation into RT::Authen::ExternalAuth
+ - Remove unnecessary $ExternalServiceUsesSSLorTLS option
+ - Prevent segfaults during server startup when using a LDAPS connection
+   under mod_perl + mod_ssl
+
 0.21 2014-07-01 Kevin Falcone
  - Fix another bad attr_match_list example
  - Better documentation about anonymous binds
diff --git a/MANIFEST b/MANIFEST
index a5c41dc..88c63bd 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -1,5 +1,4 @@
 ChangeLog
-etc/RT_SiteConfig.pm
 html/Callbacks/ExternalAuth/autohandler/Auth
 html/Callbacks/ExternalAuth/autohandler/Session
 html/Callbacks/ExternalAuth/Elements/Header/Head
diff --git a/META.yml b/META.yml
index 375c706..7f9de33 100644
--- a/META.yml
+++ b/META.yml
@@ -1,7 +1,7 @@
 ---
 abstract: 'RT Authentication using External Sources'
 author:
-  - 'Best Practical Solutions <modules at bestpractical.com>'
+  - 'Best Practical Solutions, LLC <modules at bestpractical.com>'
 build_requires:
   ExtUtils::MakeMaker: 6.59
 configure_requires:
@@ -16,7 +16,6 @@ meta-spec:
 name: RT-Authen-ExternalAuth
 no_index:
   directory:
-    - etc
     - html
     - inc
     - xt
@@ -34,6 +33,6 @@ requires:
 resources:
   license: http://opensource.org/licenses/gpl-license.php
   repository: https://github.com/bestpractical/rt-authen-externalauth
-version: '0.21'
+version: 0.22_01
 x_module_install_rtx_version: 0.34_04
-x_requires_rt: 3.8.2
+x_requires_rt: 4.0.0
diff --git a/Makefile.PL b/Makefile.PL
index 937f5f0..1d172fe 100755
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -2,17 +2,12 @@ use inc::Module::Install;
 
 RTx('RT-Authen-ExternalAuth');
 
-license('GPL version 2');
-
-all_from('lib/RT/Authen/ExternalAuth.pm');
-readme_from;
-
 feature 'SSL LDAP Connections' =>
     -default => 0,
     recommends('Net::SSLeay' => 0),
     ;
 
-feature 'External LDAP Sources' => 
+feature 'External LDAP Sources' =>
     -default => 1,
     recommends('Net::LDAP' => 0),
     ;
@@ -22,15 +17,13 @@ feature 'External DBI Sources' =>
     recommends('DBI' => 0),
     ;
 
-feature 'SSO Cookie Sources' => 
+feature 'SSO Cookie Sources' =>
     -default => 1,
     recommends('CGI::Cookie' => 0),
     ;
 
 author_tests('xt');
 
-requires_rt('3.8.2');
-
 &auto_install();
 
 repository 'https://github.com/bestpractical/rt-authen-externalauth';
diff --git a/README b/README
index a2d39fa..1883dbe 100644
--- a/README
+++ b/README
@@ -2,43 +2,6 @@ NAME
     RT::Authen::ExternalAuth - RT Authentication using External Sources
 
 DESCRIPTION
-    A complete package for adding external authentication mechanisms to RT.
-    It currently supports LDAP via Net::LDAP and External Database
-    authentication for any database with an installed DBI driver.
-
-    It also allows for authenticating cookie information against an external
-    database through the use of the RT-Authen-CookieAuth extension.
-
-UPGRADING
-    If you are upgrading from an earlier version of this extension, you must
-    remove the following files manually:
-
-        $RTHOME/local/plugins/RT-Authen-ExternalAuth/lib/RT/User_Vendor.pm
-        $RTHOME/local/lib/RT/User_Vendor.pm
-        $RTHOME/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 $RTHOME so you will need
-    to visit Configuration -> Tools -> System Configuration to find your
-    plugin root.
-
-  VERSION NOTES
-    If you are using RT 3.6, you want to use the 0.05 version.
-
-    If you are using RT 3.8.0 or 3.8.1, you may have trouble using this due
-    to RT bugs related to plugins, but you may be able to use 0.08.
-
-    0.08_02 or later will not work on 3.8.0 or 3.8.1
-
-    If you are using RT 4.0.0 or greater, you must use at least 0.09
-
-MORE ABOUT THIS MODULE
     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
@@ -54,57 +17,231 @@ MORE ABOUT THIS MODULE
     in to your website, they will be automagically logged in to RT when they
     access it.
 
-    It was originally designed and tested against:
+INSTALLATION
+    perl Makefile.PL
+    make
+    make install
+        May need root permissions
 
-    MySQL v4.1.21-standard MySQL v5.0.22 Windows Active Directory v2003
+    Edit your /opt/rt4/etc/RT_SiteConfig.pm
+        If you are using RT 4.2 or greater, add this line:
 
-    But it has been designed so that it should work with ANY LDAP service
-    and ANY DBI-drivable database, based upon the configuration given in
-    your $RTHOME/etc/RT_SiteConfig.pm
+            Plugin('RT::Authen::ExternalAuth');
 
-    As of v0.08 ExternalAuth also allows you to pull a browser cookie value
-    and test it against a DBI data source allowing the use of cookies for
-    Single Sign-On (SSO) authentication with another application or website
-    login system. This is due to the merging of RT::Authen::ExternalAuth and
-    RT::Authen::CookieAuth. 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.
+        For RT 4.0, add this line:
 
-INSTALLATION
-    To install this module, run the following commands:
+            Set(@Plugins, qw(RT::Authen::ExternalAuth) );
 
-        perl Makefile.PL
-        make
-        make install
+        or add RT::Authen::ExternalAuth to your existing @Plugins line.
 
-    If you are using RT 3.8.x, you need to enable this module by adding
-    RT::Authen::ExternalAuth to your @Plugins configuration:
+        See "CONFIGURATION" for additional configuration to add to your
+        RT_SiteConfig.pm file.
 
-        Set( @Plugins, qw(RT::Authen::ExternalAuth) );
+UPGRADING
+    If you are upgrading from an earlier version of this extension, you must
+    remove the following files manually:
 
-    If you already have a @Plugins line, add RT::Authen::ExternalAuth to the
-    existing list. Adding a second @Plugins line will cause interesting
-    bugs.
+        /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
 
-    Once installed, you should view the file:
+    Otherwise you will most likely encounter an error about modifying a read
+    only value and be unable to start RT.
 
-    3.4/3.6 $RTHOME/local/etc/ExternalAuth/RT_SiteConfig.pm 3.8
-    $RTHOME/local/plugins/RT-Authen-ExternalAuth/etc/RT_SiteConfig.pm
+    You may not have all of these files. It depends what versions you are
+    upgrading between.
 
-    Then use the examples provided to prepare your own custom configuration
-    which should be added to your site configuration in
-    $RTHOME/etc/RT_SiteConfig.pm
+    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( $ExternalAuthInfo,     ["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 <modules at bestpractical.com>
+    Best Practical Solutions, LLC <modules at bestpractical.com>
 
     Originally by Mike Peachey (Jennic Ltd.) <zordrak at cpan.org>
 
-COPYRIGHT AND LICENCE
-    Copyright (C) 2008, Jennic Ltd. Copyright 2008-2014 Best Practical
-    Solutions
+BUGS
+    All bugs should be reported via email to
+
+        L<bug-RT-Authen-ExternalAuth at rt.cpan.org|mailto:bug-RT-Authen-ExternalAuth at 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:
 
-    This software is released under version 2 of the GNU General Public
-    License. The license is distributed with this package in the LICENSE
-    file found in the directory root.
+      The GNU General Public License, Version 2, June 1991
 
diff --git a/lib/RT/Authen/ExternalAuth.pm b/lib/RT/Authen/ExternalAuth.pm
index dc3d1a8..ad0e9ed 100644
--- a/lib/RT/Authen/ExternalAuth.pm
+++ b/lib/RT/Authen/ExternalAuth.pm
@@ -1,6 +1,6 @@
 package RT::Authen::ExternalAuth;
 
-our $VERSION = '0.21';
+our $VERSION = '0.22_01';
 
 =head1 NAME
 

-----------------------------------------------------------------------


More information about the Bps-public-commit mailing list