Changes between Version 64 and Version 65 of LdapPlugin
- Timestamp:
- Mar 11, 2015, 12:26:00 PM (9 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
LdapPlugin
v64 v65 1 = LDAP extensions =2 3 1 [[PageOutline(2-4)]] 4 2 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 7 LDAP 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 9 The latest release also permits storage of permissions (both users and groups permissions) in the LDAP directory itself rather than in the SQL backend. 10 11 The original proposal for LDAP ACL is documented under ticket trac:#535 on the official web site. 17 12 18 13 This plugin uses the same license as Trac. 19 14 20 == Requirements ==21 22 This plugin works with 15 == Requirements 16 17 This plugin works with the following versions: 23 18 * Trac 0.10, for the 0.5.x series 24 19 * Trac 0.11, for the 0.6.x series … … 33 28 Please refer to the TracPlugins page for information about plugin installation. 34 29 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 42 36 43 37 Download the zipped source from [download:ldapplugin here]. 44 38 45 == Source ==39 == Source 46 40 47 41 You can check out LdapPlugin from [http://trac-hacks.org/svn/ldapplugin here] using Subversion, or [source:ldapplugin browse the source] with Trac. 48 42 49 == Configuration ==43 == Configuration 50 44 51 45 You must configure 3 different places: 52 1. '''Authentication (Apache configuration):''' Get access to the ldap server for reading out the groups53 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 plugin54 3. '''Give Trac permissions to the groups (Trac web interface menu Admin):''': Map the known Trac permissions to the LDAP groups46 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. 55 49 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 52 LdapPlugin 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 54 LdapPlugin 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 56 You probably want to use Apache2 LDAP authentication as well. This is out of scope of this document but you may find useful information 57 on the official Apache2 mod_ldap web site. 58 59 You 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 72 62 73 63 Here is an example of a typical LDAP section of an Apache2.0 configuration file: … … 87 77 }}} 88 78 89 ==== Apache 2.2 ====79 ==== Apache 2.2 90 80 91 81 Since 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: … … 107 97 }}} 108 98 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]] 99 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. 100 101 === Plugin Configuration 102 103 You need to customize the `trac.ini` file of your project: 115 104 1. Optionally add the path to your plugin directory. 116 105 1. Enable `ldapplugin` in `[components]` section, so that the Trac engine loads and uses this extension. … … 118 107 1. Configure the LDAP directives to fit your LDAP server configuration. 119 108 120 To enable LdapPlugin you must add this line to the `[components]` section :109 To enable LdapPlugin you must add this line to the `[components]` section of `trac.ini`: 121 110 122 111 {{{ … … 126 115 }}} 127 116 128 The `[ldap]` section may contain the following options ( which are presented down here with their default values)117 The `[ldap]` section may contain the following options (presented here with their default values): 129 118 130 119 {{{ … … 179 168 }}} 180 169 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. 170 You probably want to define at least `enable=true` and the `basedn`. The meaning of the options are straightforward for LDAP administrators. 183 171 184 172 A typical setup for group resolution would look like this: … … 191 179 }}} 192 180 193 A typical setup for all LDAP support (group resolution and permission store) 194 would look like this: 181 A typical setup for all LDAP support (group resolution and permission store) would look like this: 195 182 196 183 {{{ … … 206 193 }}} 207 194 208 ==== Note ====195 ==== Note 209 196 210 197 If you get an error message like this: … … 217 204 https://trac-hacks.org/ticket/6183 218 205 219 ===== Note about `group_rdn` and `user_rdn` =====206 ===== Note about `group_rdn` and `user_rdn` 220 207 221 208 Starting from release '''v0.4.0''', `group_basedn` and `user_basedn` options have been superseeded with `group_rdn` and `user_rdn`.[[BR]] … … 234 221 }}} 235 222 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 225 If 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: 242 226 243 227 {{{ … … 249 233 }}} 250 234 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: 235 If 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: 254 236 255 237 {{{ … … 261 243 }}} 262 244 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 249 If 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 251 Note 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 253 To achieve this setting, add the following line to the main `[trac]` section of your `trac.ini` configuration file: 279 254 280 255 {{{ … … 286 261 287 262 You also need to enable `LdapPermissionStore` for LdapPlugin by adding: 263 288 264 {{{ 289 265 #!ini … … 292 268 }}} 293 269 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 270 The 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 298 272 {{{ 299 273 dn: cn=managers,dc=example,dc=org … … 315 289 }}} 316 290 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 291 It 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 293 To 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 295 One would grant the above permissions using the following `trac-admin` commands: 324 296 {{{ 325 297 #!sh … … 331 303 }}} 332 304 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: 305 Please 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 307 Please 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 311 Once 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 313 A LDAP group should start with the '`@`' character, such as: 314 352 315 {{{ 353 316 #!sh … … 369 332 }}} 370 333 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 ===== 334 Here, 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 336 You 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]] 339 This means that you need to add both these special users in your LDAP directory if you wish to assign permission to these joker entries. 340 The directory configuration proposed in the test page may give you some hints about how to setup your LDAP directory. 341 342 ===== Group of names 387 343 388 344 There 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: 390 347 {{{ 391 348 dn: cn=fakedoctors,ou=groups,dc=example,dc=org … … 397 354 member: uid=izzie,ou=groups,dc=example,dc=org 398 355 }}} 399 With such an environment, your [ldap] section would contain 356 With such an environment, your [ldap] section would contain the following: 400 357 {{{ 401 358 #!ini … … 407 364 groupmember = member 408 365 }}} 409 1. The group contains a list of simple uids 366 1. The group contains a list of simple uids: 410 367 {{{ 411 368 dn: cn=fakedoctors,ou=groups,dc=example,dc=org … … 417 374 memberUid: uid=izzie 418 375 }}} 419 With such an environment, your [ldap] section would contain 376 With such an environment, your [ldap] section would contain the following: 420 377 {{{ 421 378 #!ini … … 440 397 }}} 441 398 442 ==== Global vs. Environment permissions ====399 ==== Global vs. Environment permissions 443 400 444 401 Starting 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. 445 402 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: 403 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. 404 405 The 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 450 407 {{{ 451 408 dn: uid=courtney,dc=example,dc=org … … 467 424 From the administrative point of view (`trac-admin`, WebAdmin, ...), there are no changes: permission are defined and retrieved as usual. 468 425 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: 470 427 `/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. 471 428 472 == Group management ==429 === Group management 473 430 474 431 Starting from release '''v0.4.1''', the LdapPlugin permission store offers two ways to store group membership: … … 478 435 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]] 479 436 480 ==== Activation ====437 ==== Activation 481 438 482 439 The new group management scheme can be activated using the `manage_groups` option. 483 440 484 ==== Example ==== 485 The following permission command 441 ==== Example 442 443 The following permission command: 486 444 {{{ 487 445 #!sh 488 446 permission add eblot @developers 489 447 }}} 490 would lead to a very modification in the LDAP directory491 492 1. The ''permission-based'' setting would add a `tracperm` attribute to the user entry 448 would lead to a modification in the LDAP directory. 449 450 1. The ''permission-based'' setting would add a `tracperm` attribute to the user entry: 493 451 {{{ 494 452 # eblot, people, example.org … … 498 456 ... 499 457 }}} 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: 501 459 {{{ 502 460 # developers, groups, example.org … … 508 466 }}} 509 467 510 ==== Important notes ====468 ==== Important notes 511 469 512 470 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]] … … 517 475 * {{{permission add devteam @developers}}} is managed as a LDAP directory group (if `manage_groups` option is enabled) 518 476 519 == Known limitations ==477 == Known limitations 520 478 521 479 * Only LDAP v3 protocol is supported. This extension may work with v2 protocol … … 523 481 * 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. 524 482 525 == !ToDo list ==483 == !ToDo list 526 484 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 490 The LdapPluginTests page gives some hints about how to test the Ldap extension for Trac. 491 492 == Bugs/Feature Requests 538 493 539 494 Existing bugs and feature requests for !LdapPlugin are [report:9?COMPONENT=LdapPlugin here]. … … 541 496 If you have any issues, create a [/newticket?component=LdapPlugin new ticket]. 542 497 543 == History == 498 [[TicketQuery(component=LdapPlugin&group=type,format=progress)]] 499 500 == History 544 501 545 502 * '''v0.0''': First attempt to write a LDAP bridge for Trac based on Trac 0.8, which required some hacks into the Trac engine. … … 562 519 * '''v0.7.0''': Support for Trac 0.12 563 520 564 == = Recent Changes ===565 566 [[ChangeLog(ldapplugin, 4)]]567 568 == Author/Contributors ==521 == Recent Changes 522 523 [[ChangeLog(ldapplugin, 3)]] 524 525 == Author/Contributors 569 526 570 527 '''Author:''' eblot [[BR]]