diff -r cd9fddc21361 -r 1771d4b0fa0d doc/book/en/admin/ldap.rst --- a/doc/book/en/admin/ldap.rst Fri Jan 18 18:31:25 2013 +0100 +++ b/doc/book/en/admin/ldap.rst Wed Jan 09 14:27:51 2013 +0100 @@ -12,49 +12,55 @@ At cube creation time, one is asked if more sources are wanted. LDAP is one possible option at this time. Of course, it is always possible -to set it up later in the `source` configuration file, which we -discuss there. +to set it up later using the `CWSource` entity type, which we discuss +there. It is possible to add as many LDAP sources as wanted, which translates -in as many [ldapxxx] sections in the `source` configuration file. +in as many `CWSource` entities as needed. The general principle of the LDAP source is, given a proper configuration, to create local users matching the users available in -the directory, deriving local user attributes from directory users +the directory and deriving local user attributes from directory users attributes. Then a periodic task ensures local user information synchronization with the directory. +Users handled by such a source should not be edited directly from +within the application instance itself. Rather, updates should happen +at the LDAP server level. + Credential checks are _always_ done against the LDAP server. -The base functionality for this is in -:file:`cubicweb/server/sources/ldapuser.py`. +.. Note:: -External dependencies ---------------------- - -You'll need the following packages to make CubicWeb interact with your LDAP / -Active Directory server: + There are currently two ldap source types: the older `ldapuser` and + the newer `ldapfeed`. The older will be deprecated anytime soon, as + the newer has now gained all the features of the old and does not + suffer from some of its illnesses. -* python-ldap -* ldaputils if using `ldapfeed` source + The ldapfeed creates real `CWUser` entities, and then + activate/deactivate them depending on their presence/absence in the + corresponding LDAP source. Their attribute and state + (activated/deactivated) are hence managed by the source mechanism; + they should not be altered by other means (as such alterations may + be overridden in some subsequent source synchronisation). -Configurations options ----------------------- -Let us enumerate the options (but please keep in mind that the -authoritative source for these is in the aforementioned python -module), by categories (LDAP server connection, LDAP schema mapping -information, LDAP source internal configuration). +Configurations options of an LDAPfeed source +-------------------------------------------- + +Let us enumerate the options by categories (LDAP server connection, +LDAP schema mapping information). LDAP server connection options: -* `host`, may contain port information using : notation. -* `protocol`, choices are ldap, ldaps, ldapi * `auth-mode`, (choices are simple, cram_md5, digest_md5, gssapi, support for the later being partial as of now) + * `auth-realm`, realm to use when using gssapi/kerberos authentication + * `data-cnx-dn`, user dn to use to open data connection to the ldap (eg used to respond to rql queries) + * `data-cnx-password`, password to use to open data connection to the ldap (eg used to respond to rql queries) @@ -62,21 +68,29 @@ leave data-cnx-dn and data-cnx-password empty. This is, however, quite unlikely in practice. -LDAP schema mapping: +LDAP schema mapping options: * `user-base-dn`, base DN to lookup for users -* `user-scope`, user search scope -* `user-classes`, classes of user -* `user-attrs-map`, map from ldap user attributes to cubicweb attributes -* `user-login-attr`, attribute used as login on authentication + +* `user-scope`, user search scope (valid values: "BASE", "ONELEVEL", + "SUBTREE") -LDAP source internal configuration: +* `user-classes`, classes of user (with Active Directory, you want to + say "user" here) + +* `user-filter`, additional filters to be set in the ldap query to + find valid users + +* `user-login-attr`, attribute used as login on authentication (with + Active Directory, you want to use "sAMAccountName" here) * `user-default-group`, name of a group in which ldap users will be by default. You can set multiple groups by separating them by a comma -* `synchronization-interval`, interval between synchronization with the - ldap directory in seconds (default to once a day) -* `cache-life-time`, life time of query cache in minutes (default to two hours). + +* `user-attrs-map`, map from ldap user attributes to cubicweb + attributes (with Active Directory, you want to use + sAMAccountName:login,mail:email,givenName:firstname,sn:surname) + Other notes ----------- @@ -87,14 +101,13 @@ authenticated but their status will not change (e.g. they will not be deactivated) -* Changing the name of the ldap server in your script is fine, changing the base - DN isn't since it's used to identify already known users from others +* The user-base-dn is a key that helps cubicweb map CWUsers to LDAP + users: beware updating it * When a user is removed from an LDAP source, it is deactivated in the CubicWeb instance; when a deactivated user comes back in the LDAP source, it (automatically) is activated again - * You can use the :class:`CWSourceHostConfig` to have variants for a source configuration according to the host the instance is running on. To do so go on the source's view from the sources management view.