View source for OldLDAP

== Jim Meyer's User_Local.pm overlay ==

=== Overview ===

These pages offers an overlay for the RT::User object which provides integrated, configurable LDAP user authentication and user information services. Both services have been approached previously (See [[LdapOverlay]] for user authentication, [[AutoCreateFromExternalUserInfo]] and [[AutoCreateAndCanonicalizeUserInfo]] for user info). This implementation is heavily derivative of (and owes much to) those previous solutions.

If you haven't already read [[CleanlyCustomizeRT]], now's the time. You'll need it to understand what's going on here.

You might also want to read [[LdapSummary]], a summary of all the available LDAP-for-RT implementations.

Please send any questions to Jim Meyer, [mailto:purp@acm.org purp@acm.org], with the phrase '''RT LDAP''' in the subject.

=== Features ===

* Integration of authentication and information services
* User-configurable map of LDAP attributes to RT attributes
* Uses LDAP info to bootstrap new user accounts
* Update RT account info from LDAP at login
* Multiple servers -- you can choose to use different servers for authentication and information
* Per-server configuration -- each server can have different user/password, base, filter, group, SSL settings, etc.
* Authentication stack -- you can choose the order of authentication methods; this allows you to fall back on RT's internal authentication if LDAP fails, or vice versa. You can also implement other authentication methods and place them into the stack.
* Autocreate RT accounts at login for users who can validly authenticate somewhere within the authentication stack.
* Works with most LDAP and Windows Active Directory configurations

=== News ===

'''2006.08.24''': /Autohandler callback and rt CLI tool bugfix/

Philip Kime noticed a problem where the authohandler callback caused the rt CLI tool to fail. The callback was emitting (an HTML comment to prove it'd been loaded) and it shouldn't, causing an error like "rt: Malformed RT response from [...]". The offending line has been removed from [[LdapAutocreateAuthCallback]]; you should remove it from your installation to avoid related issues.

'''2006.06.20''': /Critical Security Update/

With many thanks to Walter Duncan (walter dot duncan at cox dot net), a critical security problem which would let unauth'd users log in has been patched. If you're using the [[LdapAutocreateAuthCallback]], please update it immediately.

'''2006.06.05''': /v1.1b1 "Punch-Drunk Hamster" release/

Now with /automatic update of RT account info from LDAP;/ that's the big feature add this time around. Also lots of code refactoring, making it a bit more economical and/or efficient. Enough stuff got juggled around that I'd call the code /'''POTENTIALLY VERY UNSTABLE'''/ until I get some news about tests run by folks like you. =]

'''2006.06.02''': /[[AutoCreation]] of Authenticated Accounts Added/

With the most enormous thanks possible to [[RuslanZakirov]] who got me thinking about it the right way, and also to [[DirkPape]] for his notes on Callbacks on the [[CleanlyCustomizeRT]] page, there's now an [[LdapAutocreateAuthCallback]] which will autocreate RT accounts at login if the user provides valid LDAP authentication data. '''This means anyone in LDAP can log into RT with no need to first create their RT account.''' Instructions for upgrading your installation can be found at the top of the [[LdapAutocreateAuthCallback]] page. I know a large number of you asked for this; I'm sorry it took so long to get it right. It's right, now. =]

'''2006.03.29''': /Non-LDAP User Creation Added/

Since I've not had a reply from the rt-devel crowd, I've incorporated the config variable "$RT::[[LdapAutoCreateNonLdapUsers]]" into the overlay. Setting this to a non-null value (e.g. 1) will cause RT to autocreate an account from email or when added to a ticket even if the user is not in LDAP. /*Note that this does not include auto-creation of accounts on failed web login. This is [http://www.gossamer-threads.com/lists/rt/users/54131#54131 discussed being] as a separate overlay as it may be useful in non-LDAP circumstances as well.*/

'''2006.03.21''': /Documentation Reorg, testing looking good/

At this point it seems the code is largely behaving, with one unexpected behavior in that account auto-creation from email fails if the user is not in LDAP. There's a [http://www.gossamer-threads.com/lists/rt/users/54109 fix quick] posted to the rt-users mailing list; as soon as there's a more permanent fix, I'll post news and/or the fix here. Meanwhile, I've had good reports of SSL, drop-in replacement for other implementations, and Windows Active Directory (when you map Name =&gt; 's[[AMAccountName]]', see below).

'''2006.01.06''': /v1.0b1 "Rabid Guinea Pig" release/

Major integration and refactor of previous implementations. All functionality now resides in User_Local.pm, obsoleting previously required CurrentUser_Local.pm. '''SSL connections to LDAP have not been tested. Non-Linux installations have not been tested. Drop-in replacement for previous implementations has only been partially tested.''' If you can test either of these, please let me know where they work well and/or poorly. Thanks!

=== Installation ===

There are two essential pieces to this implementation: the RT::User overlay (User_Local.pm) and the configuration info required to use it. There's a third, optional piece -- the Authentication callback. This last causes RT accounts to be created on the fly for valid LDAP users.

*You must know whether or not you have multiple site customizations in User_Local.pm and how to avoid removing bits you want to keep for other non-LDAP reasons.* If you don't know this, you should spend time understanding exactly what is in your existing User_Local.pm and whether or not it conflicts with the functions in this implementation.

I'll gladly answer some questions when I can, but I've got a new daughter (best fun ever), a new [[MacBook]] Pro (best computer ever), and a new day job (best challenge ever). I also, unfortunately, have no running RT installation nor an LDAP server to play with to set up failure states. You'll understand that responses might take me a while. =\

==== New Installs ====

Installation is very straightforward if you haven't installed any previous LDAP auth/info implementations and don't currently have a User_Local.pm.

1. Copy the code from [[LdapUserLocalOverlay]] into [=${RTHOME}/local/lib/RT/[[User Local|User_Local]].pm] (if it doesn't exist, create it)

2. Copy the config settings from [[LdapSiteConfigSettings]] into [=${RTHOME}/etc/[[RT SiteConfig|RT_SiteConfig]].pm] (I'd put it at the end, but it shouldn't matter)

'''Note''' Active Directory users should use [[LdapSiteConfigSettingsForActiveDirectory]] as a template.

3. Customize the configuration settings; pay careful attention to [[LdapAttrMap]], which is a hash reference to map RT's attributes to the appropriate fields of your LDAP schema. *It's very unlikely that the [[LdapAttrMap]] shown in [[LdapSiteConfigSettings]] will work for you without customization! In particular, [[ActiveDirectory]] users should map:*

 Name =&gt; 'sAMAccountName'
 

If your LDAP server does not allow anonymous binding, $[[LdapUser]] and $[[LdapPass]] should be set to the appropriate DN and password for intial connection.

4. Optionally, copy the code from [[LdapAutocreateAuthCallback]] into <code>${RTHOME}/local/html/Callbacks/LDAP/autohandler/Auth</code> (most likely this doesn't exist, so create it)

'''Note''' Users /must/ have the [[ModifySelf]] right in order for the information to self-update from LDAP

5. If you haven't already done so, you will need to install the Perl Net::LDAP module from CPAN. ( perl -MCPAN -eshell ; install Net::LDAP ).

5a. You will also need (debian package names in this case:) libio-socket-ssl-perl and libnet-ssleay-perl for SSL to work.

6. Stop your RT instance (e.g., /sbin/service httpd stop ) and [[CleanMasonCache]] then start the web server back up.

==== Upgrading From Older Implementations ====

# Back up your existing User_Local.pm and CurrentUser_Local.pm (found in <code>${RTHOME}/local/lib/RT</code>)
# Comment out or remove any LDAP-related functions in these files which are from previous implementations. If you're sure that either of these files contains only such functions, remove the file. For example, the [[AutoCreateAndCanonicalizeUserInfo]] implementation added [[CreateFromExternalUserInfo]](), [[LoadByEmail]](), [[LoadByName]](), and Load() to CurrentUser_Local.pm; it also added [[CanonicalizeEmailAddress]](), [[CanonicalizeUserInfo]](), and [[LookupExternalUserInfo]]() to User_Local.pm
# Comment out or remove any previous LDAP config settings in [=${RTHOME}/etc/[[RT SiteConfig|RT_SiteConfig]].pm]
# Follow the instructions in the '''New Installs''' section above.

=== Configuration ===

These settings may now be found at [[LdapSiteConfigSettings]].

=== RT::User Overlay ===

This file may now be found at [[LdapUserLocalOverlay]].

=== Troubleshooting ===

*Note: There is considerable installation/debugging discussion at http://www.justatheory.com/computers/programming/perl/rt/ldap_auth.html as relates to getting the configuration right for another implementation of LDAP authentication (and which may still apply to your problem). You should review that if you're having difficulty getting this to work.*

'''Q: Does it automatically add new accounts?'''

/A: Yes./

'''Q: Does it automatically refresh the information from LDAP?'''

/A: Yes./

'''Q: Help! My information is not automatically being updated from LDAP. Why is this?'''

/A: All users must have the [[ModifySelf]] right in order for the LDAP information to refresh/

'''Q: Why don't you have a running RT instance or an LDAP server?'''

/A: I do, at my day job. However, the config there is a considerable distance from what I'd refer to as "real world," so the code we use for all of this has additional complications. Consequently, much of this implementation has been adjusted as I put it in the wiki, which also explains the multiple disclaimers and my general nervousness about the codebase./

'''Q: How can I autocreate accounts with certain attributes (e.g. Privileged, etc.)'''

/A: Put this into your [[RT SiteConfig|RT_SiteConfig]].pm:/

 <nowiki>### Autocreating users
 #
 # What default attributes should we pass to RT::User-&gt;Create?
 Set($AutoCreate, {Privileged =&gt; 1});
 
 </nowiki>

'''Q: My LDAP query is failing and because I want all of the results, I haven't specified an LDAP filter. Why won't it work?'''

/A: You HAVE to specify a filter in your [[SiteConfig]], or change the User_Local.pm code to fix the bug/

There is a bug in User_Local.pm that means that if you don't specify a search filter in the [[SiteConfig]], the filter string that gets created by User_Local.pm is (replacing sAMAccountName for whatever you have mapped to your RT username field):

 (&amp;(sAMAccountName=username)())
 

The problem is, you cannot have empty parenthesis in an LDAP search, hence, I recommend adding this line:

 if ($ldap_filter eq "()") { undef($ldap_filter) };
 

anywhere between

 my $ldap_filter     = $ldap_config{'AuthFilter'};
 

and

 my $filter_string = '(&amp;(' . $RT::LdapAttrMap-&gt;{'Name'} . '=' .
   $self-&gt;Name . ')' . $ldap_filter . ')';
 

This way, if you don't define a search filter, you get:

 (&amp;(sAMAccountName=username))

instead of

 (&amp;(sAMAccountName=username)())

which fails.

 <nowiki>* Added by Mike Peachey on 03/01/07 pending response from JimMeyer
 * I am still waiting on a response from JimMeyer to have this bug fixed in the released code - 20/11/2007
 
 </nowiki>

'''Q: Ldap +SSL does not work'''

/A: You can try "ldaps://ldap.yourserver.com" as a servername/

=== To Do ===

* [[LdapConfigInfo]]() should take an optional list of required config vars and fail if they're not all defined
* Refactor code to eliminate goofy <code>$ldap_foo = $ldap_config{foo}</code> statements.
* Make LDAP-sourced user information immutable in all RT interfaces (web and CLI)
* Look into using PAM for authentication?