ldap_connect

Description

resource ldap_connect ( [string hostname [, int port]] )

Returns a positive LDAP link identifier on success, or FALSE on error. When OpenLDAP 2.x.x is used, ldap_connect() will always return a resource as it does not actually connect but just initializes the connecting parameters. The actual connect happens with the next calls to ldap_* funcs, usually with ldap_bind().

ldap_connect() establishes a connection to a LDAP server on a specified hostname and port. Both the arguments are optional. If no arguments are specified then the link identifier of the already opened link will be returned. If only hostname is specified, then the port defaults to 389.

If you are using OpenLDAP 2.x.x you can specify a URL instead of the hostname. To use LDAP with SSL, compile OpenLDAP 2.x.x with SSL support, configure PHP with SSL, and use ldaps://hostname/ as host parameter. The port parameter is not used when using URLs.

注: URL and SSL support were added in 4.0.4.

例子 1. Example of connecting to LDAP server.


<?php

// LDAP variables
$ldaphost = "ldap.example.com";  // your ldap servers
$ldapport = 389;                 // your ldap server's port number

// Connecting to LDAP
$ldapconn = ldap_connect($ldaphost, $ldapport) 
          or die("Could not connect to $ldaphost");

?>

例子 2. Example of connecting securely to LDAP server.


<?php

// make sure your host is the correct one
// that you issued your secure certificate to
$ldaphost = "ldaps://ldap.example.com/";

// Connecting to LDAP
$ldapconn = ldap_connect($ldaphost) 
          or die("Could not connect to {$ldaphost}");

?>

See also ldap_bind().

add a note User Contributed Notes

elsint at yahoo dot com
22-Sep-2006 04:48


Be careful about the certificate's permission if you are using Windows.



Set certificates' permissions for everyone to Read and Read&Execute or you may get binding errors because of this.

baroque at citromail dot hu
05-Nov-2005 05:20


This code sample shows how to connect and bind to eDirectory in PHP using LDAP for Netware.



<?php



$server='137.65.138.159';

$admin='cn=admin,o=novell';

$passwd='novell';



$ds=ldap_connect($server);  // assuming the LDAP server is on this host



if ($ds) {

    // bind with appropriate dn to give update access

    $r=ldap_bind($ds, $admin, $passwd);

    if(!$r) die("ldap_bind failed<br>");



    echo "ldap_bind success";

    ldap_close($ds);

} else {

    echo "Unable to connect to LDAP server"; 

}

?>

Tony Brady
04-Nov-2005 06:53


I don't why but on my server I am not able to connect successfully to my LDAP server unless I use the IP address of the LDAP server, rather than the hostname. So this DOESN'T work:



<?php

  $ldapconn = ldap_connect('ldap.example.com');

?>



whereas this does work:



<?php

  $ip = gethostbyname('ldap.example.com');

  $ldapconn = ldap_connect($ip);

?>



Of course you don't know it hasn't worked until you try to bind to the server and query it.

Srivathsa M
23-Jun-2005 06:28


Using LDAP over SSL on NetWare:



1. Copy the server certificates to sys:/php5/cert directory. This location is configurable in php.ini file.



2. Use "ldaps://" prefix for host name argument or a value of 636 for port number argument in ldap_connect call.



For more details, visit, NetWare specific PHP documentation at http://developer.novell.com/ndk/doc/php/index.html

nigelf at esp dot co dot uk
26-Apr-2005 06:58


As mentioned above, openLDAP will always return a resource, even if the server name isn't valid.  



If you then bind with errors suppressed (@ldap_bind) and it fails, it's not obvious what caused the failure (ie: connection or credentials).  As the bind doesn't return a resource you can't get the last error from ldap_error etc. either.



If you display just a message about login failure to the user they may get frustrated re-typing a valid username/password when it's the connection that's at fault.

blizzards at libero dot it
28-Sep-2004 06:23


To complete questions about how to connect to a LDAP ACTIVE DIRECTORY 2000/2003 server with SASL on port 636, you can refer to prevous notes, and the following directives:



A)Create CA certificates from AD;

B)Export in .pem (DER) format;

C)Install OPENSSL,CYRUS SASL,OPENLDAP,KERBEROS 5;

D)Copy exported AD ca cert into openssl certs dir on your unix system;

E)Reash with c_reash command;

F)Get a kerberos ticket form AD for your user;

G)Compile PHP with SSL and LDAP support;

H)Test with ldapsearch -D <binddn> -W -H ldaps://ad.secure.com:636 -x



If all works right, create your php script.



Note: For writing parameters to AD you need to renew ticket each 10 hours or less (AD default lifetime ticket), for reading pourpose you can maintain expired ticket.

When querying a windows 2000/2003 AD you MUST use only SASL and not TLS (non supported).

Andrew (a.whyte at cqu.edu.au)
29-Sep-2003 03:15


To be able to make modifications to Active Directory via the LDAP connector you must bind to the LDAP service over SSL. Otherwise Active Directory provides a mostly readonly connection. You cannot add objects or modify certain properties without LDAPS, e.g. passwords can only be changed using LDAPS connections to Active Directory.



Therefore, for those wishing to securely connect to Active Directory, from a Unix host using PHP+OpenLDAP+OpenSSL I spent some time getting this going myself, and came across a few gotcha's. Hope this proves fruitfull for others like me when you couldn't find answers out there.



Make sure you compile OpenLDAP with OpenSSL support, and that you compile PHP with OpenLDAP and OpenSSL.



This provides PHP with what it needs to make use of ldaps:// connections.



Configure OpenSSL:



Extract your Root CA certificate from Active Directory, this is achived through the use of Certificate Services, a startard component of Windows 2000 Server, but may not be installed by default, (The usual Add/Remove Software method will work here). I extracted this in Base64 not DER format.



Place the extracted CAcert into the certs folder for openssl. (e.g. /usr/local/ssl/certs) and setup the hashed symlinks. This is easily done by simply running:



  /usr/local/ssl/bin/c_rehash



Once this is done you can test it is worked by running:



  /usr/local/ssl/bin/openssl verify -verbose -CApath /usr/local/ssl/certs /tmp/exported_cacert.pem



(Should return: OK).



Configure OpenLDAP:



Add the following to your ldap.conf file.

(found as /usr/local/openldap/etc/openldap/ldap.conf)



  #--begin--



  # Instruct client to NOT request a server's cert.

  TLS_REQCERT never



  # Define location of CA Cert

  TLS_CACERT /usr/local/ssl/certs/AD_CA_CERT.pem

  TLS_CACERTDIR /usr/local/ssl/certs



  #--end--



You also need to place those same settings in a file within the Apache Web user homedir called .ldaprc



  e.g.:

  

  cp /usr/local/openldap/etc/openldap/ldap.conf ~www/.ldaprc )



You can then test that you're able to establish a LDAPS connection to Active Directory from the OpenLDAP command tools:



  /usr/local/openldap/bin/ldapsearch -H "ldaps://adserver.ad.com"



This should return some output in extended LDIF format and will indicate no matching objects, but it proves the connection works.



The name of the server you're connecting to is important. If they server name you specify in the "ldaps://" URI does not match the name of the server in it's certificate, it will complain like so:



  ldap_bind: Can't contact LDAP server (81)

        additional info: TLS: hostname does not match CN in peer certificate



Once you've gotten the ldapsearch tool working correctly PHP should work also.



One important gotcha however is that the Web user must be able to locate it's HOME folder. You must check that Apache is providing a HOME variable set to the Web users home directory, so that php can locate the .ldaprc file and the settings contained within. This may well be different between Unix variants but it is such a simple and stupid thing if you miss it and it causes you grief. Simply use a SetEnv directive in Apache's httpd.conf:



  SetEnv HOME /usr/local/www



With all that done, you can now code up a simple connect function:



  function connect_AD()

  {

    $ldap_server = "ldaps://adserver.ad.com" ;

    $ldap_user   = "CN=web service account,OU=Service Accounts,DC=ad,DC=com" ;

    $ldap_pass   = "password" ;



    $ad = ldap_connect($ldap_server) ;

    ldap_set_option($ad, LDAP_OPT_PROTOCOL_VERSION, 3) ;

    $bound = ldap_bind($ad, $ldap_user, $ldap_pass);



    return $ad ;

  }



Optionally you can avoid the URI style server string and use something like ldap_connect("adserver.ad.com", 636) ;  But work fine with Active Directory servers.



Hope this proves usefull.

avel at noc uoa gr
24-Jul-2002 10:05


Note that hostname can be a space-separated list of LDAP host names. This is very useful for failover; if the first ldap host is down, ldap_connect will ask the second LDAP host. Of course, you _must_ have LDAP replicates before doing this. :) Read the LDAP API documentation for more information.





This can also be useful, apart from failover, for LDAP load balancing. Just use a random generator function that will return a different space-separated list every time. This is because the first host in the list is always tried first.





Be careful when doing LDAP writes; be sure to always connect to your master host when you are about to modify the database, so that the replicates will get the changes as expected.





Alexandros Vellis

25-Apr-2002 12:28


A resource ID is always returned when using URLs for the host parameter

even if the host does not exist.



"When using an URI to describe the connection, the (open)ldap library

only parses the url and checks if it's valid, _no connection_ is

established in that case."

-mfischer@php.net

http://bugs.php.net/bug.php?id=15637

add a note