If you have read any of the online Plone documentation or Plone books, you will notice that most of the topics covered in this book are not new. What is new is the Buildout-driven approach to site management. Buildout has been covered before, but only as an aside. A modern Plone site is comprised of many parts that may be tedious to assemble by hand. Fortunately, Buildout lends itself to the task.
Another tool, Make (http://www.gnu.org/software/make/), is perhaps equally well-suited to the task. If you are familiar with Make, Buildout should feel somewhat familiar. The first difference between them is the configuration file syntax. Another difference is that Make is written in C, and is typically used to compile C code, whereas Buildout is written in Python, and is typically used to assemble Python packages. Although they are different in many ways, both the tools share similar concepts:
Building targets or parts
Controlling the build process with configuration files
Detecting and reacting to changes on disk
But we digress whether you were familiar with Buildout or Make before reading this book does not matter. After reading it, you will be familiar with Buildout and will know how to use it to manage your Plone site.
At this point, we have discussed topics like installing Python, bootstrapping a Plone site, and changing the appearance.
In this chapter, we will discuss user management, group management, and related tasks.
You will learn:
Configuring mail settings in a development environment
Out of the box user and group management
User and group management, with LDAP
We will proceed to user and group management shortly. But first, let us address an important concern how to configure the mail settings when your site is in development.
If you browse to
http://localhost:8080/Plone and click on Site
Setup on your newly-created Plone site, you should see:
This warning message was designed to encourage folks to configure their mail settings now, rather than waiting for an error message to appear later, in case they failed to do so.
However, the need for the warning message mostly applies only to production sites. In development, you may not be running a mail server locally (that is, on your laptop), or you may not have access to the production mail servers, a mail server you can test with, and so on.
Having to configure the mail settings in production is expected, but having to configure them in development can be a mild annoyance. Nevertheless, having the mail server working in development is often quite handy, if not absolutely necessary.
You could use your own mail server, assuming you have one and know the settings for setting up the mail host.
Alternatively, you can create a free Gmail account (if you do not have one already) and use Google's Gmail service (http://gmail.com) to configure mail settings in Plone.
To configure mail settings using a Gmail account, click on the Mail control panel link as suggested, or browse
to
http://localhost:8080/Plone. Then, click on
Site Settings | Mail and enter
your Gmail account settings.
You should see (something like):
Also, enter your name and e-mail address in the Site 'From' name and Site 'From' address respectively, and click on Save.
You should now be able to use the contact form, add new users, and do anything in Plone that requires Plone to send mail.
If you want to avoid configuring your mail settings, but want to proceed with
user and group management, you could browse to http://localhost:8080/Plone.
Then, click on Site Setup | Security settings.
You should see:
Check the box and click on Save.
You should now be able to create users without configuring mail settings, because Plone will not be required to send mail when it creates users.
Other tasks, such as using the contact form will still fail.
Of course, allowing users to register without verifying an e-mail address presents its own set of problems, and more importantly, it presents the potential for abuse; so be careful.
Alternatively, you can enter bogus mail settings and force Plone to send a mail to the terminal by using Martin Aspeli's PrintingMailHost (http://pypi.python.org/pypi/Products.PrintingMailHost).
In 04-administration-mailhost.cfg, we have:
[buildout] extends = 03-appearance-zopeskel.cfg [instance] #eggs += Products.PrintingMailHost
You should now uncomment the eggs parameter to
make 04-administration-mailhost.cfg look like
this:
[buildout] extends = 03-appearance-zopeskel.cfg [instance] eggs += Products.PrintingMailHost
Now stop Plone (with Ctrl + C or Ctrl + Z/Enter) and run Buildout:
$ bin/buildout -c 04-administration-mailhost.cfg
You should see:
$ bin/buildout -c 04-administration-mailhost.cfg … Getting distribution for 'Products.PrintingMailHost'. Got Products.PrintingMailHost 0.7. …
$ bin/instance fg
You should see:
$ bin/instance fg … Hold on to your hats folks, I'm a-patchin' 2010-05-16 14:22:03 WARNING PrintingMailHost ************************************************************************ Monkey patching MailHosts to print emails to the terminal instead of sending them. NO MAIL WILL BE SENT FROM ZOPE AT ALL! Turn off debug mode or remove PrintingMailHost from the Products directory to turn this off. ************************************************************************ … 2010-05-16 14:22:09 INFO Zope Ready to handle requests
And now, if you browse to
http://localhost:8080/Plone, click on
Contact, fill in the contact form, and click on Send, you should see:
---- sending mail ----
…
You are receiving this mail because Alex Clark
[email protected]
is sending feedback about the site administered by you at http://localhost:8080/Plone.
The message sent was:
This site is great!
…
In other words, instead of trying to send the mail, Plone will print it.
Do not forget to disable the PrintingMailHost if you do not want this behavior.
Though the warning message suggests removing it from the products directory,
we have not installed the old-style Zope 2 product package (rather, we have
installed the new-style Python egg package with the help of Buildout). So, just
re-comment the eggs parameter of the
instance section, as shown:
[buildout] extends = 03-appearance-zopeskel.cfg [instance] #eggs += Products.PrintingMailHost
Now stop Plone (with Ctrl + C or Ctrl + Z/Enter) and run Buildout:
$ bin/buildout -c 04-administration-mailhost.cfg
Now start Plone:
$ bin/instance fg
This effectively configures the
04-administration-mailhost.cfg file to do nothing, as it is
configured to do so by default.
For many organizations, a few users (in a few groups with a few roles) are enough to satisfy their content-publishing needs. Other organizations may have more complex needs, and may require more than the out of the box (OOB) feature set.
In this chapter, we will focus on LDAP integration to handle these needs. However, let us cover the out of the box feature set first.
The Zope 2 administrator is a user at the Zope 2 application root level that has the Manager role. You will need this user at least initially to use Plone (for example, to create a Plone site object).
Conveniently, the plone.recipe.zope2instance recipe(http://pypi.python.org/pypi/plone.recipe.zope2instance) assists us with the creation of a Zope 2 administrator.
All you have to do is to configure the user parameter in
the instance section of your Buildout configuration file,
and run Buildout:
[instance] … user = admin:admin
However, note that this user exists in the database only (ZODB). Also, keep in mind that once this user exists, subsequent Buildout runs will not affect it. In other words, you cannot change the password for an existing user by changing it in your Buildout configuration file.
Plone supports users and groups for the purpose of adding and editing content. If you are not familiar with how to manage users and groups, see Chapter 8 of "Practical Plone 3", Packt Publishing (https://www.packtpub.com/practical-plone-3-beginners-guide-to-building-powerful-websites/book).
Once you have created a Plone site with users and groups within it, the top-level Zope 2 user becomes secondary (but is still important). A good rule of thumb is to treat the top-level Zope 2 administrator like an administrator in Windows, or like a root user in Mac OS X and Ubuntu Linux (and any UNIX) use it only when you need it.
A potential source of confusion is that the top-level Zope 2 user can log in
to the Plone site, but does not exist in the Plone site. To demonstrate this,
browse to
http://localhost:8080/Plone, click on Site
Setup | Users and Groups, and
click on Show all.
In other words, you see nothing, because Plone users do not exist yet. This is a good time to create a Plone administrator (that is, a user with the role of a Manager).
This user will be able to manage the Plone site, but not the Zope 2 application above it.
Now that you have configured the mail settings (or either avoided configuring
them or faked them) you can browse to
http://localhost:8080/Plone and click on
Site Setup | Users and Groups
to add a user.
Once you add a user, you can configure him or her to be an administrator by following these steps:
Browse to http://localhost:8080/Plone, then click
on Site Setup |
Users and Groups |<user> | Group memberships | Quick
search.
Enter Administrators in the text field and click on Search.
Check the box next to Administrators and click Add user to selected group.
You should be aware that we added this user to the Administrators group, rather than just assigning the role of a Manager directly to the user, which may be easier.
This method makes it easier to perform batch operations on a group of users later. Batch operations can include changing roles, sharing content, removing or disabling users, and so on.
Note
In Plone 4
In Plone 4, groups can be nested. Visit http://dev.plone.org/plone/ticket/5683 for more information.
Also, in Plone 4, you can add users to groups immediately using the add user form. Visit http://dev.plone.org/plone/ticket/9330 for more information.
You should see:
You are now free to add additional users and groups with this account, as well as to perform other administrative tasks that require the Manager role. Now, you are also free to log out of the top-level Zope 2 account until you need it again, which will probably be infrequent. In fact, it may be so infrequent that you may forget the password no problem!
We learned in Chapter 2 how to change the admin user's password through the Web, but what happens if you forget the password?
You can use the bin/instance script to create a new
administrator, like this:
$ bin/instance adduser admin2 some-password
But if the admin user exists already, do not try to reset the password, like this:
$ bin/instance adduser admin some-password
This command will fail silently, and you will wonder why it did not work. To avoid this problem, create another user first, for example admin2, and then log in with admin2 to reset admin user's password; remove the admin2 user if you like after that.
One of the downsides of adding users and groups in this way is that they only exist in the Plone database (ZODB) and as such, may be difficult to manage in large numbers.
Not to mention, you may need to deploy to an organization where an existing user database is in use (for example, LDAP or Active Directory (AD).
Connecting Plone to LDAP and Active Directory is covered in detail in Chapter 21 of "Practical Plone 3", Packt Publishing (https://www.packtpub.com/practical-plone-3-beginners-guide-to-building-powerful-websites/book). So, we will not repeat all of that information here (although there is some overlap).
We will not cover the installation of OpenLDAP or Active Directory, too. We will assume you (or a system administrator) can manage the task (if it is required by your organization).
What we will cover here is the installation and setup of
plone.app.ldap, with a particular focus on how Buildout works, and how
to achieve results as quickly as possible in Plone (as well as how to avoid
pitfalls).
Note
Installing OpenLDAP
If you need help installing OpenLDAP, there is a particularly good tutorial available here: http://www.debian-administration.org/article/OpenLDAP_installation_on_Debian.
While the installation is Debian-specific, most of everything else is not. In other words, if you are able to install OpenLDAP, you can follow the tutorial to perform the rest of the configuration steps.
In 04-administration-ldap.cfg, we have:
[buildout] extends = 03-appearance-zopeskel.cfg [instance] eggs += plone.app.ldap zcml += plone.app.ldap
We have extended the last known good configuration and have added
plone.app.ldap to the eggs and
zcml parameters in the instance section. The
current list of eggs now looks like this:
eggs = Plone collective.portlet.sitemap collective.portlet.explore webcouturier.dropdownmenu Products.Scrawl beyondskins.ploneday.site2010 plone.app.ldap
You can get this information by running Buildout, then looking at the
installed.cfg file in the root directory of your buildout.
Now stop Plone (with Ctrl + C or Ctrl + Z/Enter) and run Buildout:
$ bin/buildout -c 04-administration-ldap.cfg
You should see:
… Installing instance. Getting distribution for 'plone.app.ldap'. Got plone.app.ldap 1.2.1. Getting distribution for 'Products.PloneLDAP'. Got Products.PloneLDAP 1.1. Getting distribution for 'Products.LDAPUserFolder'. … Got Products.LDAPUserFolder 2.16. Getting distribution for 'Products.LDAPMultiPlugins'. Got Products.LDAPMultiPlugins 1.9. Getting distribution for 'dataflake.ldapconnection'. Got dataflake.ldapconnection 1.0. Getting distribution for 'python-ldap>=2.0.6'. extra_compile_args: extra_objects: … Got python-ldap 2.3.11. Getting distribution for 'dataflake.cache'. Got dataflake.cache 1.1. …
You will notice that plone.app.ldap and its dependencies
are now installed.
Note
Python-LDAP package dependencies
You should
experience trouble-free installations of
plone.app.ldap (and its dependencies such as
python-ldap) on fresh installs of Mac OS X and Ubuntu Linux
with the following two exceptions:
On Ubuntu
Linux you must install the libsasl2-dev
and libldap2-dev packages (and
optionally the libssl-dev
package).
On Windows, it is necessary to install
the python-ldap
package via the binary installer (for Python 2.4), available
from the Python Package Index
(http://pypi.python.org/packages/2.4/p/python-ldap/python-ldap-2.3.11.win32-py2.4.exe).
$ bin/instance fg
If you browse to http://localhost:8080/Plone and then click
on Site Setup |
Add-on Products, you should see:
Two LDAP-related packages are now listed as available
for install, only one of which is actually installable. If you
click on the product description of LDAPUserFolder, you will
see this message:
NOTE: Do not install the CMFLDAP GenericSetup extension profile into a Plone site. They are meant for pure CMF sites only and will break Plone.
In other words, do not install LDAPUserFolder in Plone. Instead, install only the LDAP support package.
Note
Do not install LDAPUserFolder in Plone
Why not? The short answer is that even though the package appears in Add-on products, it is not compatible with Plone.
The medium length answer is that
as the documentation in the product description states that
LDAPUserFolder is compatible with pure CMF sites. This means
that replacing the top-level Pluggable Auth Service
(http://pypi.python.org/pypi/Products.PluggableAuthService)
object (/acl_users at the Plone site level) would break
Plone.
The long answer is that Plone uses an add-on for Zope 2 called the Pluggable Auth Service to facilitate users and groups management (among other things). When you install plone.app.ldap, it will install PloneLDAP (http://pypi.python.org/pypi/Products.PloneLDAP), which will install the other dependencies (for example, LDAPMultiPlugins and LDAPUserFolder) and create an LDAPUserFolder for you inside the LDAP plugin, inside the Pluggable Auth Service (Plone level acl_users object).
Next, browse to http://localhost:8080/Plone , click
on Site Setup |
Add-on Product Configuration | LDAP
Connection | LDAP Servers, and
add a server.
To verify the connection, browse to
http://localhost:8080/Plone and click on
Site Setup | Zope Management
Interface | acl_users
| ldap-plugin |
Contents | acl_users | LDAP
Servers.
We now have five more tasks to perform, all of which can be done simultaneously (or separately, if you like) in the Global Settings tab of the LDAP configuration form:
Configure the RDN, user id, and login name attributes
Configure the bind DN and password
Configure the LDAP object classes
Configure the base DN for users and groups
Restart Plone (to force re-connect the LDAP connection)
However, before we begin those tasks, let us take a minute to define the terminology we are using.
What follows here is a very brief overview of LDAP terminology. See Chapter 21 of "Practical Plone 3", Packt Publishing (https://www.packtpub.com/practical-plone-3-beginners-guide-to-building-powerful-websites/book) for more details.
To understand the LDAP configuration form and Global Settings in particular, you need to understand (if you do not already) that one of the core features of LDAP is to provide a way to organize hierarchical data using unique string identifiers such as:
dn: uid=aclark,ou=People,dc=aclark,dc=net
The entry above is a Distinguished Name (DN), or a uniquely identifiable entry. We are simplifying this explanation of course, for brevity's sake. For more information, visit http://www.zytrax.com/books/ldap/.
In case these terms are not obvious, they are acronyms for Domain Component (DC),User ID (UID), and Organizational Unit (OU) respectively.
Distinguished names are comprised of Relative Distinguished Names (RDNs).
A common way to explain them is to compare them with Internet hostnames, which have a corresponding fully-qualified domain name.
For example, in the case of the host lucy.aclark.net,
lucy and aclark.net are both relative
distinguished names, while lucy.aclark.net is a
distinguished name, that is it is unique within the hierarchal
data.
With the information above, we know enough to fill in the Global Settings of the LDAP configuration form.
We assume the server type to be OpenLDAP because it is the most robust implementation. An Active Directory implementation will support only "read-only access".
Here, we are asked which of the following LDAP attributes we would like to use as a part of the LDAP DN used to create new users: CN, Mail, SN, or UID. While the default choice is CN, the most common choice is UID, which will create a DN like this:
dn: uid=aclark,ou=People,dc=aclark,dc=net
Here, we are asked which of the following LDAP attributes we would like Plone to use internally to identify users: CN, Mail, SN, or UID. While the default choice is CN, the most common choice is UID.
Here, we are asked which of the following LDAP attributes we would like to use for the Plone user account login name: CN, Mail, SN, or UID. In other words, it asks for the name the user types into the login form. While the default choice is CN, the most common choice is UID.
Setting the object class tells LDAP where to look for your objects. If you were to follow the LDAP tutorial on http://www.debian-administration.org/article/OpenLDAP_installation_on_Debian, you would notice that new users are created with the person object class: http://www.debian-administration.org/article/OpenLDAP_installation_on_Debian#id2503051.
In the case of our example, the aclark user looks
like this:
# aclark, People, aclark.net dn: uid=aclark,ou=People,dc=aclark,dc=net uid: aclark uidNumber: 20000 gidNumber: 20000 objectClass: top objectClass: person objectClass: posixAccount objectClass: shadowAccount loginShell: /bin/bash homeDirectory: /home/aclark sn: Alex Clark cn: Alex Clark
This means we must configure the person object
class in the LDAP object classes
field in Global Settings.
As mentioned earlier, we must configure an LDAP admin user in Plone to allow Plone to connect to our LDAP server as an administrator.
In the aclark example, the LDAP admin user looks
like this:
# admin, aclark.net dn: cn=admin,dc=aclark,dc=net objectClass: simpleSecurityObject objectClass: organizationalRole cn: admin description: LDAP administrator
This means we must configure the
cn=admin,dc=aclark,dc=net, and bind DN in the Bind DN field in
Global Settings.
Also, as mentioned earlier, this LDAP account has an associated password. If you are not familiar with how to install and configure OpenLDAP, create an admin account, and set the password. You can refer to http://www.debian-administration.org/article/OpenLDAP_installation_on_Debian#ldap-install.
If you are not using Debian (one of our target operating systems, Ubuntu Linux, is based on Debian at least) and have installed OpenLDAP from source (or vendor package), you can visit http://www.openldap.org/doc/admin24/quickstart.html.
In other words, you should be able to specify the LDAP admin user's password in the Bind password field in Global Settings.
Following the aclark example, the
base-distinguished names for users and groups are as follows:
# People, aclark.net dn: ou=People,dc=aclark,dc=net ou: People objectClass: organizationalUnit # Group, aclark.net dn: ou=Group,dc=aclark,dc=net ou: Group objectClass: organizationalUnit
This means that we will configure the
ou=People,dc=aclark,dc=net and
ou=Group,dc=aclark,dc=net base-distinguished names for
users and groups, respectively.
We will leave the default settings for scope, since we are not particularly concerned with whether or not the sub-objects are searched. If you like, you can try the one-level setting, which should work equally well in this case.
At this point, it may be necessary to restart Plone in order to force a reconnection with the LDAP server.
Alternatively, you could browse to http://localhost:8080/Plone and click on Site Setup | Add-on
Product Configuration | LDAP
Connection | LDAP
Servers.
You should see:
Check the box next to the server, and click on Disable. Then check the box next to the server and click on Enable.
At this point, you should be able to see LDAP users in Plone.
If you browse to http://localhost:8080/Plone and click
on Site Setup |
Users and Groups | Show all,
you should be able to see your LDAP users (or aclark in the
case of our example):
This user can log in to Plone as a member (user with Member role).
To configure LDAP users to be administrators, you could add them to the (ZODB-only) Administrators group in Plone (like we did earlier in this chapter).
Alternatively, you could create a group in LDAP, assign it the Manager role, and add users to that group.
The most straightforward way to do this is to browse to
http://localhost:8080/Plone, click on
Site Setup | Zope Management
Interface | acl_users
| ldap-plugin | Contents |
acl_users |
Groups.
You should see:
Here, you can add a group, for example MyGroup, and map it to the Manager role. You should see the following:
That is all for this chapter. Nice job following along!
You have learned:
How to configure mail settings in a development environment
How to configure users and groups with the out of the box feature set
How to configure users and groups with LDAP
Join me again in Chapter 5, where we will discuss maintenance topics such as database packing and how to back up your database. More importantly, we will discuss how to automate these tasks in production.