The Unenlightened Zopistas Guide to exUserFolder.
(C) 2001 Andrew Milton <akm@theinternet.com.au>

0. 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.

0.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.


2. 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.


2.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.


2.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;

2.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.

2.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.


2.2 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.

2.2.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.

2.2.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.

2.2.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.


2.2.4 Password Column

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


2.2.5 Roles Column

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


2.3 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.


2.4 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.

2.4.1 Host

This is the host your RADIUS server is running on.

2.4.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.

2.4.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.

2.4.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.

2.4.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.


2.5 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.

2.5.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.

2.5.2 Domain

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

2.5.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.

2.6 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.

2.6.1 Authentication Type

2.6.1.1 Standard Authentication

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

2.6.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.

2.6.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.

3.0 PROPERTY SOURCES

4.0 MEMBERSHIP SOURCES

5.0 TIPS FOR THE UNWARY

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

5.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.

5.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.


5.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.

5.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.

5.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.

6.0 MISCELLANY

6.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.

6.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.
