doc/book/admin/ldap.rst
changeset 10491 c67bcee93248
parent 9551 cbc46f94081d
child 12534 e0e7d8ca051f
child 12904 2ad148f22c2f
equal deleted inserted replaced
10490:76ab3c71aff2 10491:c67bcee93248
       
     1 .. _LDAP:
       
     2 
       
     3 LDAP integration
       
     4 ================
       
     5 
       
     6 Overview
       
     7 --------
       
     8 
       
     9 Using LDAP as a source for user credentials and information is quite
       
    10 easy. The most difficult part lies in building an LDAP schema or
       
    11 using an existing one.
       
    12 
       
    13 At cube creation time, one is asked if more sources are wanted. LDAP
       
    14 is one possible option at this time. Of course, it is always possible
       
    15 to set it up later using the `CWSource` entity type, which we discuss
       
    16 there.
       
    17 
       
    18 It is possible to add as many LDAP sources as wanted, which translates
       
    19 in as many `CWSource` entities as needed.
       
    20 
       
    21 The general principle of the LDAP source is, given a proper
       
    22 configuration, to create local users matching the users available in
       
    23 the directory and deriving local user attributes from directory users
       
    24 attributes. Then a periodic task ensures local user information
       
    25 synchronization with the directory.
       
    26 
       
    27 Users handled by such a source should not be edited directly from
       
    28 within the application instance itself. Rather, updates should happen
       
    29 at the LDAP server level.
       
    30 
       
    31 Credential checks are _always_ done against the LDAP server.
       
    32 
       
    33 .. Note::
       
    34 
       
    35   There are currently two ldap source types: the older `ldapuser` and
       
    36   the newer `ldapfeed`. The older will be deprecated anytime soon, as
       
    37   the newer has now gained all the features of the old and does not
       
    38   suffer from some of its illnesses.
       
    39 
       
    40   The ldapfeed creates real `CWUser` entities, and then
       
    41   activate/deactivate them depending on their presence/absence in the
       
    42   corresponding LDAP source. Their attribute and state
       
    43   (activated/deactivated) are hence managed by the source mechanism;
       
    44   they should not be altered by other means (as such alterations may
       
    45   be overridden in some subsequent source synchronisation).
       
    46 
       
    47 
       
    48 Configuration of an LDAPfeed source
       
    49 -----------------------------------
       
    50 
       
    51 Additional sources are created at cube creation time or later through the
       
    52 user interface.
       
    53 
       
    54 Configure an `ldapfeed` source from the user interface under `Manage` then
       
    55 `data sources`:
       
    56 
       
    57 * At this point `type` has been set to `ldapfeed`.
       
    58 
       
    59 * The `parser` attribute shall be set to `ldapfeed`.
       
    60 
       
    61 * The `url` attribute shall be set to an URL such as ldap://ldapserver.domain/.
       
    62 
       
    63 * The `configuration` attribute contains many options. They are described in
       
    64   detail in the next paragraph.
       
    65 
       
    66 
       
    67 Options of an LDAPfeed source
       
    68 -----------------------------
       
    69 
       
    70 Let us enumerate the options by categories (LDAP server connection,
       
    71 LDAP schema mapping information).
       
    72 
       
    73 LDAP server connection options:
       
    74 
       
    75 * `auth-mode`, (choices are simple, cram_md5, digest_md5, gssapi, support
       
    76   for the later being partial as of now)
       
    77 
       
    78 * `auth-realm`, realm to use when using gssapi/kerberos authentication
       
    79 
       
    80 * `data-cnx-dn`, user dn to use to open data connection to the ldap (eg
       
    81   used to respond to rql queries)
       
    82 
       
    83 * `data-cnx-password`, password to use to open data connection to the
       
    84   ldap (eg used to respond to rql queries)
       
    85 
       
    86 If the LDAP server accepts anonymous binds, then it is possible to
       
    87 leave data-cnx-dn and data-cnx-password empty. This is, however, quite
       
    88 unlikely in practice. Beware that the LDAP server might hide attributes
       
    89 such as "userPassword" while the rest of the attributes remain visible
       
    90 through an anonymous binding.
       
    91 
       
    92 LDAP schema mapping options:
       
    93 
       
    94 * `user-base-dn`, base DN to lookup for users
       
    95 
       
    96 * `user-scope`, user search scope (valid values: "BASE", "ONELEVEL",
       
    97   "SUBTREE")
       
    98 
       
    99 * `user-classes`, classes of user (with Active Directory, you want to
       
   100   say "user" here)
       
   101 
       
   102 * `user-filter`, additional filters to be set in the ldap query to
       
   103   find valid users
       
   104 
       
   105 * `user-login-attr`, attribute used as login on authentication (with
       
   106   Active Directory, you want to use "sAMAccountName" here)
       
   107 
       
   108 * `user-default-group`, name of a group in which ldap users will be by
       
   109   default. You can set multiple groups by separating them by a comma
       
   110 
       
   111 * `user-attrs-map`, map from ldap user attributes to cubicweb
       
   112   attributes (with Active Directory, you want to use
       
   113   sAMAccountName:login,mail:email,givenName:firstname,sn:surname)
       
   114 
       
   115 
       
   116 Other notes
       
   117 -----------
       
   118 
       
   119 * Cubicweb is able to start if ldap cannot be reached, even on
       
   120   cubicweb-ctl start ... If some source ldap server cannot be used
       
   121   while an instance is running, the corresponding users won't be
       
   122   authenticated but their status will not change (e.g. they will not
       
   123   be deactivated)
       
   124 
       
   125 * The user-base-dn is a key that helps cubicweb map CWUsers to LDAP
       
   126   users: beware updating it
       
   127 
       
   128 * When a user is removed from an LDAP source, it is deactivated in the
       
   129   CubicWeb instance; when a deactivated user comes back in the LDAP
       
   130   source, it (automatically) is activated again
       
   131 
       
   132 * You can use the :class:`CWSourceHostConfig` to have variants for a source
       
   133   configuration according to the host the instance is running on. To do so
       
   134   go on the source's view from the sources management view.