Changes between Initial Version and Version 1 of DirectoryAuthPlugin

Timestamp:

Sep 18, 2012, 10:26:11 AM (12 years ago)

Author:

Ryan J Ollos

Comment:

Moved from ActiveDirectoryAuthPlugin.

DirectoryAuthPlugin

@@ +1 @@
+[[PageOutline(2-5,Contents,pullout)]]
+= Active Directory Auth Plugin =
+
+'''NOTE:''' Major changes from 0.3 
+ - conf variables are renamed for standardization
+ - now more directory type agnostic
+ - soon will be renamed to DirectoryAuthPlugin
+
+== Description ==
+
+The Active Directory Auth Plugin is a password store for the AccountManagerPlugin that provides authentication and groups from Active Directory. 
+
+Users are authenticated by performing an ldap_bind against the AD server using their credentials.  The plugin will also pull the email address and display name from Active 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. 
+
+== Groups == 
+ - One can specify a group which users must be a member of in order to log in.  
+ - Additionally, one may specify an ''admin'' group.  If a user is a member of the ''admin'' group, then they will automatically be granted the `TRAC_ADMIN` permission.
+ - Finally, !ActiveDirectory groups are extended into the trac namespace.  They can be used to extend permissions by AD group.
+   - AD groups are prefixed by @ 
+   - group names are lowercase and spaces are replaced with underscores.
+
+ See [ActiveDirectoryAuthPlugin/GroupManagement GroupManagement] for more details.
+
+== Caching == 
+Given the expense of traversing the network for authorizations, a two-stage cache has been implemented.  This caches data in the database for all instances of python, and in memory for each instance; while maintaining expiration and flushing the cache(s) as necessary. See: [ActiveDirectoryAuthPlugin/CacheManagement CacheManagement] for details. 
+
+== Bugs/Feature Requests == 
+
+Existing bugs and feature requests for ActiveDirectoryAuthPlugin are 
+[report:9?COMPONENT=ActiveDirectoryAuthPlugin here].
+
+If you have any issues, create a 
+[http://trac-hacks.org/newticket?component=ActiveDirectoryAuthPlugin&owner=sandinak new ticket].
+
+== Download ==
+
+Download the zipped source from [download:activedirectoryauthplugin here]
+
+== Source ==
+
+You can check out ActiveDirectoryAuthPlugin from [http://trac-hacks.org/svn/activedirectoryauthplugin here] using Subversion, or [source:activedirectoryauthplugin 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(activedirectoryauthplugin, 3)]]
+
+== Author/Contributors ==
+
+'''Author:''' [wiki:pacopablo] [[BR]]
+'''Maintainer:''' sandinak [[BR]]
+'''Contributors:'''