ExternalAuth

From Request Tracker Wiki
Jump to navigation Jump to search

External Authentication and Information for Request Tracker

RT::Authen::ExternalAuth

RT::Authen::ExternalAuth is an RTx-style extension for RT that allows the use of multiple external information sources for lookup of authentication and information.

What this means in practice is that you may store your RT users in an external database and RT will validate against that database when logging users in as well as its own. It also means that the users' information can also be looked up against an external database, and it can even be a different one to the one providing authentication.

The currently supported types of external information service are LDAP and DBI.

  • LDAP support means support for OpenLDAP & Active Directory both of which are commonly used for centralising user authentication and information.
  • DBI support means support for any type of database service for which a Perl DBI driver exists and can be installed into your system. Current examples of available drivers include: MySQL, Oracle, PostgreSQL, Flat files and many many others.

RT::Authen::ExternalAuth is designed to allow multiple independent sources to be checked sequentially, and to allow independent sources to be used for each of information lookup and authentication. For example, you could have an LDAP server that stores usernames, passwords and groups for authenticating access to RT, and a separate MySQL server that stores e-mail addresses and other information about those users; or perhaps multiple MySQL servers, each of which will be checked in turn until a user with valid information is found.

As of v0.08 you may also now use browser cookies to implement Single Sign-On (SSO) with other website code so that if you login to another web application and it writes a browser cookie, RT may use that cookie to automatically log you in to RT as the same user you logged in as in the other application.

Installation is simple, and configuration is simple so long as you understand how your information sources work.

ExternalAuthUsers

There is now a new wiki page (ExternalAuthUsers) for discovering just who is using RT::Authen::ExternalAuth to authenticate their users. If you use it and you're not on the list, please feel free to add yourself - I'd personally love to know where my work is being used :)

Versions

For RT versions 3.4.x and 3.6.x it is still recommended that you use RT::Authen::ExternalAuth v0.05. It is perfectly compatible with these versions and works very well. Later versions of ExternalAuth have been developed with RT-3.8.x in mind and, while they /should/ be compatible with earlier versions of RT, there could be some unforeseen difficulties.

The current version of RT::Authen::ExternalAuth is 0.09 which works with any version greater than 3.8.1 including the 4.0 releases. Please review the README of the extension to learn more about running it on older 3.8 and 3.6 releases.

If you are upgrading RT::Authen::ExternalAuth, be sure to review the upgrading instructions in the README

CPAN installation

To install on a system running CPAN: 

cpan -i RT::Authen::ExternalAuth

or, from a CPAN prompt: 

cpan> install RT::Authen::ExternalAuth
  • Rather than using PERL5LIB, setting RTHOME=/opt/rt3 is a generally preferred solution (or wherever RT can find RT.pm). If this does not work, you can try the old suggestions below.
  • remember to add your rt lib path to PERL5LIB before beginning a cpan install. For instance, on CentOS 5.3 do "export PERL5LIB=/usr/lib/rt". failing to do this will lead to the installer complaining that it can't find RT.pm.

Manual installation

Download the extension tarball from: http://search.cpan.org/dist/RT-Authen-ExternalAuth/

Then, unzip and untar the module: 

tar -xvzf RT-Authen-ExternalAuth-0.08.tar.gz

Change into the extension directory: 

cd RT-Authen-ExternalAuth-0.08

Run Makefile.PL and answer the prompt as to your RT base directory: 

perl Makefile.PL

Then run make and make install to complete the installation: 

make
make install

Git Installation

The development releases are available on github, https://github.com/bestpractical/rt-authen-externalauth

Post-install

Once you've installed the extension, you will need to amend your $RTHOME/etc/RT_SiteConfig.pm to add the new configuration options required for your external sources. The installation process should place an example set of configuration options in $RTHOME/local/plugins/RT-Authen-ExternalAuth/etc/RT_SiteConfig.pm (or for RT-3.6.x and ealier $RTHOME/local/etc/RT_SiteConfig.pm). You can choose to either use the examples as a basis for manually adding options to your SiteConfig, or you can include the $RTHOME/local/plugins/RT-Authen-ExternalAuth/etc/RT_SiteConfig.pm file directly from the base of your SiteConfig, and modify the settings accordingly.

  • Remember to add ==> Set( @Plugins, qw(RT::Authen::ExternalAuth) ); <== to your SiteConfig.
  • Remember to READ THE README!

RT::Authen::CookieAuth

  • *No longer supported for RT-3.8.x - Integrated into v0.08 of RT::Authen::ExternalAuth*

This module provides the ability to seamlessly integrate RT-3.6.x with a website that uses browser cookies to keep users authenticated once they have logged in in combination with ExternalAuth v0.05.

Installation is exactly the same as for RT::Authen::ExternalAuth above except that the example configuration file is installed into $RTHOME/local/etc/Authen-CookieAuth/RT_SiteConfig.pm.

Modifications & Bugs

The extensions above are released under the GNU General Public License v2 and you are free to modify the extension however you want, but I ask that you PLEASE document your changes and either add information here or contact me with them directly so they may be considered for future releases and the improvement of ExternalAuth for everybody.

Similarly, if you encounter any bugs, please let me know and I'll update the code accordingly. Hopefully I've tested it thoroughly enough that you shouldn't find any, but I expect that is wishful thinking. You can let me know about bugs however you like, but it'd be worth also entering them into the CPAN copy of RT via this e-mail address:

I have also done my very best to document each and every line worth documenting in the included files so that understanding the code should be easy and modification should be easy too.

Extra Support

I try to make myself available to provide support and should be easily contactable if you want any help with development or to request features or whatever; however the RT-Users mailing list and the #rt IRC channel are the best places to get help because if I'm not around to help, someone else probably will be. I make no guarantee that e-mails direct to me will get a response as I am a very busy man :)

  1. rt on irc.perl.org (Zordrak)
  • zordrak at cpan dot org
  • rt at tpa dot me dot uk

Help, it's not working!!

Make sure you do not have WebExternalAuth or WebExternalAuto set. These are not parts of ExternalAuth and it appears they are conflicting with it.

  • After installing RT::Authen::ExternalAuth successfully via CPAN, Apache won't start. In the error_log, the last entry begins: [Thu Sep 03 00:52:17 2009] error Can't locate Net/LDAP.pm... etc.

ExternalAuth requires Net::LDAP, which can be installed from cpan.

Migrate old usernames


Autocreate via email details

Could someone explain how using this module will work when a new user is autocreated using the email submit process? Would it reach out to your LDAP box based on email address and then auto create the user using his primary username from LDAP rather than the email address?

Retrieved from "https://rt-wiki.bestpractical.com/index.php?title=ExternalAuth&oldid=1176"