Changes between Version 64 and Version 65 of LdapPlugin


Ignore:
Timestamp:
Mar 11, 2015, 12:26:00 PM (9 years ago)
Author:
figaro
Comment:

Cosmetic changes, tagged with license

Legend:

Unmodified
Added
Removed
Modified
  • LdapPlugin

    v64 v65  
    1 = LDAP extensions =
    2 
    31[[PageOutline(2-4)]]
    42
    5 == Abstract ==
    6 
    7 LDAP support with group management has been added as a Trac extension. This
    8 extension enables the use of existing LDAP groups to grant permissions rather than
    9 defining permissions for every single user on the system.
    10 
    11 The latest release also
    12 permits storage of permissions (both users and groups permissions) in the LDAP
    13 directory itself rather than in the SQL backend.
    14 
    15 The original proposal for LDAP ACL is documented under ticket
    16 trac:#535 on the official web site.
     3= LDAP extensions to grant group permissions
     4
     5== Description
     6
     7LDAP support with group management has been added as a Trac extension. This extension enables the use of existing LDAP groups to grant permissions rather than defining permissions for every single user on the system.
     8
     9The latest release also permits storage of permissions (both users and groups permissions) in the LDAP directory itself rather than in the SQL backend.
     10
     11The original proposal for LDAP ACL is documented under ticket trac:#535 on the official web site.
    1712
    1813This plugin uses the same license as Trac.
    1914
    20 == Requirements ==
    21 
    22 This plugin works with
     15== Requirements
     16
     17This plugin works with the following versions:
    2318  * Trac 0.10, for the 0.5.x series
    2419  * Trac 0.11, for the 0.6.x series
     
    3328Please refer to the TracPlugins page for information about plugin installation.
    3429
    35 ==== Important note ====
    36 
    37  1. '''You need to apply all patches mentioned in #6268 on Windows, otherwise the plugin will not work.'''
    38  1. You need to grab a recent version of Trac from the trunk to make the (optional) Ldap permission store extension work as expected.[[BR]]
    39 As the trunk API may vary without notice, the plugin may be broken if you run it with a different release.
    40 
    41 == Download ==
     30'''Notes''':
     31
     32 1. You need to apply all patches mentioned in #6268 on Windows, otherwise the plugin will not work.
     33 1. You need to grab a recent version of Trac from the trunk to make the (optional) Ldap permission store extension work as expected. As the trunk API may vary without notice, the plugin may be broken if you run it with a different release.
     34
     35== Download
    4236
    4337Download the zipped source from [download:ldapplugin here].
    4438
    45 == Source ==
     39== Source
    4640
    4741You can check out LdapPlugin from [http://trac-hacks.org/svn/ldapplugin here] using Subversion, or [source:ldapplugin browse the source] with Trac.
    4842
    49 == Configuration ==
     43== Configuration
    5044
    5145You must configure 3 different places:
    52  1. '''Authentication (Apache configuration):''' Get access to the ldap server for reading out the groups
    53  2. '''Configure the plugin (section [ldap] in trac.ini):''' Get the groups by mapping the interesting part of the server's LDAP directory to this plugin
    54  3. '''Give Trac permissions to the groups (Trac web interface menu Admin):''': Map the known Trac permissions to the LDAP groups
     46 1. Authentication (Apache configuration): Get access to the ldap server for reading out the groups.
     47 1. Configure the plugin (section [ldap] in trac.ini): Get the groups by mapping the interesting part of the server's LDAP directory to this plugin.
     48 1. Give Trac permissions to the groups (Trac web interface menu Admin): Map the known Trac permissions to the LDAP groups.
    5549 
    56 === Authentication ===
    57 
    58 LdapPlugin does '''not''' perform authentication: Apache2 does, through the HTTP
    59 protocol, as with any other Trac installation. Same authentication is available through IIS if you disable anonymous user and enable Integrated Windows Authentication on your site.[[BR]]
    60 LdapPlugin retrieves the groups to which the authenticated user belongs and
    61 checks the TracPermissions
    62 against these groups, along with the regular permissions for the user.
    63 
    64 You probably want to use Apache2 LDAP authentication as well.[[BR]]
    65 This topic is out of scope of this document but you may find useful information
    66 on the official Apache2 mod_ldap
    67 web site.
    68 
    69 You may find a [http://vanalboom.org/node/15 recent roundup] on the whole setup for both Apache and Trac quite helpful.
    70 
    71 ==== Apache 2.0 ====
     50=== Authentication
     51
     52LdapPlugin does '''not''' perform authentication: Apache2 does, through the HTTP protocol, as with any other Trac installation. The same authentication is available through IIS if you disable anonymous user and enable Integrated Windows Authentication on your site.
     53
     54LdapPlugin retrieves the groups to which the authenticated user belongs and checks the TracPermissions against these groups, along with the regular permissions for the user.
     55
     56You probably want to use Apache2 LDAP authentication as well. This is out of scope of this document but you may find useful information
     57on the official Apache2 mod_ldap web site.
     58
     59You may find a [http://vanalboom.org/node/15 roundup] on the whole setup for both Apache and Trac quite helpful.
     60
     61==== Apache 2.0
    7262
    7363Here is an example of a typical LDAP section of an Apache2.0 configuration file:
     
    8777}}}
    8878
    89 ==== Apache 2.2 ====
     79==== Apache 2.2
    9080
    9181Since the mod_auth_ldap module has been superseded by the mod_authnz_ldap module for Apache 2.2, the configuration also needs a little tweaking. The above example would now look like:
     
    10797}}}
    10898
    109 Note that if you just use "Require valid-user" (to allow everybody with a valid LDAP login to access trac) you must set "AuthzLDAPAuthoritative off" according to the Apache documentation.
    110 
    111 
    112 === Plugin Configuration ===
    113 
    114 You need to customize the `trac.ini` file of your project, then[[BR]]
     99Note that if you just use "Require valid-user" (to allow everybody with a valid LDAP login to access Trac) you must set "AuthzLDAPAuthoritative off" according to the Apache documentation.
     100
     101=== Plugin Configuration
     102
     103You need to customize the `trac.ini` file of your project:
    115104 1. Optionally add the path to your plugin directory.
    116105 1. Enable `ldapplugin` in `[components]` section, so that the Trac engine  loads and uses this extension.
     
    118107 1. Configure the LDAP directives to fit your LDAP server configuration.
    119108
    120 To enable LdapPlugin you must add this line to the `[components]` section:
     109To enable LdapPlugin you must add this line to the `[components]` section of `trac.ini`:
    121110
    122111{{{
     
    126115}}}
    127116
    128 The `[ldap]` section may contain the following options (which are presented  down here with their default values)
     117The `[ldap]` section may contain the following options (presented here with their default values):
    129118
    130119{{{
     
    179168}}}
    180169
    181 You probably want to define at least `enable=true` and the `basedn`[[BR]]
    182 The meaning of the options are pretty straightforward for LDAP administrators.
     170You probably want to define at least `enable=true` and the `basedn`. The meaning of the options are straightforward for LDAP administrators.
    183171
    184172A typical setup for group resolution would look like this:
     
    191179}}}
    192180
    193 A typical setup for all LDAP support (group resolution and permission store)
    194 would look like this:
     181A typical setup for all LDAP support (group resolution and permission store) would look like this:
    195182
    196183{{{
     
    206193}}}
    207194
    208 ==== Note ====
     195==== Note
    209196
    210197If you get an error message like this:
     
    217204https://trac-hacks.org/ticket/6183
    218205
    219 ===== Note about `group_rdn` and `user_rdn` =====
     206===== Note about `group_rdn` and `user_rdn`
    220207
    221208Starting from release '''v0.4.0''', `group_basedn` and `user_basedn` options have been superseeded with `group_rdn` and `user_rdn`.[[BR]]
     
    234221}}}
    235222
    236 
    237 ==== Authenticated LDAP connections ====
    238 
    239 If the server requires an authenticated connection to retrieve group permissions,
    240 you want to set `group_bind = true` in the `[ldap]` section and define
    241 the credentials as follows:
     223==== Authenticated LDAP connections
     224
     225If the server requires an authenticated connection to retrieve group permissions, you want to set `group_bind = true` in the `[ldap]` section and define the credentials as follows:
    242226
    243227{{{
     
    249233}}}
    250234
    251 If the server requires an authenticated connection to modify group permissions,
    252 you want to set `store_bind = true` in the `[ldap]` section and define
    253 the credentials as follows:
     235If the server requires an authenticated connection to modify group permissions, you want to set `store_bind = true` in the `[ldap]` section and define the credentials as follows:
    254236
    255237{{{
     
    261243}}}
    262244
    263 ''Note'': Most LDAP servers require authenticated bind to perform any kind of
    264 modifications. Anyway, it would be a bad idea to allow modifications from
    265 anybody.
    266 
    267 ==== Ldap permission store ====
    268 
    269 If you wish to use the LDAP permission store feature, you need to tell Trac to
    270 use the LDAP extension rather than the internal default permission store which
    271 relies on the SQL backend.
    272 
    273 Note that if you decide to store Trac permissions as a ''new'' LDAP attribute,
    274 you will need LDAP schema management rights. Furthermore, some LDAP servers
    275 (e.g. Active Directory) might not allow the deletion of attribute definitions.
    276 
    277 To achieve this setting, add the following line to
    278 the main `[trac]` section of your `trac.ini` configuration file:
     245'''Note''': Most LDAP servers require authenticated bind to perform any kind of modifications. Anyway, it would be a bad idea to allow modifications from anybody.
     246
     247==== Ldap permission store
     248
     249If you wish to use the LDAP permission store feature, you need to tell Trac to use the LDAP extension rather than the internal default permission store which relies on the SQL database.
     250
     251Note that if you decide to store Trac permissions as a ''new'' LDAP attribute, you will need LDAP schema management rights. Furthermore, some LDAP servers, eg Active Directory, might not allow the deletion of attribute definitions.
     252
     253To achieve this setting, add the following line to the main `[trac]` section of your `trac.ini` configuration file:
    279254
    280255{{{
     
    286261
    287262You also need to enable `LdapPermissionStore` for LdapPlugin by adding:
     263
    288264{{{
    289265#!ini
     
    292268}}}
    293269
    294 The extension differentiates '''group permissions''' from '''user permission'''.
    295 This permits to use distinct objectclasses in the LDAP directory, to store
    296 permission. For example thanks to the `groupattr` and `uidattr`
    297 attributes, you can define group permission to LDAP entries such as
     270The extension differentiates '''group permissions''' from '''user permission'''. This permits to use distinct objectclasses in the LDAP directory, to store permission. For example thanks to the `groupattr` and `uidattr` attributes, you can define group permission to LDAP entries such as:
     271
    298272{{{
    299273dn: cn=managers,dc=example,dc=org
     
    315289}}}
    316290
    317 It is worth noting that the '''dn''' used for groups and for users may be
    318 different, which should make things easier to add TracPermissions into your existing LDAP directory.
    319 
    320 To differentiate a group name from a user name in `trac-admin`, prefix the group
    321 name with the `@` characters. This syntax has been borrowed from Samba
    322 and many other software dealing with group management.[[BR]]
    323 One would grant the above permissions using the following `trac-admin` commands
     291It is worth noting that the '''dn''' used for groups and for users may be different, which should make things easier to add TracPermissions into your existing LDAP directory.
     292
     293To differentiate a group name from a user name in `trac-admin`, prefix the group name with the `@` characters. This syntax has been borrowed from Samba and many other software dealing with group management.
     294
     295One would grant the above permissions using the following `trac-admin` commands:
    324296{{{
    325297#!sh
     
    331303}}}
    332304
    333 Please note that the LDAP permission store '''never''' attemps to create a new
    334 entry in the LDAP directory. To grant (or revoke) permissions to/from the LDAP
    335 directory, the targetted LDAP entry should exist in the directory and the
    336 attribute defined by the `permattr` option should be writtable for the
    337 `store_user` user.
    338 
    339 Please have a look at the LdapPluginTests page to get an overview of LDAP ACLs
    340 (access control lists) that manages LDAP operations on a directory.
    341 
    342 === Permissions ===
    343 
    344 Once LDAP support has been activated, you can use the web interface menu item `Admin` or `trac-admin` as usual to
    345 define TracPermissions.[[BR]]
    346 However, you can now use the existing groups defined in your LDAP directory to
    347 assign permissions.
    348 
    349 A LDAP group should start with the '`@`' character
    350 
    351 Example:
     305Please note that the LDAP permission store '''never''' attemps to create a new entry in the LDAP directory. To grant (or revoke) permissions to/from the LDAP directory, the targetted LDAP entry should exist in the directory and the attribute defined by the `permattr` option should be writtable for the `store_user` user.
     306
     307Please have a look at the LdapPluginTests page to get an overview of LDAP ACLs (access control lists) that manages LDAP operations on a directory.
     308
     309=== Permissions
     310
     311Once LDAP support has been activated, you can use the web interface menu item `Admin` or `trac-admin` as usual to define TracPermissions. However, you can now use the existing groups defined in your LDAP directory to assign permissions.
     312
     313A LDAP group should start with the '`@`' character, such as:
     314
    352315{{{
    353316#!sh
     
    369332}}}
    370333
    371 Here, people who are declared in the 'administrator' LDAP group have the
    372 `TRAC_ADMIN` permission, and people who are declared in the 'betatesters'
    373 LDAP group have the `WIKI_CREATE` and `WIKI_MODIFY` permission.
    374 
    375 You can obviously still use permissions for regular user such as ''eblot'' in
    376 the example above.
    377 
    378 '''Note''': Please remember that ''anonymous'' and ''authenticated'' are special users
    379 but are considered by the permission backend just like any other regular user.[[BR]]
    380 This means that you need to add both these special users in your LDAP directory
    381 if you wish to assign permission to these joker entries.
    382 The directory configuration proposed in
    383 the test page may give you some hints about how to setup
    384 your LDAP directory.
    385 
    386 ===== Group of names =====
     334Here, people who are declared in the 'administrator' LDAP group have the `TRAC_ADMIN` permission, and people who are declared in the 'betatesters' LDAP group have the `WIKI_CREATE` and `WIKI_MODIFY` permission.
     335
     336You can obviously still use permissions for regular user such as ''eblot'' in the example above.
     337
     338'''Note''': Please remember that ''anonymous'' and ''authenticated'' are special users but are considered by the permission backend just like any other regular user.[[BR]]
     339This means that you need to add both these special users in your LDAP directory if you wish to assign permission to these joker entries.
     340The directory configuration proposed in the test page may give you some hints about how to setup your LDAP directory.
     341
     342===== Group of names
    387343
    388344There are usually two flavours to manage group permissions in LDAP:
    389  1. The group contains a list of fully qualified dns
     345
     346 1. The group contains a list of fully qualified dns:
    390347{{{
    391348dn: cn=fakedoctors,ou=groups,dc=example,dc=org
     
    397354member: uid=izzie,ou=groups,dc=example,dc=org
    398355}}}
    399    With such an environment, your [ldap] section would contain
     356   With such an environment, your [ldap] section would contain the following:
    400357{{{
    401358#!ini
     
    407364groupmember = member
    408365}}}
    409  1. The group contains a list of simple uids
     366 1. The group contains a list of simple uids:
    410367{{{
    411368dn: cn=fakedoctors,ou=groups,dc=example,dc=org
     
    417374memberUid: uid=izzie
    418375}}}
    419    With such an environment, your [ldap] section would contain
     376   With such an environment, your [ldap] section would contain the following:
    420377{{{
    421378#!ini
     
    440397}}}
    441398
    442 ==== Global vs. Environment permissions ====
     399==== Global vs. Environment permissions
    443400
    444401Starting from release '''v0.3.0''', permissions are not defined globally (unless `global_perms` is set in the environment configuration file), but on per-environment basis.
    445402
    446 With environment-wide permissions, it is now possible to define distinct permissions for each Trac environment (as long as their name differ) even if they access the same LDAP directory.[[BR]]
    447 
    448 The Trac LDAP permission attribute value are prefixed with the environment name.[[BR]]
    449 Using the previous example, assuming the environment name is named "test", permission attributes would become:
     403With environment-wide permissions, it is now possible to define distinct permissions for each Trac environment (as long as their name differ) even if they access the same LDAP directory.
     404
     405The Trac LDAP permission attribute value are prefixed with the environment name. Using the previous example, assuming the environment name is named "test", permission attributes would become:
     406
    450407{{{
    451408dn: uid=courtney,dc=example,dc=org
     
    467424From the administrative point of view (`trac-admin`, WebAdmin, ...), there are no changes: permission are defined and retrieved as usual.
    468425
    469 ''Note:'' The environment ''name'' is based on the root directory of the Trac environment. This means that if you use different environment with the same name, such as:
     426'''Note:''' The environment ''name'' is based on the root directory of the Trac environment. This means that if you use different environment with the same name, such as:
    470427`/var/local/trac/test` and `/var/db/test`, they are both named "test" and share the same permissions. This is a known limitation of the current implementation.
    471428
    472 == Group management ==
     429=== Group management
    473430
    474431Starting from release '''v0.4.1''', the LdapPlugin permission store offers two ways to store group membership:
     
    478435   In this configuration, the plugin only uses the LDAP groups to manage group membership. The plugin adds or removes group members from existing LDAP groups[[BR]]
    479436
    480 ==== Activation ====
     437==== Activation
    481438
    482439The new group management scheme can be activated using the `manage_groups` option.
    483440
    484 ==== Example ====
    485 The following permission command
     441==== Example
     442
     443The following permission command:
    486444{{{
    487445#!sh
    488446permission add eblot @developers
    489447}}}
    490 would lead to a very modification in the LDAP directory
    491 
    492  1. The ''permission-based'' setting would add a `tracperm` attribute to the user entry
     448would lead to a modification in the LDAP directory.
     449
     450 1. The ''permission-based'' setting would add a `tracperm` attribute to the user entry:
    493451{{{
    494452# eblot, people, example.org
     
    498456...
    499457}}}
    500  1. The ''LDAP group'' setting would add a new `member` attribute to the group entry
     458 1. The ''LDAP group'' setting would add a new `member` attribute to the group entry:
    501459{{{
    502460# developers, groups, example.org
     
    508466}}}
    509467
    510 ==== Important notes ====
     468==== Important notes
    511469
    512470 1. The LDAP plugin is not able to create new groups or new users from scratch. Users and groups must already exist in the LDAP directory. It would be difficult to create a new LDAP group or a new LDAP user from Trac, as the creation of a LDAP resource usually requires properties which are not made available to the LDAP plugin.[[BR]]
     
    517475   * {{{permission add devteam @developers}}} is managed as a LDAP directory group (if `manage_groups` option is enabled)
    518476
    519 == Known limitations ==
     477== Known limitations
    520478
    521479 * Only LDAP v3 protocol is supported. This extension may work with v2 protocol
     
    523481 * Several assumptions made by the plugin proved to be unreliable in at leave one Active Directory based implementation.  #6268 contains fixes to work better with AD in cases where the Common Name is not the same as the sAMAccountName.
    524482
    525 == !ToDo list ==
     483== !ToDo list
    526484 
    527  * Add user detail support so that the full name and email address are
    528    retrieved from the LDAP server. It would require a new extension point in
    529    Trac engine, which might be called `IUserDirectory` (not before Trac 0.11 at best) - Note: A patch on #6268 implements this.  It's a bit of a kludge, but it's been working without issue thus far.
    530  * There's probably a lot of room for improvement (and debugging) ;-)
    531 
    532 == Testing ==
    533 
    534 The LdapPluginTests page gives some hints about how to test the Ldap extension for
    535 Trac
    536 
    537 == Bugs/Feature Requests ==
     485 * Add user detail support so that the full name and email address are retrieved from the LDAP server. It would require a new extension point in Trac engine, which might be called `IUserDirectory` (not before Trac 0.11 at best) - Note: A patch on #6268 implements this. It's a bit of a kludge, but it's been working without issue thus far.
     486 * There's probably a lot of room for improvement and debugging.
     487
     488== Testing
     489
     490The LdapPluginTests page gives some hints about how to test the Ldap extension for Trac.
     491
     492== Bugs/Feature Requests
    538493
    539494Existing bugs and feature requests for !LdapPlugin are [report:9?COMPONENT=LdapPlugin here].
     
    541496If you have any issues, create a [/newticket?component=LdapPlugin new ticket].
    542497
    543 == History ==
     498[[TicketQuery(component=LdapPlugin&group=type,format=progress)]]
     499
     500== History
    544501
    545502 * '''v0.0''': First attempt to write a LDAP bridge for Trac based on Trac 0.8, which required some hacks into the Trac engine.
     
    562519 * '''v0.7.0''': Support for Trac 0.12
    563520
    564 === Recent Changes ===
    565 
    566 [[ChangeLog(ldapplugin, 4)]]
    567 
    568 == Author/Contributors ==
     521== Recent Changes
     522
     523[[ChangeLog(ldapplugin, 3)]]
     524
     525== Author/Contributors
    569526
    570527'''Author:''' eblot [[BR]]