How to map AD role to custom named role

Oh, silly me, I messed it up all.

So, with some little knowledge/research about LDAP and after reading Advanced configuration guide my final question is:

What exactly LDAP group is meaning? DN for LDAP group?

In examples from Advanced configuration guide,

  // LDAP group => Drupal role
  'cn=users,ou=Group,dc=example,dc=com' => 'Users',
  'cn=IT,ou=Group,dc=example,dc=com' => 'SiteAdmins'

I can assume that there is OU 'Groups' in LDAP hierarchy. Beneath that OU is laying CN definitions of user groups in that specific LDAP. So LDAP group is DN for that group, right?

In my example (in Active Directory), DN for CN of one group is:
CN=Small department,OU=Small department,OU=Big department,OU=City,DC=example,DC=local

And when I put it in ldapgroups.conf.php file it looks like this:

function ldapgroups_role_mappings() {
  return array(
    // LDAP group => Drupal role

    // Make sure the last group->role mapping does NOT have a trailing comma (,).
    //'cn=admin,ou=Group,dc=example,dc=com' => 'IT'
    'CN=Small department,OU=Small department,OU=Big department,OU=City,DC=example,DC=local' => 'small'
  );
}

And it is not working. :(

I'm starting to believing that this is a bug, another example that I tried with is (this AD group): CN=Users,DC=example,DC=local, according to hierarchy in my AD.

Here I come again, and this is last time I hope so, at least in this issue! ;)

Thanks to (unresolved) Active Directory groups within groups within groups... support request, I found out where I was making mistake, and I'm posting it as patch to LDAP Integration documentation (also changed Category to task and component to Documentation).

Configuration of ldapgroups module documentation node (just last sentence):

• Groups are specified by LDAP attributes:

  Use this option if the user object contains an attribute that represents the group the user belongs to. This is most commonly applicable to Active Directory environment. The attribute of the user object that holds the group DN is memberOf.
  Also it is necessary to use this option if you are using Active Directory and want to map/filter AD groups to Drupal roles.

And here is patch to:

LDAP Integration Advanced configuration documentation node (it need to be inserted just above "Uncomment the function ldapgroups_roles_filter." unordered list item):

If you are using Active Directory and it is structured similar to this:

DC=tld (aka top level domain like 'org', 'com' or 'local')
  |
  +-- DC=sld (aka second level domain like 'drupal', 'google', etc)
  |     |
  |     +-- CN=... (e.g. 'Users', 'Computers', etc.) 
  |     |
  |     +-- OU=City 1
  |     |     |
  |     |     +-- OU=Office 1
  |     |     |     |
  |     |     |     +-- OU=... (e.g. 'Computers', etc.)
  |     |     |     |
  |     |     |     +-- CN=Office 1
  |     |     |     |
  |     |     |     +-- OU=Users
  |     |     |           |
  |     |     |           +-- CN=User 1
  |     |     |           |
  |     |     |           +-- CN=User 2
  |     |     |           |
  |     |     |           +-- CN=User ...
  |     |     |           .
  |     |     |           .
  |     |     |           .
  |     |     |
  |     |     |
  |     |     +-- OU=Office ...
  |     |     .     .
  |     |     .     .
  |     |     .     .
  |     |     
  |     +-- OU=City ...
  |     .     .
  |     .     .
  |     .     .
  |

then you need to edit modules/ldap_integration/ldapgroups.conf.php file and specify your AD groups and their role names like presented in example below:

function ldapgroups_role_mappings() {
  return array(
    // LDAP group => Drupal role

    // Make sure the last group->role mapping does NOT have a trailing comma (,).
    //'cn=admin,ou=Group,dc=example,dc=com' => 'IT'
    'CN=Office 1,OU=Office 1,OU=City 1,DC=sld,DC=tld' => 'First office',
    'CN=Office 2,OU=Office 2,OU=City 1,DC=sld,DC=tld' => 'Second office'
  );
}

This part of code is from ldapgroups.conf.php file from 6.x version of LDAP integration module, but syntax for specifying the AD group is same as in 5.x version.

Another important thing is to configure LDAP Groups (Administer >> Site Configuration >> LDAP Groups) by (AD) attribute of the user object that holds the group DN (which is memberOf).

>> End of documentation patch <<

I can also comment these documentation nodes if there is nobody to update them.

After all, it remains way mapping is not working when you configure ldapgroups with Group is specified in user's DN option in 'Group by DN' section. Maybe Active Directory is supposed to have groups stored only in (memberOf) user entries - then this would be OK behavior. I will try to find out this from our LAN admins and report it back in Active Directory groups within groups within groups... support request.

Cheers.

P.S.
I attached HTML code of my contribution to LDAP integration documentation, to make updating easier.