[[PageOutline(2-5,Contents,pullout)]]
= Directory Auth Plugin =

'''NOTE:''' Major changes from 0.3 
 - renamed to DirectoryAuthPlugin
 - conf variables are renamed for standardization
 - now more directory type agnostic
 - soon will be renamed to DirectoryAuthPlugin

== Description ==

The Directory Auth Plugin is a password store for the AccountManagerPlugin that provides authentication and groups from Lightweight Directory Access Protocol (LDAP) enabled service including [[http://www.openldap.org|OpenLdap]], [[http://en.wikipedia.org/wiki/Active_Directory|ActiveDirectory]] and [[en.wikipedia.org/wiki/Apple_Open_Directory|OpenDirectory]].

Users are authenticated by performing an ldap_bind against a directory using their credentials.  The plugin will also pull the email address and displayName from Directory and populate the `session_attribute` table.  See [http://pacopablo.com/blog/pacopablo/blog/set-assign-to-drop-down Populating ''Assign To'' Drop Down in Trac] for more information on why. 

== Features ==
 - Can use a service account to do lookups, or anonymous binding
 - Can use SSL if openssl is configured correctly ( I am working on some documentation for this ) 
 - Configurable .. many options to deal with the differences between directories and schema
 - Uses both memory and db based caching to improve performance
 - Now supports LARGE directories 
 - Can expand directory groups into the Trac namespace

See: [DirectoryAuthPlugin/TheoryOfOperation] for details


== Bugs/Feature Requests == 

Existing bugs and feature requests for DirectoryAuthPlugin are 
[report:9?COMPONENT=DirectoryAuthPlugin here].

If you have any issues, create a 
[http://trac-hacks.org/newticket?component=DirectoryAuthPlugin&owner=sandinak new ticket].

== Download ==

Download the zipped source from [download:directoryauthplugin here]

== Source ==

You can check out DirectoryAuthPlugin from [http://trac-hacks.org/svn/directoryauthplugin here] using Subversion, or [source:directoryauthplugin browse the source] with Trac.

== Install ==

==== Prerequisites ====

 - You must install AccountManagerPlugin in order to use this plugin.  
 - Python-LDAP is also required and can be downloaded [http://pypi.python.org/pypi/python-ldap/ here]

==== Installation ====

Follow the Trac documentation on how [http://trac.edgewall.org/search?q=TracPlugins to install Trac plugins]

 - starting with 0.3, a database upgrade will be required as part of the installation. 
   1. install the plugin and it's prerequisites
   1. update the database
{{{
#!sh
trac-admin /var/trac/instance upgrade
}}}
   1. restart the trac service or your webserver. 

== Examples ==
'''NOTE: this has changed from 0.3 to 0.4!!!!'''

All config options go under the [account-manager] config heading.  Options for this module are:

{{{
#!ini
[account-manager]
#--to use this module with AccountManager, ADAuthStore must be enabled inside of AccountManager
password_store = ADAuthStore
#--define the Active Directory host address here.  A port other than default(389) is set as
#  ldap://hostname:port or ldaps://hostname:port
dir_uri = ldap://adserver.example.com
#-- the Active Directory's base DN to search from, this is likely just your domain
dir_basedn = DC=example,DC=com
#-- the user/password to search the directory from, it must be a valid
dir_binddn = ldapuser@example.com
dir_bindpw = ldapuserpassword
#-- timeout for an ldap operation before in seconds
dir_timeout = 5
#-- the default charset for the ldap server
dir_charset = utf-9
##### Userinfo
#-- the attribute containing the users login name, THIS MUST BE UNIQUE!
user_attr = sAMAccountName
#-- the attribute containing the users display name
name_attr = displayName
#-- the attribute containing the users email addy
email_attr = mail
##### Groups
#-- where to look for groups, uses dir_basedn if not defined.
group_basedn = ou=Groups,dc=foo,dc=net
#-- expand directory groups
group_expand = 1
#-- the name of a group .. uses user_attr if not defined. 
group_attr = cn
#-- which attribute to look in for members
group_member_attr = member
#-- what to look for in the member_attr
group_member_value = dn
#-- the dn of a group that has valid users, all users if not enabled
group_validusers = CN=Alltechs,OU=Mail enabled groups,OU=Email,DC=serverplus,DC=com
#-- the DN for a group automagically given TRAC_ADMIN
#   if this option is enabled you must specify the UserExtensiblePermissionStore as the trac permission store, such as:
#   [trac]
#   permission_store = UserExtensiblePermissionStore
group_tracadmin = CN=Administration,DC=example,DC=com
#### Cache Tuning
#-- cached entry time to live in seconds 
cache_ttl= 90
#-- memorycache size in entries, and a highwater warning mark
cache_memsize = 400
cache_memsize_warn = 300
#-- memory cache prune size in percentage
cache_memprune = 5

[trac]
permission_store = UserExtensiblePermissionStore
}}}

If you are unsure of what the DNs for your groups are, you may want to use an LDAP browser to inspect your Active Directory schema to find out a group's DN.

== Common Errors ==

If you see Trac throwing an exception similar to "OPERATIONS_ERROR: In order to perform this operation a successful bind must be completed on the connection" when you know the bind user/pass is correct you will want to try connection to active directory on port 3268.  This may happen when AD is running across multiple machines.

== Recent Changes ==

[[ChangeLog(directoryauthplugin, 3)]]

== Author/Contributors ==

'''Author:''' [wiki:pacopablo] [[BR]]
'''Maintainer:''' sandinak [[BR]]
'''Contributors:'''