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. |
|