diff -r 76ab3c71aff2 -r c67bcee93248 doc/book/en/admin/ldap.rst --- a/doc/book/en/admin/ldap.rst Mon Jul 06 17:39:35 2015 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,134 +0,0 @@ -.. _LDAP: - -LDAP integration -================ - -Overview --------- - -Using LDAP as a source for user credentials and information is quite -easy. The most difficult part lies in building an LDAP schema or -using an existing one. - -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 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 `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 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. - -.. Note:: - - 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. - - 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). - - -Configuration of an LDAPfeed source ------------------------------------ - -Additional sources are created at cube creation time or later through the -user interface. - -Configure an `ldapfeed` source from the user interface under `Manage` then -`data sources`: - -* At this point `type` has been set to `ldapfeed`. - -* The `parser` attribute shall be set to `ldapfeed`. - -* The `url` attribute shall be set to an URL such as ldap://ldapserver.domain/. - -* The `configuration` attribute contains many options. They are described in - detail in the next paragraph. - - -Options of an LDAPfeed source ------------------------------ - -Let us enumerate the options by categories (LDAP server connection, -LDAP schema mapping information). - -LDAP server connection options: - -* `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) - -If the LDAP server accepts anonymous binds, then it is possible to -leave data-cnx-dn and data-cnx-password empty. This is, however, quite -unlikely in practice. Beware that the LDAP server might hide attributes -such as "userPassword" while the rest of the attributes remain visible -through an anonymous binding. - -LDAP schema mapping options: - -* `user-base-dn`, base DN to lookup for users - -* `user-scope`, user search scope (valid values: "BASE", "ONELEVEL", - "SUBTREE") - -* `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 - -* `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 ------------ - -* Cubicweb is able to start if ldap cannot be reached, even on - cubicweb-ctl start ... If some source ldap server cannot be used - while an instance is running, the corresponding users won't be - authenticated but their status will not change (e.g. they will not - be deactivated) - -* 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.