Skip to content
Snippets Groups Projects
Commit 9f0ee42a authored by Hahn Axel (hahn)'s avatar Hahn Axel (hahn)
Browse files

update docs

parent b86636d7
No related branches found
No related tags found
1 merge request!2php8 only: use variable types; update phpdocs
Show whitespace changes
Inline Side-by-side
README.md
+ 4
− 5
View file @ 9f0ee42a
...@@ -5,8 +5,7 @@ A PHP class that I use ...@@ -5,8 +5,7 @@ A PHP class that I use
* for authentication of user logins * for authentication of user logins
* CRUD actions on ldap nodes * CRUD actions on ldap nodes
Institute for Medical Education; University of Bern 👤 Author: Axel Hahn; Institute for Medical Education; University of Bern
📄 Source: https://git-repo.iml.unibe.ch/iml-open-source/ldap-php-class
License: GNU GPL 3 📜 License: GNU GPL 3.0
📗 Docs: https://os-docs.iml.unibe.ch/ldap-php-class/
see [docs](docs/)
\ No newline at end of file
docs/20_Usage.md
+ 60
− 8
View file @ 9f0ee42a
...@@ -11,12 +11,11 @@ require_once '[APPROOT]/classes/ldap.class.php'; ...@@ -11,12 +11,11 @@ require_once '[APPROOT]/classes/ldap.class.php';
As an example I create a hash named $aConfig and save it as "inc_config.php". As an example I create a hash named $aConfig and save it as "inc_config.php".
```php ```php
$aConfig=[ return [
... ...
'ldap' => [ 'ldap' => [
'server' => 'ldaps://ldap.example.com', 'server' => 'ldaps://ldap.example.com',
'port' => 636,
'DnLdapUser' => 'cn=Lookup,ou=Service,dc=some,dc=example.com', 'DnLdapUser' => 'cn=Lookup,ou=Service,dc=some,dc=example.com',
'PwLdapUser' => 'PasswordOfLookupUser', 'PwLdapUser' => 'PasswordOfLookupUser',
...@@ -32,16 +31,69 @@ $aConfig=[ ...@@ -32,16 +31,69 @@ $aConfig=[
]; ];
``` ```
## Example: verify login data ## initialize connection
```php ```php
require_once('inc_config.php'); $aConfig = require_once('inc_config.php');
require_once '[APPROOT]/classes/ldap.class.php'; require_once '[APPROOT]/classes/ldap.class.php';
oLdap=new imlldap($aConfig['ldap']); $oLdap=new imlldap($aConfig['ldap']);
```
## Methods
### Object handling
* objAdd(string $sDn, array $aItem): bool
* objGet(string $sDn, string $sSearchFilter = '(objectclass=*)', array $aAttributesToGet = ["*"]): bool|array
* objUpdate(string $sDn, array $aItem): bool
* objDelete(string $sDn): bool
### Attributes
* objAddAttr(string $sDn, array $aItem): bool
* objDeleteAttr(string $sDn, array $aItem): bool
* objectAttributeExists(string $sDn, string $sAttribute): bool
* objectAttributeAndValueExist(string $sDn, string $sAttribute, string $sAttrValue): bool - check only
* objectAttributeAndValueMustExist(string $sDn, string $sAttribute, string $sAttrValue): bool - force the existence of attribute and value
### User functions
* userAdd(array $aItem, string $sDn = "")
* getUserInfo(string $sUser, array $aAttributesToGet = ["*"]): bool|array
* userDelete(string $sUserDn)
* userUpdate(array $aItem)
* setPassword(string $sUser, string $sPW): bool
* verifyPassword(string $sUser, string $sPW): bool
### Debugging
Turn debugging on or off
// set values from $_FORM or $_POST data of your login form here * debugOff()
// The variable $bAuthenticated is true if authentication of the user was successful. * debugOn()
$bAuthenticated=oLdap->verifyPassword($sUser, $sPassword);
## Examples
### read user attributes
Use the username or an email address to get user data. The 2nd parameter defines the attributes to fetch (`["*"]` is default).
```php
$aUser = $oLdap->getUserInfo("john@example.com", []);
$aUser = $oLdap->getUserInfo("john@example.com", ["memberof", "uid"]);
// simplify result array:
print_r($oLdap->normalizeSearchentry($aUser));
```
### Example: search
When using special chars in search then you can sanitize the search string.
```php
$sCn = 'John Smith (john)';
$sSearchFilter = '(cn='.$oLdap->sanitizeFilter($sCn).')';
$aResults = $oLdap->searchDn("<DN here>", $sSearchFilter, ["*"]);
$oLdap->close();
``` ```
docs/30_Methods.md
+ 64
− 71
View file @ 9f0ee42a
...@@ -5,19 +5,28 @@ ...@@ -5,19 +5,28 @@
--- ---
## `class imlldap` ## `class imlldap`
IML LDAP CONNECTOR *<pre> 2022-02-22 ah added objGet(), sanitizeFilter() <br> 2022-08-18 ah mask password (showing 4 chars only) <br> 2022-08-22 ah mhash is deprecated <br> 2022-08-26 ah fix verifyPassword <br> </pre> IML LDAP CONNECTOR
2022-02-22 ah added objGet(), sanitizeFilter() 2022-08-18 ah mask password (showing 4 chars only) 2022-08-22 ah mhash is deprecated 2022-08-26 ah fix verifyPassword 2024-07-11 ah php8 only: use variable types
--- ---
## `private $_aLdap = array( 'server' => false, 'port' => false, 'DnLdapUser' => false, // ldap rdn oder dn 'PwLdapUser' => false, 'DnUserNode' => false, // ou=People... 'DnAppNode' => false, // cn=AppGroup... 'protoVersion' => 3, 'debugLevel' => 0, )` ## `private array $_aLdap = [ 'server' => false, 'port' => false, 'DnLdapUser' => false, // ldap rdn oder dn 'PwLdapUser' => false, 'DnUserNode' => false, // ou=People... 'DnAppNode' => false, // cn=AppGroup... 'protoVersion' => 3, 'debugLevel' => 0, ]`
--- ---
## `private $_ldapConn = false` ## `private object|bool $_ldapConn = false`
--- ---
## `private $_ldapBind = false` ## `private object|bool $_ldapBind = false`
ldap bind object - bind was done?
--- ---
## `public function __construct($aConfig = array())` ## `var bool $bDebug = false`
Flag if debug mode is on
---
## `public function __construct(array $aConfig = [])`
constructor constructor
**Parameters:** **Parameters:**
...@@ -27,17 +36,17 @@ Var | Type | Desciption ...@@ -27,17 +36,17 @@ Var | Type | Desciption
$aConfig | array | optional set ldap connection $aConfig | array | optional set ldap connection
--- ---
## `public function debugOn()` ## `public function debugOn(): void`
turn debug messages on; if this detail level is not enough, set a value with key debugLevel in ldap config array turn debug messages on; if this detail level is not enough, set a value with key debugLevel in ldap config array
--- ---
## `public function debugOff()` ## `public function debugOff(): void`
turn debug messages off turn debug messages off
--- ---
## `private function _w($sText)` ## `private function _w(string $sText): bool`
write debug message if denugOn() was fired. write debug message if denugOn() was fired.
...@@ -52,7 +61,7 @@ $sText | string | message text ...@@ -52,7 +61,7 @@ $sText | string | message text
boolean boolean
--- ---
## `private function _wLdaperror($sText = '')` ## `private function _wLdaperror(string $sText = ''): bool`
write last ldap error as debug write last ldap error as debug
...@@ -67,7 +76,7 @@ $sText | string | message text ...@@ -67,7 +76,7 @@ $sText | string | message text
boolean boolean
--- ---
## `public function setConfig($aConfig = array())` ## `public function setConfig(array $aConfig = []): void`
set a ldap config set a ldap config
...@@ -87,17 +96,17 @@ Var | Type | Desciption ...@@ -87,17 +96,17 @@ Var | Type | Desciption
$aConfig | array | new config items $aConfig | array | new config items
--- ---
## `public function close()` ## `public function close(): void`
close an existing ldap connection close an existing ldap connection
--- ---
## `public function connect()` ## `public function connect(): void`
connect to ldap connect to ldap
--- ---
## `public function bind($sUser = '', $sPw = '')` ## `public function bind(string $sUser = '', string $sPw = ''): bool`
ldap bind connects with a ldap user. If the ldap connection was not opened yet the connection will be established. If a binding exists it will be unbind ldap bind connects with a ldap user. If the ldap connection was not opened yet the connection will be established. If a binding exists it will be unbind
...@@ -109,12 +118,12 @@ $sUser | string | optional: username (overrides _aLdap['DnLdapUser']) ...@@ -109,12 +118,12 @@ $sUser | string | optional: username (overrides _aLdap['DnLdapUser'])
$sPw | string | optional: password (overrides _aLdap['PwLdapUser']) $sPw | string | optional: password (overrides _aLdap['PwLdapUser'])
--- ---
## `public function unbind()` ## `public function unbind(): void`
ldap unbind ... if a bind exists ldap unbind ... if a bind exists
--- ---
## `public function DnExists($sDn)` ## `public function DnExists(string $sDn): bool`
check if a DN already exists; return is true/ false check if a DN already exists; return is true/ false
**Parameters:** **Parameters:**
...@@ -128,37 +137,22 @@ $sDn | string | DN to check ...@@ -128,37 +137,22 @@ $sDn | string | DN to check
boolean boolean
--- ---
## `public function normalizeSearchentry($aRecord)` ## `public function normalizeSearchentry(array $aRecord): bool|array`
get simpler array from ldap_get_entries after ldap_search get simpler array from ldap_get_entries after ldap_search If the given array doesn't contain the key "dn" it returns "false"
**Parameters:** **Parameters:**
Var | Type | Desciption Var | Type | Desciption
-- |-- |-- -- |-- |--
$aRecord | array | singel result item $aRecord | array | single result item
**Return:** **Return:**
array array
--- ---
## `public function normalizeSearchresult($aLdapSearchresult)` ## `static public function sanitizeFilter(string $s): string`
get simpler array from ldap_get_entries after ldap_search
**Parameters:**
Var | Type | Desciption
-- |-- |--
$aRecord | array | singel result item
**Return:**
array
---
## `static public function sanitizeFilter($s)`
sanitize value to put into a search filter WARNING: the implementation is incomplete! I replaces the first N ascii chars only sanitize value to put into a search filter WARNING: the implementation is incomplete! I replaces the first N ascii chars only
...@@ -176,9 +170,9 @@ $s | string | value to sanitize ...@@ -176,9 +170,9 @@ $s | string | value to sanitize
string string
--- ---
## `public function searchDn($sDn, $sSearchFilter='(objectclass=*)', $aAttributesToGet = array("*"), $bRecursive=true)` ## `public function searchDn(string $sDn, string $sSearchFilter = '(objectclass=*)', array $aAttributesToGet = ["*"], bool $bRecursive = true): bool|array`
search in ldap directory and get result as array search in ldap directory and get result as array. It returns "false" on error: - no ldap connection - search failed
**Parameters:** **Parameters:**
...@@ -191,10 +185,10 @@ $bRecursive | boolean | recusrive (uses ldap_search) or not (ldap_list) ...@@ -191,10 +185,10 @@ $bRecursive | boolean | recusrive (uses ldap_search) or not (ldap_list)
**Return:** **Return:**
array boolean|array
--- ---
## `public function searchUser($sSearchFilter='', $aAttributesToGet = array("*"), $bRecursive=true)` ## `public function searchUser(string $sSearchFilter = '', array $aAttributesToGet = ["*"], bool $bRecursive = true): bool|array`
search for entries in in ldap user node and get result as array search for entries in in ldap user node and get result as array
...@@ -208,10 +202,10 @@ $bRecursive | bool | flag: recursive search? default: true (=yes, recursive) ...@@ -208,10 +202,10 @@ $bRecursive | bool | flag: recursive search? default: true (=yes, recursive)
**Return:** **Return:**
array boolean|array
--- ---
## `public function getUserInfo($sUser, $aAttributesToGet = array("*"))` ## `public function getUserInfo(string $sUser, array $aAttributesToGet = ["*"]): bool|array`
search user by a given username or email address. It returns false if the user does not exist or is not member of the group 'DnAppNode' (if it was set). search user by a given username or email address. It returns false if the user does not exist or is not member of the group 'DnAppNode' (if it was set).
...@@ -219,15 +213,15 @@ search user by a given username or email address. It returns false if the user d ...@@ -219,15 +213,15 @@ search user by a given username or email address. It returns false if the user d
Var | Type | Desciption Var | Type | Desciption
-- |-- |-- -- |-- |--
$sUser | type | user id (uid) or email (mail) to search $sUser | string | user id (uid) or email (mail) to search
$aAttributesToGet | type | i.e. array("ou", "sn", "vorname", "mail", "uid", "memberOf") $aAttributesToGet | array | i.e. ["ou", "sn", "vorname", "mail", "uid", "memberOf"]
**Return:** **Return:**
boolean|array boolean|array
--- ---
## `public function getUserDn($sUser)` ## `public function getUserDn(string $sUser): bool|string`
search for a DN entry with the lookup user by a given username or email address. It returns false if the user does not exist or is not member of the group 'DnAppNode' (if it was set). search for a DN entry with the lookup user by a given username or email address. It returns false if the user does not exist or is not member of the group 'DnAppNode' (if it was set).
...@@ -235,14 +229,14 @@ search for a DN entry with the lookup user by a given username or email address. ...@@ -235,14 +229,14 @@ search for a DN entry with the lookup user by a given username or email address.
Var | Type | Desciption Var | Type | Desciption
-- |-- |-- -- |-- |--
$sUser | type | %s $sUser | string | %s
**Return:** **Return:**
string string
--- ---
## `public function setPassword($sUser, $sPW)` ## `public function setPassword(string $sUser, string $sPW): bool`
set a password for a given user; this requires a ldap bind with master/ admin account set a password for a given user; this requires a ldap bind with master/ admin account
...@@ -258,7 +252,7 @@ $sPW | string | password ...@@ -258,7 +252,7 @@ $sPW | string | password
boolean boolean
--- ---
## `private function _getNTLMHash($Input)` ## `private function _getNTLMHash(string $Input): string`
get NTLM hash from a string taken from https://secure.php.net/manual/en/ref.hash.php get NTLM hash from a string taken from https://secure.php.net/manual/en/ref.hash.php
...@@ -273,7 +267,7 @@ $Input | string | %s ...@@ -273,7 +267,7 @@ $Input | string | %s
string string
--- ---
## `public function setPasswordSamba($sUser, $sPW)` ## `public function setPasswordSamba(string $sUser, string $sPW): bool`
set a password for a given user for Samba this requires a ldap bind with master/ admin account see https://msdn.microsoft.com/en-us/library/cc223248.aspx see http://php.net/ldap-modify-batch - last examle see https://secure.php.net/manual/en/ref.hash.php set a password for a given user for Samba this requires a ldap bind with master/ admin account see https://msdn.microsoft.com/en-us/library/cc223248.aspx see http://php.net/ldap-modify-batch - last examle see https://secure.php.net/manual/en/ref.hash.php
...@@ -289,23 +283,23 @@ $sPW | string | password ...@@ -289,23 +283,23 @@ $sPW | string | password
boolean boolean
--- ---
## `public function objAdd($sDn, $aItem)` ## `public function objAdd(string $sDn, array $aItem): bool`
update an ldap object this requires a ldap bind with master/ admin account update an ldap object this requires a ldap bind with master/ admin account It returns true if the action was successful
**Parameters:** **Parameters:**
Var | Type | Desciption Var | Type | Desciption
-- |-- |-- -- |-- |--
$sDn | string | dn to update $sDn | string | dn to update
$aItem | string | array of new ldap properties $aItem | array | array of new ldap properties
**Return:** **Return:**
boolean boolean
--- ---
## `public function objAddAttr($sDn, $aItem)` ## `public function objAddAttr(string $sDn, array $aItem): bool`
update an ldap attribute this requires a ldap bind with master/ admin account update an ldap attribute this requires a ldap bind with master/ admin account
...@@ -314,16 +308,16 @@ update an ldap attribute this requires a ldap bind with master/ admin account ...@@ -314,16 +308,16 @@ update an ldap attribute this requires a ldap bind with master/ admin account
Var | Type | Desciption Var | Type | Desciption
-- |-- |-- -- |-- |--
$sDn | string | dn to update $sDn | string | dn to update
$aItem | string | array of new ldap properties $aItem | array | array of new ldap properties
**Return:** **Return:**
boolean boolean
--- ---
## `public function objGet($sDn, $sSearchFilter='(objectclass=*)', $aAttributesToGet = array("*"))` ## `public function objGet(string $sDn, string $sSearchFilter = '(objectclass=*)', array $aAttributesToGet = ["*"]): bool|array`
read attributes from ldap node with given DN (using ldap_read) read attributes from ldap node with given DN (using ldap_read) It returns "false" if the action was not successful - no ldap connection - DN or filter didn't match
**Parameters:** **Parameters:**
...@@ -335,12 +329,12 @@ $aAttributesToGet | array | flat array of attributes to fetch ...@@ -335,12 +329,12 @@ $aAttributesToGet | array | flat array of attributes to fetch
**Return:** **Return:**
array boolean|array
--- ---
## `public function objUpdate($sDn, $aItem)` ## `public function objUpdate(string $sDn, array $aItem): bool`
update an ldap object with given key-value array if the attribute (key) does not exist it will be created. this requires a ldap bind with master/ admin account update an ldap object with given key-value array if the attribute (key) does not exist it will be created. this requires a ldap bind with master/ admin account It returns "false" if the action failed
**Parameters:** **Parameters:**
...@@ -354,9 +348,9 @@ $aItem | array | updated entry ...@@ -354,9 +348,9 @@ $aItem | array | updated entry
boolean boolean
--- ---
## `public function objDelete($sDn)` ## `public function objDelete(string $sDn): bool`
delete an ldap object this requires a ldap bind with master/ admin account delete an ldap object this requires a ldap bind with master/ admin account It returns "false" if the action failed
**Parameters:** **Parameters:**
...@@ -369,25 +363,24 @@ $sDn | string | full DN to remove ...@@ -369,25 +363,24 @@ $sDn | string | full DN to remove
boolean boolean
--- ---
## `public function objDeleteAttr($sDn, $aItem)` ## `public function objDeleteAttr(string $sDn, array $aItem): bool`
delete attributes of an ldap object this requires a ldap bind with master/ admin account
TODO: Test me delete attributes of an ldap object this requires a ldap bind with master/ admin account It returns "false" if the action failed
remove attribute "userPassword" of user $sUserDn: <code>$oLdap->objDeleteAttr($sUserDn, ['userPassword'=>[]]</code>
**Parameters:** **Parameters:**
Var | Type | Desciption Var | Type | Desciption
-- |-- |-- -- |-- |--
$sDn | string | DN $sDn | string | DN
$aItem | string | item to remove $aItem | array | item to remove
**Return:** **Return:**
boolean boolean
--- ---
## `public function objectAttributeExists($sDn, $sAttribute)` ## `public function objectAttributeExists(string $sDn, string $sAttribute): bool`
check if an attribute exists in a DN check if an attribute exists in a DN
...@@ -404,7 +397,7 @@ $sAttrValue | string | value to check ...@@ -404,7 +397,7 @@ $sAttrValue | string | value to check
boolean boolean
--- ---
## `public function objectAttributeAndValueExist($sDn, $sAttribute, $sAttrValue)` ## `public function objectAttributeAndValueExist(string $sDn, string $sAttribute, string $sAttrValue): bool`
check if an attribute and value exist in a DN check if an attribute and value exist in a DN
...@@ -421,7 +414,7 @@ $sAttrValue | string | value to check ...@@ -421,7 +414,7 @@ $sAttrValue | string | value to check
boolean boolean
--- ---
## `public function objectAttributeAndValueMustExist($sDn, $sAttribute, $sAttrValue)` ## `public function objectAttributeAndValueMustExist(string $sDn, string $sAttribute, string $sAttrValue): bool`
check an attribute and value; it will be created if it does not exist this requires a ldap bind with master/ admin account check an attribute and value; it will be created if it does not exist this requires a ldap bind with master/ admin account
...@@ -438,7 +431,7 @@ $sAttrValue | string | value to check ...@@ -438,7 +431,7 @@ $sAttrValue | string | value to check
boolean boolean
--- ---
## `public function userAdd($aItem, $sDn = false)` ## `public function userAdd(array $aItem, string $sDn = ""): bool`
create a new user item this requires a ldap bind with master/ admin account create a new user item this requires a ldap bind with master/ admin account
...@@ -454,7 +447,7 @@ $sDn | string | optional DN where to create the user ...@@ -454,7 +447,7 @@ $sDn | string | optional DN where to create the user
boolean boolean
--- ---
## `public function userDelete($sUserDn)` ## `public function userDelete(string $sUserDn): bool`
delete a user this requires a ldap bind with master/ admin account delete a user this requires a ldap bind with master/ admin account
...@@ -470,7 +463,7 @@ $sPW | string | new password to set ...@@ -470,7 +463,7 @@ $sPW | string | new password to set
boolean boolean
--- ---
## `public function userUpdate($aItem)` ## `public function userUpdate(array $aItem): bool`
update an ldap object this requires a ldap bind with master/ admin account update an ldap object this requires a ldap bind with master/ admin account
...@@ -485,7 +478,7 @@ $aItem | array | new user data to update ...@@ -485,7 +478,7 @@ $aItem | array | new user data to update
boolean boolean
--- ---
## `public function verifyPassword($sUser, $sPW)` ## `public function verifyPassword(string $sUser, string $sPW): bool`
verify user and password verify user and password
**Parameters:** **Parameters:**
......
docs/_index.md
+ 6
− 5
View file @ 9f0ee42a
...@@ -5,12 +5,13 @@ A PHP class that I use ...@@ -5,12 +5,13 @@ A PHP class that I use
* for authentication of user logins * for authentication of user logins
* CRUD actions on ldap nodes * CRUD actions on ldap nodes
Institute for Medical Education; University of Bern 👤 Author: Axel Hahn; Institute for Medical Education; University of Bern
📄 Source: https://git-repo.iml.unibe.ch/iml-open-source/ldap-php-class
License: GNU GPL 3 📜 License: GNU GPL 3.0
📗 Docs: https://os-docs.iml.unibe.ch/ldap-php-class/
## Requirements ## Requirements
* PHP 7+ * PHP 8
* Php Ldap module * Php Ldap module
* OpenLdap server to connect * OpenLdap server / Active Directory to connect
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment