EXT: Generic User Administration using LDAP¶

What does it do?¶

This extension allows the management and import of hierarchically structured backend users, groups and roles stored in a LDAP directory. Tasks like user or group management can be delegated to non-admins.

You can:

• separate backend users, groups and roles in organizations, thus allowing easy management of separated websites in one TYPO3 instance
• delegate the right to create, edit and delete users or groups to other non-admin users
• manage data for other applications, e.g. mail addresses for use with a MTA like Postfix

This can solve several problems related to the administrator as bottleneck:

• The administrator's tasks are reduced to create and manage organizations, roles and the initial page structure; he does not need to set up each individual user as he is able to delegate this task.
• Hosting many sites in a single TYPO3 instance are easier to maintain because privileged site managers - without full administration rights - can act autonomous in their assigned subtrees.

Screenshots¶

Drag&drop action on a hierarchical structured user tree with limited rights.

Delegate a subtree to another group. But this module does not only set the owner group, it also adds TypoScript code, so that new pages belong to the associated group, even if they were created by someone with a different default user group.

As a user administrator you can modify accounts that are below yourself in the user hierarchy. If you are a group administrator, too, you can also set the group membership here. Please note:

• The prefix “msm” is fixed. It's the abbreviation of the organization and enforces the separation of the user account names.
• You can move the user in the hierarchy by setting a new parent user. This can also be done via drag&drop (see above).
• The screenshot was made using the msm_mueller account. He is both user and group administrator. So he can set new role and group memerships. But he can only assign roles he owns (he is not mailadmin, e.g.). And he can only assign groups that are below his own groups. (He is member of “msm_projekte”, but he can only assign the groups below.)
• Assignments can also be made the other way round: Edit a role or group and check/uncheck the users there.

Basic concept behind the extension¶

This extension offers a new kind of user and group management for TYPO3. Normally, “almighty” TYPO3 administrators can and have to

• create, modify and delete users
• create, modify and delete groups
• add/remove users to/from groups
• add/remove rights to/from groups
• assign pages to groups, so they can edit them

Unfortunately, these tasks can only be processed by administrators (except the last one, but it is normally restricted to the creator) and not by “normal” backend users. So, if there are many changes among the users (imagine a school at the beginning of the school year) the admin can become a “bottleneck”. The only way to allocate the duty to others is to create more admins. But this may not be the best way with regard to security ...

The ldap_gua extension and the concept behind gives the administrators the possibility to allocate at least some of the tasks mentioned above to other users. In addition, it also allows to use the managed account data for even more services than TYPO3 only (Postfix, Apache, SSH ...). The aim is to simplify the admin's life by using an LDAP directory service.

The concept in a nutshell:

• Backend user accounts are stored hierarchically (TYPO3: flat), also groups and roles.
• The extensions differentiates between groups and roles, though both are mapped to TYPO3 groups:
  • Roles can be used to assign rights (to use functions or modules ) to users; the administrator can set the ACLs in the TYPO3 groups accordingly. There are also some system roles needed by the extension itself.
  • Groups can be used to pool users together to assign TYPO3 pages to them, describing where the functions gained by the role membership (see above) can be used.
• Users and groups are grouped by “organizations”. At least one organization is required.
• If someone has the role of a user administrator (one of the extension specific roles), he or she can edit other user accounts without being a TYPO3 admin. He or she can also assign roles to these accounts. But, only user accounts below (hierarchical) the performing user can be managed and only owned roles can be assigned or withdrawn. This allows the delegation of parts of the user administration to non-admins!
• If someone has the role of a group administrator (another extension specific role), he or she can create, edit or delete groups and assign users to them. This does only include the group's name and the members, nothing further. While all users of an organization can be added or removed, only groups below the own group can be edited. This keeps the hierarchy intact. Group administrators can also assign subtrees of TYPO3 pages to groups. All in all this allows the delegation of many group related tasks to non-admins!

All users¶

All TYPO3 users with access to the administration module (which is highly recommended) can change their password there. Everyone will find a pencil icon next to its entry in the user's tree. Clicking on it will show a form with the user's data that is stored in the directory. The password text fields are located below the group and role membership information. Keep in mind: Do NOT change the password at the user's settings dialog of TYPO3, because it will not be written to the LDAP directory and will not be usable for other services, maybe even in TYPO3 (depending on your system's configuration).

(Dirk Fraser is logged in and can edit his entry to change the password; the group & role information is read-only.)

User administrators¶

As a user administrator you can create, edit and delete user accounts below yourself (in the directory structure) and assign the roles you own to them.

To create a user account, go th the “Manage Users” form and click the top right symbol to add an entry. Enter a username (organization prefix is preset) and the name. Next, choose the parent user. Your account is preset, but you can also create the account below any existing account in your subtree. Now you can assign roles to the user by checking the boxes next to the role entries. If you do not own a certain role, its box has a red cross and cannot be assigned. If you want to assign a role that has a subrole, you only have to assign the top role as the roles below are assigned implicitly. Finally you have to set an initial password for the user.

To edit or delete a user account just click on the pencil symbol next to the user's name. Of course, you can only edit users hierarchically below yourself. When editing an entry you may notice checkboxes next to roles that cannot be unchecked. Then another user administrator (with this role) gave this role to this user, but you cannot remove this unless you own this role, too. Boxes with grey checkmarks show roles the user owns implicitly.

(User administrator “Jane Bar” can add entries and modify entries below. She can also edit her own entry, but only to change the password.)

If you want to shift a user to another place in the hierachy, you can edit its “parent user” setting, so the whole user including its subtree is moved to the new position. You can also achieve this by drag&drop: in the user tree, drag the user symbol to the new parent element and drop it. Here you can also select if you want to move the whole subtree or just the single account.

A user account can be deleted by editing the entry and clicking the “delete” button at the bottom. Similar to above, you have the choice to delete the single entry or the whole subtree. This form will also appear if the user does not have any subordinated users, just as a security measure.

Keep in mind: Not all characters are allowed in a username to avoid problems with the LDAP directory.

There is a second way to assign roles to users: You can use the “Manage roles” form, edit a role and check/uncheck the boxes next to the usernames there. This might be useful if you have to change the assignment of many users to one role.

(User administrator “Jane Bar” can also edit the roles she owns and add/remove users there. But only accounts below her own can be edited.)

Group administrators¶

As a group administrators you can create, edit and delete groups and delegate TYPO3 items to these groups.

To create a new group, go th the “Manage Groups” form in the administration module and click the top right symbol to add an entry. Enter a groupname (organization prefix is preset) and a description. Next, choose the parent group. Now you can add users to this group by checking the boxes next to the usernames.

To edit or delete a group just click on the pencil symbol next to the groupname. If you want to shift a group to another place in the hierachy, you can edit its “parent group” setting, so the whole group including its subtree is moved to the new position. You can also achieve this by drag&drop: in the user tree, drag the group symbol to the new parent element and drop it. Here you can also select if you just want to move the whole subtree or just the single group.

A group can be deleted by editing the entry and clicking the “delete” button at the bottom. Similar to above, you have the choice to delete the single entry or the whole subtree. This form will also appear if the group does not have any subordinated groups, just as a security measure.

(Group administrator “Jane Bar” is (explicit) member of jdh_projects. She cannot edit the group itself, only add and modify groups below.)

(Jane Bar can add all users of the organizaiton to the group. She does not need to be an explicit member, because she is a member of the parent group jdh_projects.)

There is a second way to assign groups to users: Use the “Manage users” form and edit a user account. There you can change its group membership, too, at least for the groups you are administrator of. When editing a user entry you may notice checkboxes next to groups that cannot be unchecked. Then another group administrator has assigned this group to this user, but you cannot change this unless you are member of one of its supergroups, too. Boxes with grey checkmarks show implicit group memberships.

(Jane Bar can change the group membership of Peter Smith, at least for the groups she is administrator of.)

The group members are only allowed to edit TYPO3 pages and other elements if they are the owners or in the owning group. When you create a new group, it might be necessary to assign pages to it. This can be done with the “delegation” module. You can select a page in the middle column and get the subtree including the owning group. Each page that belongs to your group or one of its subgroups has a pencil icon next to it. Clicking on it brings up the dialog to change the owner group.

(Jane Bar is group administrator of the jdh_projects group. She can edit the associated pages.)

(Jane Bar can delegate the “Journal” page to one of her groups, e.g. jdh_journal. All members of jdh_jorunal (and its parent groups) can now edit this page.)

Mail account administrators¶

Note: This role is only available if the ldap_gua extension was configured with mail account management enabled (see the sections “Administration” and “Configuration”).

As a mail account administrator you can set and remove mail accounts of subordinated users. It can be done with the “Manage user” form. The edit form of each user has a field where you can enter a mail address. The domain is preset by the organization. When you enter a mail address, it will also be written to the TYPO3 mail attribute of the user profile. When a user enters his own address in his profile, the address stored in the LDAP is not affected.

(The mail account administrator jdh_admin can set a mail address for the user jdh_lsteele.)

System administrators¶

We have users and user administrators, we have groups and group administrators. But there are no distinct administrators for organizations and roles. They are grouped together as “system administrators”. And these are identical to the TYPO3 admins. So, there is no way to set this role in ldap_gua; all TYPO3 admins are system admins. There are some pragmatic reasons:

• TYPO3 admins have raw access to the LDAP directory, because they have to set up the ldap_gua module. They could override any restriction manually.
• Role administrators have to edit the mapped TYPO3 groups and set the ACLs. This can only be done by TYPO3 admins.
• Organization admins should create an initial pagetree for the new organization, set up domain records, prepare the webserver, set a template ... Normally this has to be done by the TYPO3 admin.

As you may notice, there is no reason, why TYPO3 admins should or could be separated from our “system administrators”. They also own all roles implicitly.

As a system administrator you can add and remove organizations with the “Manage organizations” form. Keep in mind, that the domain cannot be changed after creation. After an organization was added, an initial user, group and local role are added. The names of them can be changed in the extension's configuration (see following sections). The initial password of the autocreated user is its full username (including the organization shortcut).

A system administrator can also create, edit and delete roles. The “Manage roles” form shows all global roles and the local roles of the selected organization. There are two icons to add roles, the left for local roles and the right for global roles. The behaviour of this form is similar to the groups form, except that drag&drop will not work for local to global roles and vice versa.

Do not forget to adjust the ACL of the mapped TYPO3 groups after a role was created.

Requirements¶

The ldap_gua requires the following software, additional to the typical TYPO3 requirements:

• running LDAP server
• PHP with LDAP and mhash module

LDAP¶

If you want to use the extension, you have to install, setup and prepare a LDAP directory first. Below the root element, you need at least two containers: one for the (global) roles and one for the organizations. The roles element should contain the entries for the global roles. These are not absolutely required but recommended. A minimal setup could look like this:

(This screenshot was made with the phpLDAPadmin extension; might be helpful for you, too ...)

If you want to use the mail account management module, you also have to add a mail administrator role. For more information, read the following section.

The organization and the roles container there are both “organizationalUnit” objects, the role entries are “organizationRole” objects. This is recommended by the authors, but it's up to you what you want to use.

ldap_gua¶

At the module configuration you can enable or disable the “e-mail account administration”. If enabled an additional module is loaded that allows the management of mail accounts in the LDAP directory. These entries can be read by Postfix and other mail server software. With all accounts and passwords in the directory, you can offer a single source for authentication. If you want to use it, do not forget to add a global mail admin role (see above). You can manage even more attributes by writing your own extension (have a look at the “Extending ldap_gua” section).

To complete the installation, add the required configuration directives (see “Configuration” section).

After this, please run “LDAP Sync” at least once. First of all, this will test your mapping rules. As ldap_gua relies on ldap_server and ldap_sync, they have to be set up properly! Second, this sync should create the new “useradmin”, “groupadmin” (“mailadmin”) groups in your TYPO3 instance. You can also use the LDAP Sync module later, if you faced sync problems or if you made manual changes to the directory.

Finally set up your first organization. Go to “Administration” and select “manage administration” from the first dropdown menu. Add an organization by clicking the (+) button. While creating a new organization, also initial user, group and local role will be set up.

TYPO3¶

Keep in mind: the predefined roles do only have effects at the ldap_gua extension. If you want a role (predefined or your own) to have an effect in TYPO3, you have to modify the mapped groups in TYPO3 – just the common way. An example: You may want that only group administrators can see the “Delegation” module in their backend menu (it does not make sense for others ...). So you should set the ACLs of the TYPO3 group “groupadmin” accordingly. The topic is also discussed in the “Basic concept” section.

Extending ldap_gua¶

The extension offers hooks to add other modules, similar to the mail account administration. Of course, the possibility to use XCLASSes is also always given. Possible reasons where additional funcionality is required or useful:

• Want to have a “kickstarter”, so that while creating an organization an initial page structure is added? Just write a small extension and use the corresponding hooks.
• Want to manage additional user data like address, telephone number etc.? You can write a small extension and use the hooks to add your own fields and functions to write the entered data to the directory.
• Some MDAs might require to execute a special command to create mailbox. With a XCLASS you can add this functionality to the corresponding method in the existing mail account administration module.

You can find nearly all hooks available at the end of the class.tx_ldapgua.php except two: init and extConfiguration. These are called in the module's init() function. If you need more hooks, just contact us via email.

General settings¶

After installing ldap_gua you can enable or disable the mail account administration module in the extension manager. You can switch the addition on or off at any time, but keep in mind to provide the required addition configuration settings (see below).

TypoScript setup¶

The ldap_gua extension uses the server records of the ldap_server extension. For more information refer to its manual.

lang = MAP_OBJECT
lang.value = de
lang.special = value

subgroup = MAP_OBJECT
subgroup {
  special = children
  userFunc = tx_ldapserver->getBESubGroups
  userFunc {
    table = be_groups
    identField = tx_ldapserver_dn
  }
}

workspace_perms = MAP_OBJECT
workspace_perms.value = 0
workspace_perms.special = value
workspace_perms.default = 1

ou=organizations

top,organization,domainRelatedObject

o

associatedDomain

admin

manager

typo3users

.

ou=users

top,account,simpleSecurityObject

uid

userPassword

seeAlso

(seeAlso:distinguishedNameMatch:=###IDENT###)

be_users

tx_ldapserver_dn

ou=groups

top,nisNetgroup

cn

be_groups

tx_ldapserver_dn

ou=roles

top,organizationalRole

cn

be_groups

tx_ldapserver_dn

cn=useradmin

cn=groupadmin

Initial setup¶

include         /etc/openldap/schema/core.schema
include         /etc/openldap/schema/cosine.schema
include         /etc/openldap/schema/inetorgperson.schema
include         /etc/openldap/schema/rfc2307bis.schema
include         /etc/openldap/schema/qmail.schema
# Version 2 bind might be required by MTA
allow bind_v2
loglevel        0
schemacheck     on
pidfile         /var/run/slapd/run/slapd.pid
argsfile        /var/run/slapd/run/slapd.args
database        bdb
checkpoint      1024    5
cachesize       10000
suffix          "dc=gua"
rootdn          "<rootDN>"
rootpw          <password>
directory       /var/lib/ldap
# some indices
index   objectClass     eq
index   seeAlso eq
index   uid     eq
index   cn      eq
# use SSHA instead of MD5
password-hash {SSHA}
access to attrs=userPassword
    by anonymous auth
    by self write
    by * none
access to *
    by self write
    by users read
    by * read

BEusers = LDAP_SYNC
BEusers {
        enable = 1
        table = be_users
        basedn = dc=gua
        handleNotFound = 1
        handleNotFound {
                delete = 1
        }
        pid = root
        filter = (&(objectClass=account))
        uniqueField = tx_ldapserver_dn
        fields {
                username = MAP_OBJECT
                username.attribute = uid
                password = MAP_OBJECT
                password.attribute = userPassword
                realName = MAP_OBJECT
                realName.attribute = description
                email = MAP_OBJECT
                email.attribute = mail
                tx_ldapserver_dn = MAP_OBJECT
                tx_ldapserver_dn.special = DN
                lang = MAP_OBJECT
                lang.value = de
                lang.special = value
                options = MAP_OBJECT
                options.value = 3
                options.special = value
                workspace_perms = MAP_OBJECT
                workspace_perms.value = 0
                workspace_perms.special = value
                usergroup = MAP_OBJECT
                usergroup {
                        attribute = seeAlso
                        userFunc = tx_ldapserver->getBEGroups
                        userFunc {
                                pid = root
                                table = be_groups
                                identField = tx_ldapserver_dn
                        }
                }
        }
}

BEgroups = LDAP_SYNC
BEgroups {
        enable = 1
        pid = root
        table = be_groups
        handleNotFound = 1
        handleNotFound {
                delete = 1
        }
        basedn = dc=gua
        filter = (|(objectClass=organizationalRole)(objectClass=nisNetgroup))
        uniqueField = tx_ldapserver_dn
        fields {
                username >
                usergroup >
                tx_ldapserver_dn = MAP_OBJECT
                tx_ldapserver_dn.special = DN
                title = MAP_OBJECT
                title.attribute = cn
                description = MAP_OBJECT
                description.attribute = description
                workspace_perms = MAP_OBJECT
                workspace_perms.value = 0
                workspace_perms.special = value
                workspace_perms.default = 1
                subgroup = MAP_OBJECT
                subgroup {
                        special = children
                        userFunc = tx_ldapserver->getBESubGroups
                        userFunc {
                                table = be_groups
                                identField = tx_ldapserver_dn
                        }
                }
        }
}

BEauth = LDAP_AUTH
BEauth {
   enable = 1
   table = be_users
   sync < BEusers
}

gua_config = LDAP_GUA
gua_config {
        enable = 1
        organizations {
                rdn = ou=schools
                ldapClasses = top,organization,domainRelatedObject
                idAttribute = o
                domainAttribute = associatedDomain
                initialUser = admin
                initialGroup = schoolmanager
                initialLocalRole = typo3user
                separator = _
        }
        users < BEusers
        users {
                rdn = ou=users
                ldapClasses = top,account,simpleSecurityObject
                idAttribute = uid
                passwordAttribute = userPassword
                referenceAttribute = seeAlso
                membershipFilter = (seeAlso:distinguishedNameMatch:=###IDENT###)
                mailAccount {
                        ldapClasses = qmailUser
                        addressAttribute = mail
                }
        }
        groups < BEgroups
        groups {
                rdn = ou=groups
                ldapClasses = top,nisNetgroup
                idAttribute = cn
        }
        roles < BEgroups
        roles {
                rdn = ou=roles
                ldapClasses = top,organizationalRole
                idAttribute = cn
                sysRoles {
                        useradmin = cn=useradmin
                        groupadmin = cn=groupadmin
                        mailadmin = cn=mailadmin
                }
        }
}

server_host = localhost
search_base = ou=schools,dc=gua
bind_dn = <rootdn or other with read access>
bind_pw = <password>
scope = sub
query_filter = (|(mail=%s)(mailAlternateAddress=%s))
result_attribute = uid

Set up roles¶

As already mentioned we do not want to grant write access to the live workspace to all backend users. Therefore we add two new global roles with the ldap_gua administration tool (use the right + icon): first “reviewer” and then below this entry the role “editor”. The hierarchy implies that all reviewers are editors, too, so everyone who should work in TYPO3 has the editor role. We can use this fact to define rights for all users at one: We go to Web>List and open the root node, where we find the new TYPO3 group “editor”, and edit this entry: Checking the “ACL” box gives us the possibility to enable important modules, access rights to tables and so on. We must not forget to grant the permission to access the administration module, otherwise users would not be able to change their password. And as mentioned above, we do not want that ordinary editors have write access on the live workspace, so none of the workspace permission boxes is checked.

Let us continue with the reviewer TYPO3 group. When we open the edit form we can see that the group has “editor” as subgroup – as we entered it in the administration module. Reviewers have to be able to commit changes to the live system, so we have to grant them access rights on the live workspace. Keep in mind: In this scenario a reviewer has write access to all pages (on the live workspace) that belong to one of his groups; it is not possible that a reviewer in groups A and B has write access (live) to all pages of group A, but cannot edit pages of group B (live). So a reviewer has his role for all groups he is in.

Finally, the TYPO3 group named “groupadmin” should be able to see the delegation module, which can also be set via ACLs.

Set up organizations¶

Now the first school “JohnDoe high school” wants to go online, so we create a new organization first. This can be done with the “Manage organizations” form in the administration module. We add a new entry with a shortcut “jdh”, its full name and the future domain. Keep in mind that the shortcut and the domain cannot be modified later any more! Some initial entries were added automatically: jdh_schoolmanager as the first group, jdh_typo3user as the first local role and jdh_admin as the first user, with is member of the (initial passwort: “jdh_admin”).

Now we set up a new page tree in TYPO3, add the templates, add a domain record and all the TYPO3 specific stuff to host a site in the CMS. This also includes the creation of a separate workspace for the new school, with the “reviewers” TYPO3 group as reviewers and jdh_typo3user as members (no dedicated workspace owner!). Then we assign the root node of the new page subtree to the jdh_typo3user group as DB mount, maybe also an additional file mount. Now we see the use of local roles: All school related settings can be gathered there. And all new users of this school should own this local role (if they are editors, too), so they are able to see their school's pages.

Finally we have to assign the whole school subtree to the jdh_schoolmanager group, so jdh_admin is able to edit and delegate the pages. This should be done with the Web>Delegation module.

This setup procedure might look a bit tricky, but it has to be done only once for each school: Now the school can act idependent because their local administrator can set up groups and users on his own. Only the role management has to stay in the TYPO3 administrator's hands.

Daily usage¶

The jdh_admin user is able to create groups and users, that can be privileged with different roles. Imagine a teacher called Jane Bar; she is responsible for the projects section. The school administrator can now create a new group jdh_projects (below jdh_schoolmanager) and assign the projects subtree to the new group. Then he can add the new user jdh_jbar: She should edit and review pages, so she gets the roles jdh_typo3user and jdh_reviewer. She should also be able to add accounts and groups for students, so she will be a groupadmin and useradmin, too.

Jane Bar is the head of the school's newspaper, so she creates a new group “jdh_newspaper” (below jdh_projects) and some new student accounts (below herself). The new users there are part of this group and should receive some rights: They should be able to edit pages in the draft workspace only, so they receive the roles jdh_typo3user and jdh_editor. Finally she can assign a certain area of the projects page tree to the newspaper group (delegation module). The newspaper editors can create and modify pages in that special part of the site but are not able to publish them online. This has to be done by Jane Bar or the school administrator.

See also the “Users manual” section.

((generated))¶