== Extension Point : ''IPermissionGroupProvider'' ==

||'''Interface'''||''IPermissionGroupProvider''||'''Since'''||0.9||
||'''Module'''||''trac.perm''||'''Source'''||[source:trunk/trac/perm.py perm.py]||

The ''IPermissionGroupProvider'' implementations define permission group membership information.

== Purpose ==

The TracPermissions system supports hierarchical [TracPermissions#PermissionGroups groups] to bundle and inherit permissions. The IPermissionGroupProvider interface can be used to get group membership information for users (e.g. from arbitrary external data sources).

(Note that currently the [TracPermissions#AddingaNewGroupandPermissions admin defined groups] are provided by the [source:trunk/trac/perm.py DefaultPermissionStore], not an IPermissionGroupProvider. See #5648)

== Usage ==

Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].

The group providers are called by the permissions system to provide the group membership information for a certain user name. This information is automatically cached and reused for some time.

== Examples ==

The following example uses an [http://timgolden.me.uk/python/active_directory.html active_directory] module to provide group membership information from Windows' default Active Directory:
{{{
#!python
import active_directory
from trac.core import *
from trac.perm import IPermissionGroupProvider

class ActiveDirectoryPermissionGroupProvider(Component):
    """Permission group provider providing Active Directory group membership 
    information."""

    implements(IPermissionGroupProvider)

    def get_permission_groups(self, username):
        aduser = active_directory.find_user(username)
        return list(aduser.memberOf)
}}}

== Available Implementations ==

In Trac:
|| [source:trunk/trac/perm.py DefaultPermissionGroupProvider] || Provides the basic builtin permission groups 'anonymous' and 'authenticated'. ||


In third-party plugins:

|| th:LdapPlugin || Provides groups from LDAP. ||
|| th:HtgroupsPlugin || Provides groups from a `.htgroup` file (usually used with Apache's `AuthGroupFile` or `AuthDigestGroupFile` directives). ||
|| th:AuthzGroupsPlugin || Provides groups from the SVN authz file. ||
|| th:TracSysgroupsPlugin || Provides groups from the unix / linux system groups. ||
|| th:UnixGroupsPlugin || Provides groups from the unix system groups. ||
|| th:TracUnixGroupsPlugin || Provide groups from the unix system groups. ||
|| th:wiki:SQLAuthStorePlugin || Provide groups from the SQL database. ||
|| [http://code.google.com/p/tracgoogleappsauthplugin/ TracGoogleAppsAuthPlugin] || Provide groups from a hosted Google Apps domain. ||
|| th:TracForgePlugin || Adds cross-project permissions with virtual groups. ||

== Additional Information and References ==

 * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.perm.IPermissionGroupProvider-class.html Epydoc API Reference]
 * See also [../trac.perm.IPermissionStore IPermissionStore], [../trac.perm.IPermissionPolicy IPermissionPolicy], [../trac.perm.IPermissionRequestor IPermissionRequestor] 
 * Related tickets:
  * #5648 Move user defined groups to IPermissionGroupProvider implementation
  * #2194 Provide user credentials to IPermissionGroupProvider
  * [query:status!=closed&keywords~=group group in keywords]
 * Related mailing list topics:
  * Early [Trac-ML:3072 design discussion]
  * Some discussion about possible [trac-dev:2758 future enhancements]