1<page xmlns="http://projectmallard.org/1.0/" 2 type="topic" 3 id="ldap-connection"> 4 <info> 5 <title type="sort">1</title> 6 <link type="guide" xref="features"/> 7 <link type="guide" xref="index#connections"/> 8 </info> 9 <title>LDAP connections</title> 10 <p> 11 LDAP connections are different than other connections in a way that an LDAP database stores data in 12 a hierarchical way, in the DIT (Directory Information Tree), whereas other databases accessible using 13 the <app>gda-browser</app> application are relational databases. 14 </p> 15 <p> 16 As a consequence, LDAP connections are treaded specially: as normal connections with tables (see the 17 table mapping explained next), and through the presence of the <link xref="ldap-browser-perspective"> 18 LDAP browser perspective</link> 19 </p> 20 <p> 21 Note that LDAP connections may not be available is either the LDAP database provider is not installed 22 or if the LDAP support was disabled during the compilation. 23 </p> 24 25 <section id="ldap-table-mapping"> 26 <title>LDAP table's mapping</title> 27 <p> 28 Within an LDAP connection, it is possible to declare virtual tables which are mapped to an LDAP search. 29 These virtual tables can then later be used like any other table. The first column of each LDAP virtual 30 table will always be the DN (Distinguished Name) of the entry represented in the row; the other columns 31 depend on the table definition. 32 </p> 33 <p> 34 An LDAP virtual table is defined by the following attributes: 35 </p> 36 <list> 37 <item><p>a table name</p></item> 38 <item><p>the base DN for the search: the LDAP entry at which the search begins (if not specified 39 then the top level entry of the LDAP connection is used)</p></item> 40 <item><p>the search filter: a valid LDAP search filter (if none is provided then the default 41 search filter is "(objectClass=*)", requesting any LDAP entry).</p></item> 42 <item><p>the attributes: the attributes to retrieve, each attribute will be mapped to a column of the 43 table. The attributes must be a comma separated list of attributes, where each attribute can optionally 44 be assigned a type and a multi value option (see below).</p></item> 45 <item><p>the scope: the search scope, "subtree" (to search the base DN and the entire sub tree below), 46 "onelevel" (to search the immediate children of the base DN entry only), or 47 "base" (to search the base DN only)</p></item> 48 </list> 49 <figure> 50 <title>LDAP table's properties</title> 51 <desc>LDAP table's properties</desc> 52 <media type="image" mime="image/png" src="figures/ldap-table-mapping.png"/> 53 </figure> 54 <p> 55 For example in the figure above, the "users" table will "contain" all the LDAP entries from 56 the top level LDAP entry of the connection, and have 3 columns: the DN, the "cn" and the "jpegPhoto". 57 </p> 58 </section> 59 60 <section id="ldap-columns-mapping"> 61 <title>Attributes to columns mapping</title> 62 <p> 63 As mentioned in the previous section, each attribute will be mapped to a column. The column type 64 is normally automatically determined (string, number, ...) but can be forced by appending to the attribute 65 name the "::<type>" for the requested type. 66 </p> 67 <p> 68 Also, because 69 some attributes can have multiple values, the table construction handles multi-valued attributes in 70 different ways, depending on each attribute's options. An option can be specified by appending the 71 "::<option>" to the attribute name. Valid options are: 72 </p> 73 <list> 74 <item><p>"NULL" or "0": a NULL value will be returned for the attribute</p></item> 75 <item><p>"CSV": a comma separated value with all the values of the attribute will be returned. 76 This only works for string attribute types.</p></item> 77 <item><p>"MULT" or "*": a row will be returned for each value of the attribute, effectively 78 multiplying the number of returned rows</p></item> 79 <item><p>"1": only the first value of the attribute will be used, the other values ignored</p></item> 80 <item><p>"CONCAT": the attributes' values are concatenated (with a newline char 81 between each value)</p></item> 82 <item><p>"ERROR": an error value will be returned (this is the default behaviour)</p></item> 83 </list> 84 </section> 85 86 <section id="ldap-ddl-sql"> 87 <title>SQL usable with LDAP connections</title> 88 <p> 89 You can use the SQL understood by <link href="http://sqlite.org/lang.html">SQLite</link> in any LDAP 90 connection. Be aware however that if you define database objects (outside of the extended SQL 91 presented next section), they will be lost the next time the LDAP connection is opened. 92 </p> 93 <p> 94 So it is perfectly safe for example to create a table to store some LDAP data which 95 may require a long operation to obtain, but after closing the LDAP connection, the table 96 and its data will be lost. 97 </p> 98 <p> 99 See the <link xref="sql-sqlite">SQL understood by LDAP connections and virtual connections</link> 100 section for more information. 101 </p> 102 </section> 103 104 <section id="ldap-sql"> 105 <title>SQL extension to handle LDAP tables</title> 106 <p> 107 LDAP tables can be created using an extended set of SQL commands: 108 </p> 109 <list> 110 <item><p><code>CREATE LDAP TABLE <table_name> [BASE='<base_dn>'] [FILTER='<filter>'] [ATTRIBUTES='<filter>'] [SCOPE='<filter>']</code> to declare a new LDAP virtual table</p></item> 111 <item><p><code>DESCRIBE LDAP TABLE <table_name></code> to show LDAP virtual table's definition</p></item> 112 <item><p><code>ALTER LDAP TABLE <table_name> [BASE='<base_dn>'] [FILTER='<filter>'] [ATTRIBUTES='<filter>'] [SCOPE='<filter>']</code> to modify an LDAP virtual table's definition (only the specified part is actually modified)</p></item> 113 <item><p><code>DROP LDAP TABLE <table_name></code> to remove an LDAP virtual table. Note that the 114 usual <code>DROP TABLE <table_name></code> can also be used instead.</p></item> 115 </list> 116 <p> 117 For example the following SQL code: 118 </p> 119 <code> 120 CREATE LDAP TABLE users FILTER='(objectClass=inetOrgPerson)' 121 ATTRIBUTES='cn,sn,givenName,seeAlso::*' SCOPE='subtree'; 122 SELECT * FROM users WHERE cn like '%john%'; 123 ALTER LDAP TABLE users FILTER='(&(objectClass=inetOrgPerson)(cn=*john*))'; 124 SELECT * FROM users; 125 DROP LDAP TABLE users; 126 </code> 127 <p> 128 should display twice the same results, which list all the LDAP entries of the "inetOrgPerson" class with 129 a CommonName (cn) containing the "john" string. 130 </p> 131 </section> 132</page> 133
