Platinum sponsors
This section should give you an impression how this and other extensions can be used together to realize a multi-site TYPO3 instance. Also the use of roles and groups should become clearer during the tutorial.
Let us have a look at the following scenario: We want to host several different school websites in a single TYPO3 instance to achieve a similar look though a single template (corporate identity), reduce the amount of updates etc. But as an administration you are not willing to manage to do the user management of 50 schools alone. In addition to this, we also want to mange all mail accounts, so the users do not need to remember two different user names and passwords. The schools do not want that all users have write access to the live site by default, so we wil use workspaces.
LDAP setup
First of all, we install TYPO3, an openLDAP server. Here is a sample slapd.conf file. The rootdn and rootpw have to be set. Important: The password hashing method must be changed to SSHA because ldap_gua only uses them at the moment for security reasons!
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
To handle mail accounts, we add the qmail schema to the directory's configuration. It might not be included in your distribution, try a search engine then. Now we should fill the LDAP directory with some required initial entries:
the root element of course; we will take dc=gua
an element for the global roles, we will use an organizationalUnit object at ou=roles,dc=gua here
an entry as “container” for the organizations, we also use an organizationalUnit object at ou=schools,dc=gua
Afterwards we add some global roles manually. This is not absolutely required, but we recommend it. It is possible to create them later with the help of the GUI, but then you know what to write to the configuration and you can easily test if the LDAP sync is working properly, at least for roles. So we add three organizaionalRole objects:
the user administration role at cn=useradmin,ou=roles,dc=gua with the description “user administrator”
the group administrator role at cn=groupadmin,ou=roles,dc=gua with the description “group administrator”
the mail account administrator role at cn=mailadmin,ou=roles,dc=gua with the description “mail administrator”
This was the LDAP part. Now we can finish the setup in TYPO3.
TYPO3 setup
In TYPO3 add the required extensions ldap_lib, ldap_server, ldap_auth, ldap_sync and ldap_gua. Adding the phpLDAPadmin extension might helpful. During the installation process, some features can be set. We check the box at the ldap_gua configuration, so we are able to manage mail addresses.
We have to add a ldap_server record somewhere in the system. This record will contain the information how to map the attributes of the directory elements to TYPO3 tables and some configuration data for ldap_auth and ldap_gua. It is also possible to manage frontend users with ldap_server, ldap_sync and ldap_auth, but we only need backend users and ldap_gua is limited to backend users, as frontend users follow some other principles.
After entering some system data (server type, address etc.) we add the mapping rules with TypoScript code. Most of it is straight forward and is also described in the ldap_server documentation. As already mentioned we also map the user's password to the TYPO3 password field, although TYPO3 cannot read the openLDAP password format, so the directory (access via ldap_auth later) is the single authentication authority. Associated groups and roles will be saved together in the seeAlso attribute. Now something new: We want to preset some profile attributes like workspace_perms, so that the workspace access is handled in the groups only. This can be done with a new “special” directive.
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
}
}
}
}
Now we add the mapping of groups and roles to TYPO3 groups. It is similar to the user object, but uses two special directives that are not found in the classic ldap_server extension. First, we want to set workspace_perms to zero by default, but it should be changeable by the administrator in TYPO3 later. The special=value directive would overwrite this setting at each sync, so we should set the new “default” attribute to 1. This means, that this value is only read when the recordset is created, not when it is updated. And, we want to get the subgroup information not from a single field but from elements hierarchically below the group entry. Here we use the new “special” directive “children”. For additional information about syntax and objects, see ldap_server manual.
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
}
}
}
}
We need some TypoScript code to tell ldap_auth where to get its data from. See ldap_auth description for detailed information.
BEauth = LDAP_AUTH
BEauth {enable = 1
table = be_users
sync < BEusers
}
After the mapping configuration is done, we click on the Web>LDAP Sync module, select the element that contains the ldap_server record and run the synchronization. It should transfer the useradmin, groupadmin and mailadmin group to the TYPO3 system. If you do “Simulate Sync” first, you will see all log entries twice, because the ldap_gua extension forces a double execution of the sync to map the subgroup relations properly.
Finally, the ldap_gua configuration. Here we have to tell ldap_gua how the current LDAP structure is and how new objects have to be created and so on. First, we describe the organizations. They should be stored in the ou=schools,dc=gua element; therefore “ou=schools” is the correct RDN. All schools should be created as organization objects (see ldapClasses) and the entries should be of the style “o=<school-id>,ou=schools,dc=gua”, so the idAttribute is “o” here. When a new organization is created, also an initial user, group and local role is added. Their names can be defined here. Later we will see how to use them, especially the role. Because some MDAs have problems with a dot in a username, we will use “_” as separator. Important: The separator option should be set immediately after installing these things (if required) and should not be changed afterwards. If you do not need mail support, just use the default dot, which might look more familiar.
After this, we add some information about the users, similar to above. We need some attributes there that are already set in the BEusers object, so we just copy this and add new attributes. The membershipFilter can be tricky, because seeAlso expects correct Dns and a special matching rule.
Groups and roles are quite similar; we also copy the data from BEgroups first. Remember: For TYPO3 our groups and roles are both just groups, therefore both read their data from BEgroups. The sysRoles array contains the RDNs of the mentioned extension specific roles. The full user administrator's DN is “cn=useradmin,ou=roles,dc=gua”. Please also note, that the RDN for roles is both used for global roles (with root entry as parent element) and for local roles (with organization as parent element).
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
}
}
}
MTA setup hint
We assume Postfix as the running MTA. In the main.cf you can add “ldap:/etc/postfix/LDAP_virtual_mailboxes.cf” at the “virtual maps” option. The file LDAP_virtual_mailboxes.cf could look like this:
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
Please note, that also the domain names have to be set and authenticated SMTP requires additional configuration. This depends on your system, so this sniplet just wants to give you an idea how to use the LDAP directory.
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.
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.
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.
