Unenlightened Zopistas Guide to exUserFolder

The Unenlightened Zopistas Guide to exUserFolder. (C) 2001-2003 Andrew Milton

1. INTRODUCTION.

exUserFolder is an extensible authentication product for the Zope Application Server. It allows a user to choose from a number of methods of authenticating their users, and allows the setting and fetching of arbitrary properties on a User object.

Authentication methods, and Property methods do not have to use the same backing store, so it is possible to use legacy user sources, and still have configuration information stored about a user.

exUserFolder supports HTTP Basic Authentication, and the so called Cookie Authentication schemes popular with most webservers.

1. 1 Audience.

Everybody, and Nobody. If we build our product correctly, we shouldn't need user documentation, that's why Nobody. For some reason, normal sane people seem to lose all of their common sense when sitting in front of a computer. To the point where plain messages e.g. "Please Insert a Floppy", evoke a response of "What does that mean?" So that's why this document is for Everybody.

This is not a guide for writing your own authentication, property, or membership sources. You need the Zen Masters Guide to exUserFolder document for that.

1. GETTING STARTED

exUserFolder requires Python 2.1 or above (may work with older pythons, but, this is not supported). And has been tested on Zope 2.3.0 and above (including 2.4.3).

exUserFolder comes as a source tarball, and it does not rely on any outside dependencies to be work. Some items may require additional products to be installed in your Zope tree, but, simply will not appear if these are not available. Some items may also require external products to add functionality to them, but, at no time should the Product not install because of these dependencies.

1. 1 Installing exUserFolder.

Unpack exUserFolder in your Products directory. This can be achieved by executing the following on most UNIX systems.

gzip -d -c exUserFolder-Ma_Mi_u.tgz | tar xvf -

where exUserFolder-Ma_Mi_u.tgz is the version of exUserFolder you have downloaded.

On systems that have the GNU tar this can be shortened to;

tar zxvf exUserFolder-Ma_Mi_u.tgz

You should restart Zope after unpacking. Installing the product will not affect your Zope installation in anyway.

If you go to Folder inside your Zope Management Interface, you should see exUserFolder as a dropdown item near the bottom somewhere.

Congratulations, it's installed.

1. AUTHENTICATION SOURCES AND YOU.

The only mandatory component of an exUserFolder installation, is choosing an Authentication Source. There are six Authentication Sources to choose from in the default install. There are other add-on Sources available from other parties.

Each Authentication Source is different, and assumes at least some knowledge of that type of authentication scheme.

Most if not all sources store the password encrypted in some manner. This means that discovering other people's passwords is going to be more difficult, than with the standard user folder that comes with Zope.

By default crypt or fcrypt are used, which is are DES encryption methods. While this is not the strongest, fastest, choose another superlative, of encryption techniques, it is certainly adequate for protecting webpages.

In a later release exUserFolder will allow you to choose what method is used for password hashing.

Some Authentication Sources can list the users that are available, some cannot (or will not). Some allow you to add users, and others do not. What features are availble depend on the individual Authentication Source.

1. 1 ZODB Authentication Source

The ZODB Authentication Source operates just like a normal User Folder. It stores its authentication items in the ZODB as the name suggests. This is the simplest folder to setup, requiring no parameters.

Choosing ZODB Authentication Source is recommended for testing your install.

1. 2 File Based Authentication.

File Based Authentication allows you to have a fixed set of users in a file with their encrypted passwords. The prerequisites for this are somewhat convoluted.

In the root of your Zope Installation, on the actual file system (not in the ZODB), create a directory called exUsers. Make sure that Zope has access to that directory.

This is the directory where you will create your files.

This is a read only Authentication Source. You will not be able to create users, or modify their passwords. You can change their roles if you choose a Property Source.

There are two parameters asked for;

1. 2.1 Password File

This is the name of the file that contains your users and passwords. It should be of the format;

username:cryptedPassword user2:otherCryptedPasswd

I can contain other fields after the password also delimited by : but these will not be ussed.

This file should exist inside the exUsers directory.

1. 2.2 Default Role

This is the role that all users should be given when the log in. Because this is a Read Only authentication source, you may not be able to add Roles at a later date.

1. 3 Postgresql Authentication Source

Postgresql Authentication source is an RDBMS backed user store. You can add, change, and list users. It requires a Postgresql Database Connection to be created before creating the User Folder.

You should be familiar with databases, and with your schema before using this Authentication Source. If you don't already have a table structure in place, a default schema is provided called pgScheme.sql in the exUserFolder distribution.

The required schema is very simple. You need to store usernames, passwords, and roles. If your existing schema doesn't support a roles column you will have to add one.

The configuration scheme looks daunting, but, it is setup to use the defaults for pgScheme.sql so if you're using this you can safely continue.

We will run through the items.

1. 3.1 Database Connection

If you have any database connections, they will be listed in the drop down box. Choose the one that represents your connection to your users table.

1. 3.2 Table Name

This is the name of the table containing your users. If you have a different table to the default, you should change it here.

1. 3.3 Username Column

This is the name of the column inside your table that contains the usernames or logins of your users. This should contain exactly what the user needs to type in as their username.

1. 3.4 Password Column

This is the name of the column inside your table that contains the encrypted passwords of your users.

1. 3.5 Roles Column

This is where the roles are stored. These are used to provide access to items in Zope.

1. 4 User Supplied Authentication Source

This allows you to create your methods in DTML, PythonScripts, External Methods, or any other callable Zope item for listing, authenticating, adding and changing your users.

It is beyond the scope of this guide to describe how to do this, but, the API is quite well defined inside the source, and also in the README.API document.

This Authentication Source has no configuration parameters.

1. 5 RADIUS Authentication Source

This allows you to authenticate your users against a RADIUS server. If you don't know what this means, then this User Source is not for you :-)

You will require a RADIUS server to be operating, and for the server that Zope is running on to have access to it. You will also need to know the secret key to access the RADIUS server.

1. 5.1 Host

This is the host your RADIUS server is running on.

1. 5.2 Port

This is the port your RADIUS server is running on. Older installs may require this to be 1645. The new blessed port by IANA is 1812, and this is now the default port.

1. 5.3 Secret

Every remote host has a secret key it has to share with the server in order to gain access to the authentication server. You need to know this.

1. 5.4 Retries

Because this is a networked authentication service, errors can occur. This sets the number of times it will try to authenticate before giving up.

1. 5.5 Timeout

This is how long the RADIUS authenticator will wait for a response. Because RADIUS operates over UDP, which is a connectionless protocol, answers may never come back, or never reach their destination in the first place.

The default is 5 seconds which is actually quite a long time.

1. 6 SMB Authentication Source

This source allows you to authenticate your users in a Microsoft Environment, using the SMB protocols. This is not the same as authenticating via Directory Services.

If your SMB server requires passwords to be encrypted in transit, you'll need to install mxCrypto.

1. 6.1 Host

This is the host that your Authentication service is on, this is normally an NT or Win2K server, but, it can also be a UNIX box running Samba. This should be the NetBIOS name of the server.

1. 6.2 Domain

This is the NT/Windows DOMAIN that the user is to authenticate against.

1. 6.3 WINS Server IP Address (optional)

If provided, this should be the IP address of the WINS server to be queried to locate your auth host (see 2.5.1 above).

If you leave this field empty, the location of the authentication host will be queried by broadcast, which works just fine if the Zope machine is on the same subnet as your auth host but not if the auth host is across a subnet link or if it's in the same machine as Zope (don't ask. Apparently, some braindmamaged creature at M$ decided that a machine shouldn't answer to its own broadcasts no matter what)

Fill in this field if you are getting "NetBIOSTimeout" errors but you are sure that your auth host was specified correctly, or if Windows machines in your subnet also use a WINS server.

1. 7 LDAP Authentication

This source allows you to authenticate your users against an LDAP server. This code is based on the auth_ldap module for Apache. The documentation for these parameters is unashamedly lifted directly from the documentation of the Apache directives for auth_ldap.

See: http://www.rudedog.org/auth_ldap/

You must choose a property source when using LDAP Authentication, all of the properties associated with the LDAP user entry are stored as properties when they authenticate. Items with multiple entries are stored as a list of items.

1. 7.1 URL

An RFC 2255 URL which specifies the LDAP search parameters to use. The syntax of the URL is ldap://host:port/basedn?attribute?scope?filter

ldap For regular ldap, use the string ldap. For secure LDAP, use ldaps instead. Secure LDAP is only available if auth_ldap was compiled with SSL support. host:port The name/port of the ldap server (defaults to localhost:389 for ldap, and localhost:636 for ldaps).

Once a connection has been made to a server, that connection remains active for the life of the Zope process, or until the LDAP server goes down.

If the LDAP server goes down and breaks an existing connection, the Auth Source will attempt to re-connect

basedn The DN of the branch of the directory where all searches should start from. At the very least, this must be the top of your directory tree, but could also specify a subtree in the directory.

attribute The attribute to search for. Although RFC 2255 allows a comma-separated list of attributes, only the first attribute will be used, no matter how many are provided. If no attributes are provided, the default is to use uid. It's a good idea to choose an attribute that will be unique across all entries in the subtree you will be using.

scope The scope of the search. Can be either one or sub. Note that a scope of base is also supported by RFC 2255, but is not supported by this module. If the scope is not provided, or if base scope is specified, the default is to use a scope of sub.

filter A valid LDAP search filter. If not provided, defaults to (objectClass =*), which will search for all objects in the tree.

When doing searches, the attribute, filter and username passed by the HTTP client are combined to create a search filter that looks like (&(filter) (attribute=username)).

For example, consider an URL of ldap://ldap.xuf.com/o=XUF?cn?sub?(posixid =). When a client attempts to connect using a username of The Jester, the resulting search filter will be (&(posixid=)(cn=The Jester)).

1. 7.2 Bind DN

An optional Distinguished Name user to bind to the server when searching for entries. If not provided an Anonymous bind will be used.

1. 7.3 Bind Password. A bind password to use in conjunction with the bind DN. Note that the bind password is probably sensitive data, and should be properly protected. You should only use the Bind DN and Bind Password if you absolutely need them to search the directory.
2. 7.4 Cert DB Path

Specifies in which directory LDAP Auth Source should look for the certificate authorities database. There should be a file named cert7.db in that directory.

1. 7.5 Compare DN On Server

When set, LDAP Auth Source will use the LDAP server to compare the DNs. This is the only foolproof way to compare DNs. LDAP Auth Source will search the directory for the DN specified with the require dn directive, then, retrieve the DN and compare it with the DN retrieved from the user entry. If this directive is not set, LDAP Auth Source simply does a string comparison. It is possible to get false negatives with this approach, but it is much faster. Note the LDAP Auth Source cache can speed up DN comparison in most situations.

1. 7.6 Dereference Aliases

This directive specifies when LDAP Auth Source will de-reference aliases during LDAP operations. The default is always.

1. 7.7 Group Attribute is DN

When set, this directive says to use the distinguished name of the client username when checking for group membership. Otherwise, the username will be used. For example, assume that the client sent the username tjester, which corresponds to the LDAP DN cn=The Jester, o=XUF. If this directive is set, LDAP Auth Source will check if the group has cn=The Jester, o=XUF as a member. If this directive is not set, then LDAP Auth Source will check if the group has tjester as a member.

1. 7.8 Compare Cache Size

This specifies the size of the cache used to cache LDAP compare operations. The default is 1024 entries. Setting it to 0 disables operation caching.

1. 7.9 Compare Cache TTL

Specifies the time (in seconds) that entries in the operation cache remain valid. The default is 600 seconds.

1. 7.10 Start TLS

If this is set to Yes, LDAP Auth Source will start a secure TLS session after connecting to the LDAP server. This requires your LDAP server to support TLS.

1. 7.11 Require User (one per line)

The require user directive specifies what usernames can access the resource. Once LDAP Auth Source has retrieved a unique DN from the directory, it does an LDAP compare operation using the username specified in the require user to see if that username is part of the just-fetched LDAP entry. Multiple users can be granted access by putting multiple usernames in the box, separated with newlines. For example, with a AuthLDAPURL of ldap://ldap/o=XUF?cn (i.e., cn is used for searches), the following require entries could be used to restrict access: The Jester Fred User Joe Manager

Because of the way that LDAP Auth Source handles this directive, The Jester could sign on as The Jester, Zen Jester or any other cn that he has in his LDAP entry. Only the single require user line is needed to support all values of the attribute in the user's entry.

If the uid attribute was used instead of the cn attribute in the URL above, the above three lines could be;

tj fred_u jmanager

1. 7.12 Require Group (one per line)

This directive specifies an LDAP group whose members are allowed access. It takes the distinguished name of the LDAP group. For example, assume that the following entry existed in the LDAP directory:

dn: cn=Administrators, o=XUF objectClass: groupOfUniqueNames uniqueMember: cn=The Jester, o=XUF uniqueMember: cn=Fred User, o=XUF

The following directive would grant access to both Fred and Jester:

require group cn=Administrators, o=XUF

Behavior of this directive is modified by the Group Attribute and Group Attribute Is DN options.

1. 7.13 Require DN

The require dn option allows the administrator to grant access based on distinguished names. It specifies a DN that must match for access to be granted. If the distinguished name that was retrieved from the directory server matches the distinguished name in the require dn, then authorization is granted.

The following directive would grant access to a specific DN: require dn cn=The Jester, o=XUF

Behavior of this directive is modified by the Compare DN On Server option.

1. 7.14 Default Manager

This allows you to specify the username of the Manager for this area. The manager will still need to meet auth requirements above, but, if they do they will get the Manager role added to their list of roles.

1. 7.15 Default Role

This is a role to be assigned to users when they auth correctly. This is to differentiate them from merely being authenticated.

1. 7.16 Examples
   • Grant access to anyone who exists in the LDAP directory, using their UID for searches. URL ldap://ldap1.zope.com:389/ou=People, o=XUF?uid?sub?(objectClass=*)
   • The next example is similar to the previous one, but is uses the common name instead of the UID. Note that this could be problematical if multiple people in the directory share the same cn, because a search on cn must return exactly one entry. That's why this approach is not recommended: it's a better idea to choose an attribute that is guaranteed unique in your directory, such as uid. URL ldap://ldap.zope.com/ou=People, o=XUF?cn
   • Grant access to anybody in the Administrators group. The users must authenticate using their UID. URL ldap://ldap.zope.com/o=XUF?uid require group: cn=Administrators, o=XUF
   • The next example assumes that everyone at XUF who carries an alphanumeric pager will have an LDAP attribute of qpagePagerID. The example will grant access only to people (authenticated via their UID) who have alphanumeric pagers: URL: ldap://ldap.zope.com/o=XUF?uid??(qpagePagerID=*)
   • The next example demonstrates the power of using filters to accomplish complicated administrative requirements. Without filters, it would have been necessary to create a new LDAP group and ensure that the group's members remain synchronized with the pager users. This becomes trivial with filters. The goal is to grant access to anyone who has a filter, plus grant access to Joe Manager, who doesn't have a pager, but does need to access the same resource: URL ldap://ldap.zope.com/o=XUF?uid??(|(qpagePagerID=*)(uid=jmanager))

     This last may look confusing at first, so it helps to evaluate what the search filter will look like based on who connects, as shown below. If Fred User connects as fuser, the filter would look like

     (&(|(qpagePagerID=*)(uid=jmanager))(uid=fuser))

     The above search will only succeed if fuser has a pager. When Joe Manager connects as jmanager, the filter looks like

     (&(|(qpagePagerID=*)(uid=jmanager))(uid=jmanager))

     The above search will succeed whether jmanager has a pager or not.

2. 8 General Items.

You can choose to use standard auth, or cookie auth, and you can decide how long you want to cache the users credentials before retrying.

1. 8.1 Authentication Type
2. 8.1.1 Standard Authentication

This method causes the browser to pop up a dialog box to ask for the username and password.

1. 8.1.2 Cookie Authentication

This method allows you to use a normal HTML form to get the username and password from the user. It also will present the default form to the user if they try to access an unauthorised area.

1. 8.1.3 Secure Cookie based Authentication

This method, like Cookie Authentication allows you to use a HTML form to get the user details. However, the cookie it uses does not contain any login information. It is internally checked against a cache of hashes and the information is derived from that. This cache disappears if you restart Zope, so this is not a good option for people who want to persistently cache logins across sessions.

1. 8.2 Credential Cache Timeout in Seconds

exUserFolder by default caches credential information, so that the authorisation source isn't hit for every object and page that has to be fetched. For remote authentication services this can slow things down quite considerably. Even setting this to a modest setting will quicken response times.

Setting this too long could cause problems if you want to lock out a troublesome user. The credential cache is flushed if someone provides a password that doesn't match the one in the cache.

1. 8.3 Negative Credential Cache Timeout in Seconds

exUserFolder allows you to cache login failures for users that do not exist. This means you don't have to go out to your auth source when you know for certain this user is never going to be able to authenticate.

Due to the way some auth sources are designed, this doesn't work for auth sources like SMB Auth Source that lie initially about the user existing (because you can't verify the existence of a user without authenticating them), and then check the credentials later.

It's possible to create a hybrid auth source that lets this work correctly for auth sources that can't list the users.

1. 8.4 Log out users who expire from cache?

If you've got caching turned on, then this will force any user who has their session expire to login again. Some people like to do this.

1. 8.5 Activate Session Tracking for anoymous users?

For any anonymous user, a new temporary user is created. This allows you to set/get properties for anonymous users too. Currently experimental.

1. 0 PROPERTY SOURCES
2. 0 MEMBERSHIP SOURCES
3. 0 TIPS FOR THE UNWARY

Generally these things apply to Cookie Authentication models, since there is additional access required to present the login form.

1. 1 Too much protection.

A lot of people try to protect a folder by placing an exUserFolder inside. They then change the permissions on this folder to only allow Authenticated or some Local Role to have permission.

1. 1.1 The problem

When you try to access the folder, instead of getting the form, you get a popup box, even though you chose Cookie Authentication. Even when you enter a username and password it doesn't work.

1. 1.2 What happened

You tried to access an area you don't have access to. Zope found the closest user folder to the object you were trying to access. The user folder decided you were not authorised and tried to display the login form. You don't have access to view the login form, so Zope finds the nearest user folder to the login form, which is the user folder above the protected directory. It pops up the authentication dialog. If you put in a valid username and password for this top level, then lower level then displays the login form.

1. 1.3 Solution 1 (preferred).

Place the user folder one level above the folder you want to protect, that is in the unprotected area. Everything should work fine.

1. 1.4. Solution 2 (not so preferred).

Set the View permission on the docLogin form inside the acl_users folder. You can get there by Choosing Contents on docLogin and scrolling down to the bottom.

1. 0 MISCELLANY
2. 1 Adding an exUserFolder from a product.

You can add an exUserFolder from a Python product fairly easily, if not a tad messily.

from Products.exUserFolder.exUserFolder import manage_addexUserFolder, eUserFolder

manage_addexUserFolder(authId=zodbAuthSource, propId=zodbPropSource, memberId=basicMemberSource, cookie_mode=1, session_length=600, REQUEST)

Obviously change authId, propId, and memberId to what you want. However, you'll need to ram in the appropriate form fields for the various source constructors into your REQUEST.

1. 2 Session Tracking.

Session tracking (currently) relies on having the credential cache active, and a property source active. Your trackable user will only last as long as they are not expired from the cache. You should set the cache expiry length to be somewhat longer than normal if you plan to use Session Tracking, and you should also be prepared to check that the current session is valid.