README for the Zope LDAPLoginAdapter Product This product is a replacement for a Zope user folder. It does not store its own user objects but builds them on the fly after authenticating a user against the LDAP database. The nature of the LDAPLoginAdapter is "read-only", meaning at present it does not allow you to create, edit or delete users in LDAP. You will need to populate the LDAP directory by other means. **How to upgrade** Upgrading entails not only unpacking the new code, you should also delete and recreate all LDAPLoginAdapter instances in your Zope installation. **Custom login page** Check out the code in the LDAPLoginAdapter install directory under dtml/login.dtml for what a login page has to do. You want to make sure that you have a *form* which posts at least 2 input fields named *__ac__name* (user name) and *__ac_password* (password) back. You can make your custom page the default page by simply instantiating it under the "Contents" tab of the LDAPLoginAdapter and giving it an id of *login*. **Limited non-ASCII character support** If your version of python is unicode-enabled (versions after 1.6) the product will now let you use the full Latin-1 character set within LDAP attribute values and handle them correctly. The exception to this rule is the Distinguished Name (DN) of a record and all its elements. This means the attribute you chose as RDN-attribute (cn or uid) must contain only ASCII- characters, as well as all other attributes that are contained in the DN, such as ou or o or dc etc. **Note**: The UTF-8 encoding will not work with OpenLDAP 1.x **Help, I locked myself out of my own site!** This can happen if you create a custom login page within the LDAPLoginAdapter which does not do the right thing and the authentication method is set to use cookies. In order to authenticate you can force the usage of the default login page by going to: http://my.site.com/acl_users/default_loginpage Type in your name and password and hit the button. You will stay on the same page, even if the authentication succeeded, you can then type the desired address into your browser's navigation bar. **Why use LDAP to store user records?** LDAP as a source of Zope user records is an excellent choice in many cases, like... o You already have an existing LDAP setup that might store company employee data and you do not want to duplicate any data into a Zope user folder o You want to make the same user database available to other applications like mail, address book clients, operating system authenticators (PAM-LDAP) or other network services that allow authentication against LDAP o You have several Zope installations that need to share user records or a ZEO setup o You want to be able to store more than just user name and password in your Zope user folder o You want to manipulate user data outside of Zope ... the list continues. **Requirements** In order for this product to run you will need to provide the following items: * a working LDAP server (see http://www.openldap.org/) * the python-ldap module (see http://python-ldap.sourceforge.net/) **Tested Platforms** This version of the LDAPLoginAdapter has been written on and for Zope 2.3.0 and up. I am not going to support earlier versionds of Zope with my product. If you are looking for a similar solution for a pre-2.3.0-site see http://sourceforge.net/projects/zldapadapter/ for the LDAPAdapter. The LDAPAdapter, written by Ross Lazarus and Soren Roug, formed the basis for the LDAPLoginAdapter. This product is platform-independent except for its reliance on the python-ldap module. If you cannot compile or find a python- ldap module suitable for your platform the LDAPLoginAdapter will not work. **The LDAP Schema** Your LDAP server should contain records that can be used as user records. Any object types like person, organizationalPerson, or inetOrgPerson and any derivatives thereof should work. After a small code change records of type posixAccount should work correctly as well. The LDAPLoginAdapter expects your user records to have at least the following attributes, most of which are required for the abovementioned object classes, anyway: * cn (Canonical Name) * userPassword (the password field) * objectClass * whatever attribute you choose as the username attribute * typcial person-related attributes like sn (last name), givenName (first name), uid or mail (email address) will make working with the LDAPLoginAdapter nicer Zope users have certain roles associated with them, these roles determine what permissions the user have. In LDAPLoginAdapter-speak, roles are embodied in Groups. Group records can be of any object type that accepts multiple attributes of type "uniqueMember" and that has a "cn" attribute. One such type is "groupOfUniqueNames". The cn describes the group / role name while the uniqueMember attributes point back to all those user records that are part of this group. For examples of valid group- and user-records for LDAP please see the file SAMPLE_RECORDS.txt in this distribution. It has samples for a user- and a group record in LDIF format. It is outside of the scope of this documentation to describe the different object classes and attributes in detail, please see LDAP documentation for a better treatment. **Things to watch out for** Since a user folder is one of these items that can lock users out of your site if they break I suggest testing the settings in some inconspicuous location before replacing a site's main acl_users folder with a LDAPLoginAdapter. As a last resort you will always be able to log in and make changes as the superuser (or in newer Zope releases called "emergency user") who, as an added bonus, can delete and create user folders. This is a breach of the standard "the superuser cannot create / own anything" policy, but can save your skin in so many ways.