LDAP User Preferences Backend ============================= SquirrelMail LDAP Prefs Backend Plugin (ldap_prefs_backend) By Daniel Marczisovszky Based on db_prefs.php and ldapuserdata by Alexandros Vellis; Copyright (c) 2005-2006 Daniel Marczisovszky Licensed under the GNU GPL. For full terms see the file COPYING that came with the Squirrelmail distribution. Requires at least SquirrelMail 1.4.3 1. Description =============== LDAP prefs backend is a generic solution to store SquirrelMail preferences in an LDAP directory. There is little utility (convert_pref.php) that may help to convert your file based preferences to LDIF format. 2. Configuration ================ To set up ldap_prefs_backend, you should edit config.php. A sample configuration can be found in config_sample.php. Copy or rename this file to config.php before using this plugin! The following parameters can be set: Parameter name Meaning $ldapPrefDebug Enable/disable debug log. The log file should be specified in ldap_common plugin. $ldapPrefHost LDAP server's host Example: localhost $ldapPrefOptions Array of LDAP settings applied just after LDAP connect has finished successfully. See ldap_set_option for details in PHP doc. Note that constants should be specified as strings. Example: array("LDAP_OPT_PROTOCOL_VERSION" => 3); $ldapPrefUseTls Enable START_TLS. Requires protocol V3. $ldapPrefUseSelfAuth Bind as a manager account, or bind as the found mail account's DN and current user's password. If set to true, then the plugin will search the user's DN using the $ldapPrefUserFilter. After that it binds to the LDAP server with this DN and the password used for login into SquirrelMail. If set to false, then the plugin will bind as $ldapPrefUser (see below) with password as $ldapPrefPassword. In this case this user should have enough privileges to modify the virtual mail account objects. $ldapPrefBindDn DN of the manager account if $ldapPrefUseSelfAuth is true. Example: cn=squirrel,dc=dev-labs,dc=com $ldapPrefBindPassword Password for the user above. Example: secret $ldapPrefBase Base DN for searching mail accounts Example: ou=virtMail, dc=dev-labs, dc=com $ldapPrefFilter Filter used to search the mail account under $ldapPrefBase The %username will be replaced by the username given at login time. Example: (mail=%username) $ldapPrefAttrName Name of attribute used to store preferences. Example: sqPref. $ldapPrefAuxObjectClass If your mail account's class does not have the $ldapPrefObjectAttr (sqPref), then you should set the name of an auxiliary object class that contains the $ldapPrefObjectAttr (sqPref) attribute. The name of this class will be added to the "objectClass" attribute of every mail account object. See below for details. 3. Schema and Security ====================== Depending on configuration and your needs, different scenarios are available to access the LDAP server. However, it very important to set up proper ACLs to avoid unauthorized access. On one hand, it may be useful to use a dedicated user that has only those privileges that is required by the plugin, but this way the password of this dedicated user has to be stored in config.php, which may be a security risk. On the other hand, it is possible to give these privileges to the user, but in this way it has to be restricted when LDAP is being accessed from localhost or that IP address where SqiurrelMail runs. ACL examples can be found in the SECURITY file. Available scenarios are results of combination of the following parameters: I. Which user has access to attributes holding perferences values: - Dedicated user: a dedicated user should be added to the LDAP tree and this user should have access to those attributes that the plugin uses. Use $ldapPrefBindDn and $ldapPrefBindPassword and set $ldapPrefUseSelfAuth to false. - The user has appropriate rights to modify his/her object. The plugin will search the user's DN and use that DN to bind to LDAP. Use $ldapPrefBase and $ldapPrefFilter for this query and set $ldapPrefUseSelfAuth to true. II. Which objectClass contains the attribute holding preferences values: By the default, the name of this attribute is sqPref, but it may be changed using the $ldapPrefAttrName parameter. - The objectClass used for user accounts already contains this attribute. If you use your own objectClass for user account, you may choose this method. Set $ldapPrefAuxObjectClass to empty. In your schema you should add the name of this attribute to the MAY section. Example: objectclass ( 1.3.6.1.4.1.13788.1.2.1 NAME 'mailAccount' SUP top STRUCTURAL MUST ( mail $ userPassword ) MAY ( mailalt $ homeDirectory $ sqPref $ description ) ) dn: mail=marczi@dev-labs.com, domain=dev-labs.com, ou=virtualMail, dc=dev-labs, dc=com objectClass: top objectClass: mailAccount userPassword: secret mail: marczi@dev-labs.com homeDirectory: /home/marczi sqPref: javascript_on=1 sqPref: chosen_theme=../themes/bluesteel_theme.php - An auxiliary objectClass is used to allow storing preferences attributes in user account objects. If user account objects are created by using a standard objectClass (example: qmailUser, courierMailAccount), which you don't want to or can't modify, then the name of an auxiliary objectClass is added to user account objects before adding preferences attributes to them. Set $ldapPrefAuxObjectClass to the name of the auxiliary objectClass. By default this objectClass is sqAccount. Example: objectclass ( 1.3.6.1.4.1.13788.3.2.1 NAME 'sqAccount' SUP top AUXILIARY MAY ( sqPref ) ) dn: mail=marczi@dev-labs.com, domain=dev-labs.com, ou=virtualMail, dc=dev-labs, dc=com objectClass: top objectClass: courierMailAccount objectClass: sqAccount userPassword: secret mail: marczi@dev-labs.com homeDirectory: /home/marczi sqPref: javascript_on=1 sqPref: chosen_theme=../themes/bluesteel_theme.php (note that compared to the previous example, the entry now has the "objectClass: sqAccount" line, since courierMailAccount does not have the sqPref attribute.) 4. Character encoding ===================== It is higly recommended to use LDAPv3 protocol if users use languages other than English. The only proper way to store international characters in LDAP is to use UTF-8. The plugin will convert to UTF-8 when writing to LDAP server and will convert back to that character set which corresponds to the current user's language setting. However, UTF-8 works only when LDAP protocol V3 is used, so the default config.php has LDAPv3 enabled. Although many of SquirrelMail settings contain only English characters and numbers, many settings that belong to plugins and signatures can still contain non-English characters. 5. Logging ========== When the plugin is first used, it may be very useful to see what happens in the background. It helps to find out misspells in config.php or insufficient ACLs. Set $ldapPrefDebug to true to enable debug log. However, the log file should be specified in ldap_common plugin's config.php. It is recommended to enable debug log for LDAP Common plugin as well, since that will log low-level LDAP operations. Note that log file will contain unencrypted passwords, so don't use it in a production environment.