Permalink
Browse files

Unify the README with the partial docs in the .pm file

  • Loading branch information...
1 parent af4a845 commit 7969ffb8af8b1ca4031563585050ac6e9e993e46 @jibsheet jibsheet committed Sep 19, 2011
Showing with 186 additions and 90 deletions.
  1. +1 −0 Makefile.PL
  2. +74 −87 README
  3. +111 −3 lib/RT/Authen/ExternalAuth.pm
View
@@ -6,6 +6,7 @@ license('GPL version 2');
author('Mike Peachey <zordrak@cpan.org>');
all_from('lib/RT/Authen/ExternalAuth.pm');
+readme_from;
feature 'SSL LDAP Connections' =>
-default => 0,
View
161 README
@@ -1,123 +1,110 @@
-RT-Authen-ExternalAuth
+NAME
+ RT::Authen::ExternalAuth - RT Authentication using External Sources
-=========================
-Important Upgrading Notes:
-=========================
+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.
-If you are upgrading from an earlier version of this extension, you must
-remove the following files manually:
+ It also allows for authenticating cookie information against an
+ external database through the use of the RT-Authen-CookieAuth extension.
- $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
+UPGRADING
+ If you are upgrading from an earlier version of this extension, you must
+ remove the following files manually:
-Otherwise you will most likely encounter an error about modifying a read
-only value and be unable to start RT.
+ $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
-You may not have all of these files. It depends what versions you are
-upgrading between.
+ Otherwise you will most likely encounter an error about modifying a read
+ only value and be unable to start RT.
-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.
+ You may not have all of these files. It depends what versions you are
+ upgrading between.
-=========================
-Import Version Notes:
-=========================
+ 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.
-If you are using RT 3.6, you want to use the 0.05 version.
+ 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.
+ 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
+ 0.08_02 or later will not work on 3.8.0 or 3.8.1
-=================
-About This Module
-=================
+ If you are using RT 4.0.0 or greater, you must use at least 0.09
-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.
+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
+ 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.
+ 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.
+ 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.
-It was originally designed and tested against:
+ It was originally designed and tested against:
-MySQL v4.1.21-standard
-MySQL v5.0.22
-Windows Active Directory v2003
+ MySQL v4.1.21-standard MySQL v5.0.22 Windows Active Directory v2003
-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
-
-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.
+ 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
+ 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.
INSTALLATION
+ To install this module, run the following commands:
-To install this module, run the following commands:
-
- perl Makefile.PL
- make
- make install
+ perl Makefile.PL
+ make
+ make install
-I recommend:
-RT::Authen::ExternalAuth v0.05 for RT-3.6.x
-RT::Authen::ExternalAuth v0.08+ for RT-3.8.x
+ If you are using RT 3.8.x, you need to enable this module by adding
+ RT::Authen::ExternalAuth to your @Plugins configuration:
-If you are using RT 3.8.x, you need to enable this
-module by adding RT::Authen::ExternalAuth to your
-@Plugins configuration:
+ Set( @Plugins, qw(RT::Authen::ExternalAuth) );
-Set( @Plugins, qw(RT::Authen::ExternalAuth) );
+ If you already have a @Plugins line, add RT::Authen::ExternalAuth to the
+ existing list. Adding a second @Plugins line will cause interesting
+ bugs.
-If you already have a @Plugins line, add RT::Authen::ExternalAuth to the
-existing list. Adding a second @Plugins line will cause interesting
-bugs.
+ Once installed, you should view the file:
-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
+ 3.4/3.6 $RTHOME/local/etc/ExternalAuth/RT_SiteConfig.pm 3.8
+ $RTHOME/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
-$RTHOME/etc/RT_SiteConfig.pm
+ 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
AUTHOR
Mike Peachey
Jennic Ltd.
zordrak@cpan.org
-
- Various Best Practical Developers
+ Various Best Practical Developers
COPYRIGHT AND LICENCE
+ Copyright (C) 2008, Jennic Ltd.
-Copyright (C) 2008, Jennic Ltd.
+ 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.
-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.
@@ -15,11 +15,119 @@ our $VERSION = '0.09';
It also allows for authenticating cookie information against an
external database through the use of the RT-Authen-CookieAuth extension.
-=begin testing
+=head1 UPGRADING
-ok(require RT::Authen::ExternalAuth);
+If you are upgrading from an earlier version of this extension, you must
+remove the following files manually:
-=end testing
+ $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.
+
+=head2 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
+
+=head1 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 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.
+
+It was originally designed and tested against:
+
+MySQL v4.1.21-standard
+MySQL v5.0.22
+Windows Active Directory v2003
+
+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
+
+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.
+
+
+=head1 INSTALLATION
+
+To install this module, run the following commands:
+
+ perl Makefile.PL
+ make
+ make install
+
+If you are using RT 3.8.x, you need to enable this
+module by adding RT::Authen::ExternalAuth to your
+@Plugins configuration:
+
+Set( @Plugins, qw(RT::Authen::ExternalAuth) );
+
+If you already have a @Plugins line, add RT::Authen::ExternalAuth to the
+existing list. Adding a second @Plugins line will cause interesting
+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
+
+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
+
+=head1 AUTHOR
+ Mike Peachey
+ Jennic Ltd.
+ zordrak@cpan.org
+
+ Various Best Practical Developers
+
+=head1 COPYRIGHT AND LICENCE
+
+Copyright (C) 2008, Jennic Ltd.
+
+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.
=cut

0 comments on commit 7969ffb

Please sign in to comment.