Sorting Out Work

I paged through the adLDAP.php library for a lot of functions. Please add and comment on them. I don't do much with writing to the LDAP so am unclear on the utility of those functions. I think a wiki would be better for hashing out the functions and methods of the api, but am not sure where on drupal to put one. I'll look into that. I committed the code I had. I haven't really looked at in 6 months, so not sure what state its in.

I see 2 sets of functions:

1. ones that were about configuring or querying ldap instances. These I put in the .module file: (first code set below)
2. ones that only make sense in the context of a particular ldap connection. I made these methods and properties on an ldap class which would be instantiated based on an ldap configuration. (second code set below)

I'm generally looking at a stored ldap configuration as a given server and service account such that a single LDAP server might be used in different ldap configurations for different purposes.

/**
 * get one or more ldap_api_server objects
 *
 * @param $server
 *   - integer representing server id,
 *   - or name => value array of server parameters,
 *   - or instantiated server object
 *   - or NULL signifying find all servers configured
 *   
 * @param $module
 *   if present, only return servers which a module has enabled.
 *
 * @param $reset
 *   clear any cached servers
 *   
 * @return
 *   Array of ldap_server objects
 *   or single server object if server id passed in
 */

function ldap_api_get_server_objects($server = NULL, $module = NULL, $reset = FALSE) {
  require_once('ldap_api.functions.inc');
  return _ldap_api_get_server_objects($server, $module, $reset);
}


/**
 * update cache
 *
 */
function ldap_api_config_update_cache() {
  $ldap_api_config = ldap_api_config_get($reset = TRUE); 
}
/**
 * get configuration array from cache or db
 *   http://www.lullabot.com/articles/a_beginners_guide_to_caching_data
 *   http://dc2009.drupalcon.org/session/inside-drupal-caching-static-variables-memcache
 *
 * @param $reset
 *   true signifies override cache or static variable and get from db
 *   
 * @param $sid
 *   if present, only return a single server's configuration
 *
 * @return
 *  ldap configuration as array or single ldap server configuration
 */
 
function ldap_api_config_get($reset = FALSE, $sid = FALSE) {
  require_once('ldap_api.functions.inc');
  return _ldap_api_config_get($reset, $sid);
}

function ldap_api_module_server_config_get($sid, $module) {
  require_once('ldap_api.functions.inc');
  $ldap_server_config = _ldap_api_config_get(FALSE, $sid);
  return $ldap_server_config['module_data'][$module];
}

function ldap_api_module_server_config_set($sid, $module, $data, $merge = FALSE) { // merge means merge arrays, if not will overwrite
  require_once('ldap_api.functions.inc');
 // return _ldap_api_module_server_config_set($sid, $module, $data, $merge);  // needs to be written.  
}


/**
 * get single ldap server attribute
 *
 * @param $sid
 *   ldap server id
 *   
 * @param $attr
 *   attribute name
 *
 * @module
 *    module name.  if given, attribute is returned from module_data array
 *
 * @return
 *  ldap configuration as array or single ldap server configuration
 */
 function ldap_api_server_get_attribute($sid, $attr, $module) {
  require_once('ldap_api.functions.inc');
  return _ldap_api_server_get_attribute($sid, $attr, $module);
 }
 
function ldap_api_encrypt($text) {
  require_once('ldap_api.functions.inc');
  return _ldap_api_encrypt($text);
}

function ldap_api_decrypt($encrypted, $encryption) {
  require_once('ldap_api.functions.inc');
  return _ldap_api_decrypt($encrypted, $encryption);
}

function ldap_api_ldap_extension_loaded() {
  require_once('ldap_api.functions.inc');
  return _ldap_api_ldap_extension_loaded();
}

/**
 * Class to encapsulate a single LDAP Server configuration
 *
 */

class ldap_api_server {

  public $connection = NULL;
  public $server_addr = NULL;
  public $name;
  public $port = 389;
  public $tls = FALSE;
  public $sid;
  public $pwd_encryption;
  public $binddn;
  public $bindpw;
  public $basedns;  // array of basedns
  public $basedn; // set of basedns separated by returns
  public $user_attr;
  public $mail_attr = "mail";
  public $ldap_to_drupal_user;
  public $testing_drupal_username;
  public $module_data;
  
  /**
 * Constructor Method
 *
 * @param $params
 *   Can be:
 *     - an associative array of property-name => property-values
 *     - the id (sid) of an ldap server configuration stored by ldap_server module
 */
  function __construct($params = NULL) {
    $constructor_properties = array('server_addr','name','port','tls','pwd_encryption','binddn','bindpw','basedn','user_attr','mail_attr','ldap_to_drupal_user','testing_drupal_username','module_data');
    if (is_array($params)) {
      foreach (array_intersect($params,$constructor_properties) as $prop) {
        if (isset($params[$prop])) {
          $this->$prop = $params[$prop];
        }
      }  
    }
    elseif (is_numeric($params)) {
      $this->sid = $params;
      $record = db_fetch_object(db_query("SELECT * FROM {ldap_api_servers} WHERE sid = %d", $this->sid));
      foreach ($constructor_properties as $prop) {
        if (isset($record->$prop)) {
          $this->$prop = $record->$prop;
        }
      }  
    }
    
    if ($this->basedn) {
    // dpm('explode');  dpm(explode("\r\n", $this->basedn));
      $this->basedns = serialize(explode("\r\n", $this->basedn));
    }
  }

  function __destruct() {
    // should break any connection or binding
  }


  function connect($dn = NULL, $pass = NULL) {
    $this->disconnect();
    $dn = ($dn != NULL) ? $dn : $this->binddn;
    $pass = ($pass != NULL) ? $pass :  ldap_api_decrypt($this->bindpw, $this->pwd_encryption);
    return ($this->connectAndBind($dn, $pass));
  }

  function initConnection() {
    if (!$con = ldap_connect($this->server_addr, $this->port)) {
      watchdog('user', 'LDAP Connect failure to '. $this->server_addr .':'. $this->port);
      return;
    }

    ldap_set_option($con, LDAP_OPT_PROTOCOL_VERSION, 3);
    ldap_set_option($con, LDAP_OPT_REFERRALS, 0);
    if ($this->tls) {
      ldap_get_option($con, LDAP_OPT_PROTOCOL_VERSION, $vers);
      if ($vers == -1) {
        watchdog('user', 'Could not get LDAP protocol version.');
        return;
      }
      if ($vers != 3) {
        watchdog('user', 'Could not start TLS, only supported by LDAP v3.');
        return;
      }
      else if (!function_exists('ldap_start_tls')) {
        watchdog('user', 'Could not start TLS. It does not seem to be supported by this PHP setup.');
        return;
      }
      else if (!ldap_start_tls($con)) {
        watchdog('user', t("Could not start TLS. (Error %errno: %error).", array('%errno' => ldap_errno($con), '%error' => ldap_error($con))));
        return;
      }
    }
    $this->connection = $con;
  }

  function connectAndBind($dn, $pass) {
    $this->initConnection();
    $con = $this->connection;
    if (!$this->bind($dn, $pass)) {
      watchdog('user', 'LDAP Bind failure for user %user. Error %errno: %error', array('%user' => $dn, '%errno' => ldap_errno($con), '%error' => ldap_error($con)));
      return NULL;
    }

    return $con;
  }

  function bind($dn, $pass) {
    ob_start();
    set_error_handler(array('LDAPInterface', 'void_error_handler'));
    $ret = ldap_bind($this->connection, $dn, $pass);
    restore_error_handler();

    ob_end_clean();

    return $ret;
  }

  function disconnect() {
    if ($this->connection) {
      ldap_unbind($this->connection);
      $this->connection = NULL;
    }
  }

  /**
 * get_ldap_user_entry_from_drupal_username
 *
 * @param $drupal_username
 *
 * @return
 *   If no matching user found in LDAP: FALSE 
 *   If match found: an associative array of LDAP User object properties
 */
  
  public function get_ldap_user_entry_from_drupal_username($drupal_username) {
  
    if ($ldap_server->ldap_to_drupal_user) {
      $name = $drupal_username;
      drupal_eval($ldap_server->ldap_to_drupal_user);
      $drupal_username = $name;
    }
    
    foreach ($this->basedns as $base_dn) {
     $filter = $this->user_attr .'='. $drupal_username;
     $result = $this->search($base_dn, $filter);
     if (!$result)
       continue;
     
     // Must find exactly one user for authentication to.
     if ($result['count'] != 1) {
       watchdog('ldapauth', "Error: %num_matches users found with $%filter under %base_dn.", array('%num_matches' => $result['count'], '%filter' => $filter, '%base_dn' => $base_dn), WATCHDOG_ERROR);
       continue;
     }
     $match = $result[0];
 
     // These lines serve to fix the attribute name in case a
     // naughty server (i.e.: MS Active Directory) is messing the
     // characters' case.
     // This was contributed by Dan "Gribnif" Wilga, and described
     // here: http://drupal.org/node/87833
     if (!isset($match[$this->user_attr][0])) {
       $username_attr = drupal_strtolower($this->user_attr);
       if (!isset($match[$username_attr][0]))
         continue;
     }
     // Finally, we must filter out results with spaces added before
     // or after, which are considered OK by LDAP but are no good for us
     // We allow lettercase independence, as requested by Marc Galera
     // on http://drupal.org/node/97728
     //
     // Some setups have multiple $name_attr per entry, as pointed out by
     // Clarence "sparr" Risher on http://drupal.org/node/102008, so we
     // loop through all possible options.
     foreach ($match[$username_attr] as $value) {
       if (drupal_strtolower(trim($value)) == drupal_strtolower($drupal_username))
         return $match;
     }
     
    }
  

  }
  
  function search($base_dn, $filter, $attributes = array()) {
    $ret = array();

    // For the AD the '\,' should be replaced by the '\\,' in the search filter.
    $filter = preg_replace('/\\\,/', '\\\\\,', $filter);

    set_error_handler(array('ldap_server', 'void_error_handler'));
    $x = @ldap_search($this->connection, $base_dn, $filter, $attributes);
    restore_error_handler();

    if ($x && ldap_count_entries($this->connection, $x)) {
      $ret = ldap_get_entries($this->connection, $x);
    }
    return $ret;
  }

  // WARNING! WARNING! WARNING!
  // This function returns its entries with lowercase attribute names.
  // Don't blame me, blame PHP's own ldap_get_entries()
  function retrieveAttributes($dn) {
    set_error_handler(array('ldap_server', 'void_error_handler'));
    $result = ldap_read($this->connection, $dn, 'objectClass=*');
    $entries = ldap_get_entries($this->connection, $result);
    restore_error_handler();

    return call_user_func($this->attr_filter, $this->sid, $entries[0]);
  }

  function retrieveAttribute($dn, $attrname) {
    $entries = $this->retrieveAttributes($dn);
    return isset($entries[strtolower($attrname)]) ? $entries[strtolower($attrname)][0] : NULL;
  }

  function retrieveMultiAttribute($dn, $attrname) {
    $entries = $this->retrieveAttributes($dn);

    $result = array();
    $retrieved = $entries[strtolower($attrname)];
    $retrieved = $retrieved ? $retrieved : array();
    foreach ($retrieved as $key => $value) {
      if ($key !== 'count') {
        $result[] = $value;
      }
    }
    return $result;
  }

  function writeAttributes($dn, $attributes) {
    foreach ($attributes as $key => $cur_val) {
      if ($cur_val == '') {
        unset($attributes[$key]);
        $old_value = $this->retrieveAttribute($dn, $key);
        if (isset($old_value)) {
          ldap_mod_del($this->connection, $dn, array($key => $old_value));
        }
      }
      if (is_array ($cur_val)) {
        foreach ($cur_val as $mv_key => $mv_cur_val) {
          if ($mv_cur_val == '') {
            unset($attributes[$key][$mv_key]);
          }
          else {
            $attributes[$key][$mv_key] = $mv_cur_val;
          }
        }
      }
    }

    ldap_modify($this->connection, $dn, $attributes);
  }

  function create_entry($dn, $attributes) {
    set_error_handler(array('ldap_server', 'void_error_handler'));
    $ret = ldap_add($this->connection, $dn, $attributes);
    restore_error_handler();

    return $ret;
  }

  function rename_entry($dn, $newrdn, $newparent, $deleteoldrdn) {
    set_error_handler(array('ldap_server', 'void_error_handler'));
    $ret = ldap_rename($this->connection, $dn, $newrdn, $newparent, $deleteoldrdn);
    restore_error_handler();

    return $ret;
  }

  function delete_entry($dn) {
    set_error_handler(array('ldap_server', 'void_error_handler'));
    $ret = ldap_delete($this->connection, $dn);
    restore_error_handler();

    return $ret;
  }

  // This function is used by other modules to delete attributes once they are
  // moved to profiles cause ldap_mod_del does not delete facsimileTelephoneNumber if
  // attribute value to delete is passed to the function.
  // OpenLDAP as per RFC 2252 doesn't have equality matching for facsimileTelephoneNumber
  // http://bugs.php.net/bug.php?id=7168
  function deleteAttribute($dn, $attribute) {
    ldap_mod_del($this->connection, $dn, array($attribute => array()));
  }

  static function void_error_handler($p1, $p2, $p3, $p4, $p5) {
  }
  
}

My initial code is in head. I'm converting it to D7 also. I'm definately on board with focus on the api. I tried to even separate out the server from the api, but no luck. Do you both agree on these points:

- the ldap server configuration interface should be in the ldap api module
- an ldap server instance should be represented as an object/class in our code
- authentication, authorization, etc. should be in sub or other modules
- a functional requirement of the api is for authorization and authentication to be separateable.

Are you also in agreement on these design principles?

• accessible ui
• Simpletest Coverage
• Patterns and Features Support
• Internationalization
• Provide Adequate Hooks
• PDO in D7; no SQL
• Drupal Coding
• no PHP4 support
• doxygen

I think a wiki is in order since its time to flush out functions and structure. I'm going to create a wiki page in the ldap integration group on gdo. I just found the group and joined it. (http://groups.drupal.org/ldap-integration-development-and-modules)

Not my favorite wiki ui, but I think its good that its on the drupal site. http://groups.drupal.org/node/68688

There is a middle ground between authorization and authentication. There are often feature requests in ldapauth for the ability to filter which ous can authenticate, or some other filter disallowing authentication by valid ldap user, who just don't have the correct characteristics.

Thus an ldap authn and an ldap authz module could use some of the same functions, but would end up with different mapping/filtering interfaces.

This will sort itself out when we have the ldap authn and an ldap authz modules.

this module moved to the project/ldap namespace. closing issue.