lib/ldaplib.php

   1 <?php
   2
   3 /**
   4  * ldaplib.php - LDAP functions & data library
   5  *
   6  * Library file of miscellaneous general-purpose LDAP functions and
   7  * data structures, useful for both ldap authentication (or ldap based
   8  * authentication like CAS) and enrolment plugins.
   9  *
  10  * @author     Iñaki Arenaza
  11  * @package    core
  12  * @subpackage lib
  13  * @copyright  1999 onwards Martin Dougiamas  http://dougiamas.com
  14  * @copyright  2010 onwards Iñaki Arenaza
  15  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  16  */
  17
  18 defined('MOODLE_INTERNAL') || die();
  19
  20 // rootDSE is defined as the root of the directory data tree on a directory server.
  21 if (!defined('ROOTDSE')) {
  22     define ('ROOTDSE', '');
  23 }
  24
  25 // Default page size when using LDAP paged results
  26 if (!defined('LDAP_DEFAULT_PAGESIZE')) {
  27     define('LDAP_DEFAULT_PAGESIZE', 250);
  28 }
  29
  30 /**
  31  * Returns predefined user types
  32  *
  33  * @return array of predefined user types
  34  */
  35 function ldap_supported_usertypes() {
  36     $types = array();
  37     $types['edir'] = 'Novell Edirectory';
  38     $types['rfc2307'] = 'posixAccount (rfc2307)';
  39     $types['rfc2307bis'] = 'posixAccount (rfc2307bis)';
  40     $types['samba'] = 'sambaSamAccount (v.3.0.7)';
  41     $types['ad'] = 'MS ActiveDirectory';
  42     $types['default'] = get_string('default');
  43     return $types;
  44 }
  45
  46 /**
  47  * Initializes needed variables for ldap-module
  48  *
  49  * Uses names defined in ldap_supported_usertypes.
  50  * $default is first defined as:
  51  * $default['pseudoname'] = array(
  52  *                      'typename1' => 'value',
  53  *                      'typename2' => 'value'
  54  *                      ....
  55  *                      );
  56  *
  57  * @return array of default values
  58  */
  59 function ldap_getdefaults() {
  60     // All the values have to be written in lowercase, even if the
  61     // standard LDAP attributes are mixed-case
  62     $default['objectclass'] = array(
  63                         'edir' => 'user',
  64                         'rfc2307' => 'posixaccount',
  65                         'rfc2307bis' => 'posixaccount',
  66                         'samba' => 'sambasamaccount',
  67                         'ad' => 'user',
  68                         'default' => '*'
  69                         );
  70     $default['user_attribute'] = array(
  71                         'edir' => 'cn',
  72                         'rfc2307' => 'uid',
  73                         'rfc2307bis' => 'uid',
  74                         'samba' => 'uid',
  75                         'ad' => 'cn',
  76                         'default' => 'cn'
  77                         );
  78     $default['memberattribute'] = array(
  79                         'edir' => 'member',
  80                         'rfc2307' => 'member',
  81                         'rfc2307bis' => 'member',
  82                         'samba' => 'member',
  83                         'ad' => 'member',
  84                         'default' => 'member'
  85                         );
  86     $default['memberattribute_isdn'] = array(
  87                         'edir' => '1',
  88                         'rfc2307' => '0',
  89                         'rfc2307bis' => '1',
  90                         'samba' => '0', // is this right?
  91                         'ad' => '1',
  92                         'default' => '0'
  93                         );
  94     $default['expireattr'] = array (
  95                         'edir' => 'passwordexpirationtime',
  96                         'rfc2307' => 'shadowexpire',
  97                         'rfc2307bis' => 'shadowexpire',
  98                         'samba' => '', // No support yet
  99                         'ad' => 'pwdlastset',
 100                         'default' => ''
 101                         );
 102     return $default;
 103 }
 104
 105 /**
 106  * Checks if user belongs to specific group(s) or is in a subtree.
 107  *
 108  * Returns true if user belongs to a group in grupdns string OR if the
 109  * DN of the user is in a subtree of the DN provided as "group"
 110  *
 111  * @param mixed $ldapconnection A valid LDAP connection.
 112  * @param string $userid LDAP user id (dn/cn/uid/...) to test membership for.
 113  * @param array $group_dns arrary of group dn
 114  * @param string $member_attrib the name of the membership attribute.
 115  * @return boolean
 116  *
 117  */
 118 function ldap_isgroupmember($ldapconnection, $userid, $group_dns, $member_attrib) {
 119     if (empty($ldapconnection) || empty($userid) || empty($group_dns) || empty($member_attrib)) {
 120         return false;
 121     }
 122
 123     $result = false;
 124     foreach ($group_dns as $group) {
 125         $group = trim($group);
 126         if (empty($group)) {
 127             continue;
 128         }
 129
 130         // Check cheaply if the user's DN sits in a subtree of the
 131         // "group" DN provided. Granted, this isn't a proper LDAP
 132         // group, but it's a popular usage.
 133         if (stripos(strrev(strtolower($userid)), strrev(strtolower($group))) === 0) {
 134             $result = true;
 135             break;
 136         }
 137
 138         $search = ldap_read($ldapconnection, $group,
 139                             '('.$member_attrib.'='.ldap_filter_addslashes($userid).')',
 140                             array($member_attrib));
 141
 142         if (!empty($search) && ldap_count_entries($ldapconnection, $search)) {
 143             $info = ldap_get_entries_moodle($ldapconnection, $search);
 144             if (count($info) > 0 ) {
 145                 // User is member of group
 146                 $result = true;
 147                 break;
 148             }
 149         }
 150     }
 151
 152     return $result;
 153 }
 154
 155 /**
 156  * Tries connect to specified ldap servers. Returns a valid LDAP
 157  * connection or false.
 158  *
 159  * @param string $host_url
 160  * @param integer $ldap_version either 2 (LDAPv2) or 3 (LDAPv3).
 161  * @param string $user_type the configured user type for this connection.
 162  * @param string $bind_dn the binding user dn. If an emtpy string, anonymous binding is used.
 163  * @param string $bind_pw the password for the binding user. Ignored for anonymous bindings.
 164  * @param boolean $opt_deref whether to set LDAP_OPT_DEREF on this connection or not.
 165  * @param string &$debuginfo the debugging information in case the connection fails.
 166  * @param boolean $start_tls whether to use LDAP with TLS (not to be confused with LDAP+SSL)
 167  * @return mixed connection result or false.
 168  */
 169 function ldap_connect_moodle($host_url, $ldap_version, $user_type, $bind_dn, $bind_pw, $opt_deref, &$debuginfo, $start_tls=false) {
 170     if (empty($host_url) || empty($ldap_version) || empty($user_type)) {
 171         $debuginfo = 'No LDAP Host URL, Version or User Type specified in your LDAP settings';
 172         return false;
 173     }
 174
 175     $debuginfo = '';
 176     $urls = explode(';', $host_url);
 177     foreach ($urls as $server) {
 178         $server = trim($server);
 179         if (empty($server)) {
 180             continue;
 181         }
 182
 183         $connresult = ldap_connect($server); // ldap_connect returns ALWAYS true
 184
 185         if (!empty($ldap_version)) {
 186             ldap_set_option($connresult, LDAP_OPT_PROTOCOL_VERSION, $ldap_version);
 187         }
 188
 189         // Fix MDL-10921
 190         if ($user_type === 'ad') {
 191             ldap_set_option($connresult, LDAP_OPT_REFERRALS, 0);
 192         }
 193
 194         if (!empty($opt_deref)) {
 195             ldap_set_option($connresult, LDAP_OPT_DEREF, $opt_deref);
 196         }
 197
 198         if ($start_tls && (!ldap_start_tls($connresult))) {
 199             $debuginfo .= "Server: '$server', Connection: '$connresult', STARTTLS failed.\n";
 200             continue;
 201         }
 202
 203         if (!empty($bind_dn)) {
 204             $bindresult = @ldap_bind($connresult, $bind_dn, $bind_pw);
 205         } else {
 206             // Bind anonymously
 207             $bindresult = @ldap_bind($connresult);
 208         }
 209
 210         if ($bindresult) {
 211             return $connresult;
 212         }
 213
 214         $debuginfo .= "Server: '$server', Connection: '$connresult', Bind result: '$bindresult'\n";
 215     }
 216
 217     // If any of servers were alive we have already returned connection.
 218     return false;
 219 }
 220
 221 /**
 222  * Search specified contexts for username and return the user dn like:
 223  * cn=username,ou=suborg,o=org
 224  *
 225  * @param mixed $ldapconnection a valid LDAP connection.
 226  * @param mixed $username username (external LDAP encoding, no db slashes).
 227  * @param array $contexts contexts to look for the user.
 228  * @param string $objectclass objectlass of the user (in LDAP filter syntax).
 229  * @param string $search_attrib the attribute use to look for the user.
 230  * @param boolean $search_sub whether to search subcontexts or not.
 231  * @return mixed the user dn (external LDAP encoding, no db slashes) or false
 232  *
 233  */
 234 function ldap_find_userdn($ldapconnection, $username, $contexts, $objectclass, $search_attrib, $search_sub) {
 235     if (empty($ldapconnection) || empty($username) || empty($contexts) || empty($objectclass) || empty($search_attrib)) {
 236         return false;
 237     }
 238
 239     // Default return value
 240     $ldap_user_dn = false;
 241
 242     // Get all contexts and look for first matching user
 243     foreach ($contexts as $context) {
 244         $context = trim($context);
 245         if (empty($context)) {
 246             continue;
 247         }
 248
 249         if ($search_sub) {
 250             if (!$ldap_result = @ldap_search($ldapconnection, $context,
 251                                            '(&'.$objectclass.'('.$search_attrib.'='.ldap_filter_addslashes($username).'))',
 252                                            array($search_attrib))) {
 253                 break; // Not found in this context.
 254             }
 255         } else {
 256             $ldap_result = ldap_list($ldapconnection, $context,
 257                                      '(&'.$objectclass.'('.$search_attrib.'='.ldap_filter_addslashes($username).'))',
 258                                      array($search_attrib));
 259         }
 260
 261         $entry = ldap_first_entry($ldapconnection, $ldap_result);
 262         if ($entry) {
 263             $ldap_user_dn = ldap_get_dn($ldapconnection, $entry);
 264             break;
 265         }
 266     }
 267
 268     return $ldap_user_dn;
 269 }
 270
 271 /**
 272  * Returns values like ldap_get_entries but is binary compatible and
 273  * returns all attributes as array.
 274  *
 275  * @param mixed $ldapconnection A valid LDAP connection
 276  * @param mixed $searchresult A search result from ldap_search, ldap_list, etc.
 277  * @return array ldap-entries with lower-cased attributes as indexes
 278  */
 279 function ldap_get_entries_moodle($ldapconnection, $searchresult) {
 280     if (empty($ldapconnection) || empty($searchresult)) {
 281         return array();
 282     }
 283
 284     $i = 0;
 285     $result = array();
 286     $entry = ldap_first_entry($ldapconnection, $searchresult);
 287     if (!$entry) {
 288         return array();
 289     }
 290     do {
 291         $attributes = array_change_key_case(ldap_get_attributes($ldapconnection, $entry), CASE_LOWER);
 292         for ($j = 0; $j < $attributes['count']; $j++) {
 293             $values = ldap_get_values_len($ldapconnection, $entry, $attributes[$j]);
 294             if (is_array($values)) {
 295                 $result[$i][$attributes[$j]] = $values;
 296             } else {
 297                 $result[$i][$attributes[$j]] = array($values);
 298             }
 299         }
 300         $i++;
 301     } while ($entry = ldap_next_entry($ldapconnection, $entry));
 302
 303     return ($result);
 304 }
 305
 306 /**
 307  * Quote control characters in texts used in LDAP filters - see RFC 4515/2254
 308  *
 309  * @param string filter string to quote
 310  * @return string the filter string quoted
 311  */
 312 function ldap_filter_addslashes($text) {
 313     $text = str_replace('\\', '\\5c', $text);
 314     $text = str_replace(array('*',    '(',    ')',    "\0"),
 315                         array('\\2a', '\\28', '\\29', '\\00'), $text);
 316     return $text;
 317 }
 318
 319 if(!defined('LDAP_DN_SPECIAL_CHARS')) {
 320     define('LDAP_DN_SPECIAL_CHARS', 0);
 321 }
 322 if(!defined('LDAP_DN_SPECIAL_CHARS_QUOTED_NUM')) {
 323     define('LDAP_DN_SPECIAL_CHARS_QUOTED_NUM', 1);
 324 }
 325 if(!defined('LDAP_DN_SPECIAL_CHARS_QUOTED_ALPHA')) {
 326     define('LDAP_DN_SPECIAL_CHARS_QUOTED_ALPHA', 2);
 327 }
 328
 329 /**
 330  * The order of the special characters in these arrays _IS IMPORTANT_.
 331  * Make sure '\\5C' (and '\\') are the first elements of the arrays.
 332  * Otherwise we'll double replace '\' with '\5C' which is Bad(tm)
 333  */
 334 function ldap_get_dn_special_chars() {
 335     return array (
 336         LDAP_DN_SPECIAL_CHARS              => array('\\',  ' ',   '"',   '#',   '+',   ',',   ';',   '<',   '=',   '>',   "\0"),
 337         LDAP_DN_SPECIAL_CHARS_QUOTED_NUM   => array('\\5c','\\20','\\22','\\23','\\2b','\\2c','\\3b','\\3c','\\3d','\\3e','\\00'),
 338         LDAP_DN_SPECIAL_CHARS_QUOTED_ALPHA => array('\\\\','\\ ', '\\"', '\\#', '\\+', '\\,', '\\;', '\\<', '\\>', '\\=', '\\00'),
 339         );
 340 }
 341
 342 /**
 343  * Quote control characters in distinguished names used in LDAP - See RFC 4514/2253
 344  *
 345  * @param string The text to quote
 346  * @return string The text quoted
 347  */
 348 function ldap_addslashes($text) {
 349     $special_dn_chars = ldap_get_dn_special_chars();
 350
 351     $text = str_replace ($special_dn_chars[LDAP_DN_SPECIAL_CHARS],
 352                          $special_dn_chars[LDAP_DN_SPECIAL_CHARS_QUOTED_NUM],
 353                          $text);
 354     return $text;
 355 }
 356
 357 /**
 358  * Unquote control characters in distinguished names used in LDAP - See RFC 4514/2253
 359  *
 360  * @param string The text quoted
 361  * @return string The text unquoted
 362  */
 363 function ldap_stripslashes($text) {
 364     $special_dn_chars = ldap_get_dn_special_chars();
 365
 366     // First unquote the simply backslashed special characters. If we
 367     // do it the other way, we remove too many slashes.
 368     $text = str_replace($special_dn_chars[LDAP_DN_SPECIAL_CHARS_QUOTED_ALPHA],
 369                         $special_dn_chars[LDAP_DN_SPECIAL_CHARS],
 370                         $text);
 371
 372     // Next unquote the 'numerically' quoted characters. We don't use
 373     // LDAP_DN_SPECIAL_CHARS_QUOTED_NUM because the standard allows us
 374     // to quote any character with this encoding, not just the special
 375     // ones.
 376     $text = preg_replace('/\\\([0-9A-Fa-f]{2})/e', "chr(hexdec('\\1'))", $text);
 377
 378     return $text;
 379 }
 380
 381
 382 /**
 383  * Check if PHP supports LDAP paged results and we can use them (we have to use LDAP
 384  * version 3, otherwise the server doesn't use them).
 385  *
 386  * @param ldapversion integer The LDAP protocol version we use.
 387  *
 388  * @return boolean true is paged results can be used, false otherwise.
 389  */
 390 function ldap_paged_results_supported($ldapversion) {
 391
 392     if (((int)$ldapversion === 3) &&
 393         function_exists('ldap_control_paged_result') &&
 394         function_exists('ldap_control_paged_result_response')) {
 395
 396         return true;
 397     }
 398
 399     return false;
 400 }