Setting up the Group Mapping Plug-in

Last Modified: 07-March-2014

This document covers the installation and setup of the group mapping plug-in (plg_ldap_mapping) that can be found in version 2. It is assumed pkg_ldap_plugins has been installed by following the installation in Configuring LDAP Settings.

Jump to:
  1. Configuring the Plug-in
  2. Example Setup

Configuring the Plug-in

This section demonstrates the usage for the group mapping plug-in parameters.

  1. Open the 'LDAP - Group Mapping' configuration through the Plug-in Manager.
  2. The following table shows the usage and examples of each parameter in the plug-in:

    Key Description / Examples / Usage
    Sync on Login

    Synchronise the LDAP group mapping when a user logs in.

    Example: set this to No if the site will use manual synchronisation for group mapping only (i.e. using the LDAP Cron script).

    Abort Login

    Abort the user login procedure if group mapping fails to synchronise on login.

    Sync Groups

    Specify the synchronisation mode for groups.

    If set to Pull Only: groups will only be pulled (downloaded) from LDAP.

    If set to Push and Pull: groups will be both pulled (downloaded) and pushed (uploaded) to LDAP. This means the user groups on the LDAP server will be modified. The proxy user specified in the LDAP host configuration must have adequate write permissions to promote and demote users in the directory.

    Allow Additions

    Specifies whether to allow group additions to user objects. This also allows groups to be added back to LDAP users if the Push and Pull setting was defined for Sync Groups.

    If set to Yes: allow the plug-in to add groups to users when it satisfies the condition for the add from the 'Mapping List'.

    If set to No: the plug-in never adds any groups to users.

    Example: set this to No to manually add groups to users through Joomla's user manager. Set this to Yes if the plug-in should automate Joomla group additions.

    Allow Removals

    Specifies whether to allow group removals from user objects. This also allows groups to be removed from LDAP users if the Push and Pull setting was defined for Sync Groups.

    If set to Yes & Default Managed: allows the plug-in to remove managed groups from users if they do not satisfy any conditions for a specified Joomla group ID from the 'Mapping List'. Also, all Joomla groups are defaulted as managed with this setting.

    If set to Yes: same as 'Yes & Default Managed' except that that all Joomla groups are defaulted as unmanaged.

    If set to No: the plug-in never removes any groups from a user.

    NOTE: If removal is allowed then only Joomla groups that are managed can be removed regardless of the 'Mapping List' contents. Read more about managed groups here.

    Examples: set to Yes & Default Managed if each Joomla group maps to an LDAP group and only the LDAP directory should be used to manage group assignments.

    On the other hand, if the site has a lot of Joomla groups that do not map to any LDAP groups, then set this to Yes.

    Set to No to manually remove groups from users. This could be due to a different department administering Joomla to that of the LDAP directory.

    Unmanaged Groups

    Specify Joomla group ID's delimited by a semicolon that should be overridden to an unmanaged state. In this context, unmanaged means specified Joomla groups are never removed from a user even if they exist in the 'Mapping List'. This doesn't affect groups being added to users, only the removal of them.

    It might be beneficial to override the super users group in case of a error in the Mapping List that may accidentally lead to demotion of super users. Though this is optional.

    Example: 7;8.

    Registered Group

    Specify Joomla's registered group ID used when a user has no mappings. Joomla fails to save users when they have no group associations, therefore one always needs to be mapped. In a default installation, the registered group ID is 2.

    Mapping List

    Specify the list of group mapping entries. Each entry is made up of a LDAP Group DN (pointing at a group object), and one or more Joomla group ID's. Use a colon to separate the Group DN from the Joomla group ID(s). Adding multiple group ID's for one LDAP DN can be achieved with a comma between each group ID. Each entry should use the form:

    <Group DN>:<Joomla Group IDs>

    Multiple entries can be achieved with a newline.

    Note: Joomla group ID's specified in this list are classed as managed unless overridden in the 'Unmanaged Groups' value.

    The DN doesn't have to be a full DN ONLY IF the Sync Groups is set to Pull Only. With Pull Only sync mode, DN's must have atleast the group container RDN for each entry. Be aware that if only the group container RDN is specified, then any other groups with an identical group container in the directory shall also match the entry. However, when the Sync Groups is set to Push and Pull full DN's MUST be used.

    Example: lets presume the following:

    Joomla Groups:
    21Student Council
    34IT Admins
    LDAP Structure:
    OU|– School
    OU|–– Staff
    CN|––– Staff Group
    CN|––– SLT Group
    OU|–– Students
    CN|––– Student Group
    CN|– Users
    CN|–– Domain Admins
    CN|–– Enterprise Admins

    Map all domain admins to the IT admins and administrators groups:

    CN=Domain Admins,CN=Users:7,34

    Map all staff to the registered and staff groups:

    CN=Staff Group,OU=Staff:2,30

    Map all students to the registered and students groups:

    CN=Student Group,OU=Students:2,20

    Map all senior leadership team to the SLT group:

    CN=SLT Group,OU=Staff:32

    These would come together by separating each entry by a newline (Valid for Pull Only mode):

    CN=Domain Admins,CN=Users:7,34
    CN=Staff Group,OU=Staff:2,30
    CN=Student Group,OU=Students:2,20
    CN=SLT Group,OU=Staff:32

    These would come together by separating each entry by a newline (Valid for Pull Only & Push and Pull modes):

    CN=Domain Admins,CN=Users,DC=ACME,DC=LOCAL:7,34
    CN=Staff Group,OU=Staff,DC=ACME,DC=LOCAL:2,30
    CN=Student Group,OU=Students,DC=ACME,DC=LOCAL:2,20
    CN=SLT Group,OU=Staff,DC=ACME,DC=LOCAL:32

    That would be the contents of the list box.

    Validate DNs

    Specify whether to validate each DN located in the 'Mapping List' with PHP's ldap_explode_dn function.

    Set to Yes when using DN's in the 'Mapping List'.

    Set to No when any strings are used instead of DN's in the 'Mapping List'.

    Lookup Type

    In most cases, setting to either value should return the same groups. Set the best (or only) option for the environment. The option specified here is also used for recursion when enabled.

    Set to Forward: returns the users group membership list.

    Set to Reverse: returns the group's members list.

    Memberof Attribute

    Specify the attribute in LDAP that successfully returns the group from the user object (used for Forward Lookups). This attribute has to exist within the user object and may only get returned when specifically requested.

    Use memberOf for either Active Directory or OpenLDAP using the memberOf overlay.

    Use groupMembership for eDirectory.

    Member Attribute

    Specify the attribute in LDAP that successfully returns users from group objects (used for Reverse Lookups and Push Sync). This attribute has to exist within the group object.

    Use member for the majority of LDAP systems including Active Directory, eDirectory and OpenLDAP using standard schemas.

    Member DN Attribute

    Specify the user object attribute to use when searching for group membership (used for Reverse Lookups and Push Sync). Some LDAP schemas do not use a full DN to map group members and instead use the uid attribute.

    Lets look at this in more depth; when searching for group membership in a reverse lookup, the plug-in sets dn as the default which calls the LDAP filter:


    However, some schemas do not use a full DN to query membership and instead require the uid attribute which calls a LDAP filter similar to:


    (where member is the value of the Member Attribute parameter)

    For most schemas, dn is the correct setting.

    Use Recursion

    Recursion can be used to find nested groups (i.e. groups of members of groups). However, depending on the amount of groups in the LDAP directory, this could degrade performance of the LDAP server.

    If set to Yes: uses the 'Recursive Query' to find nested groups the user is assigned to.

    If set to No: only uses the top level groups the member is assigned to.

    DN Attribute

    Specify the attribute in LDAP that returns the Distinguished Name (DN) of a object. This is used to perform recursive forward lookups.

    For Active Directory set to distinguishedName.

    Max Depth

    Set the maximum recursive depth for nested groups. Set this value to 0 for unlimited depth.

  3. Set the plug-in to the Enabled state and click Save.

Back to Top

Example Setup

Group Mapping Plug-in