7x31/mailcow-dockerized
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[Web] Fix mailbox editing when password is unchanged, fix adding new administrator (fixes #4054, fixes #4053); [Web] Update libs, add LDAP for future admin/domain admin authentication

Browse Source
This commit is contained in:
andryyy
2021-04-13 21:34:47 +02:00
parent 75c313ca92
commit 19843cc786
1623 changed files with 131949 additions and 2288 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
data/web/inc/lib/vendor/adldap2/adldap2/docs/.nojekyll vendored Normal file
View File

16
data/web/inc/lib/vendor/adldap2/adldap2/docs/_coverpage.md vendored Normal file
View File

@@ -0,0 +1,16 @@
<!-- _coverpage.md -->
# Adldap2
<p align="center">
<a href="https://travis-ci.org/Adldap2/Adldap2"><img src="https://img.shields.io/travis/Adldap2/Adldap2.svg?style=flat-square"/></a>
<a href="https://scrutinizer-ci.com/g/Adldap2/Adldap2/?branch=master"><img src="https://img.shields.io/scrutinizer/g/adLDAP2/adLDAP2/master.svg?style=flat-square"/></a>
<a href="https://packagist.org/packages/adldap2/adldap2"><img src="https://img.shields.io/packagist/dt/adldap2/adldap2.svg?style=flat-square"/></a>
<a href="https://packagist.org/packages/adldap2/adldap2"><img src="https://img.shields.io/packagist/v/adldap2/adldap2.svg?style=flat-square"/></a>
<a href="https://packagist.org/packages/adldap2/adldap2"><img src="https://img.shields.io/packagist/l/adldap2/adldap2.svg?style=flat-square"/></a>
</p>
> Working with LDAP doesn't need to be hard.
<!-- background image -->
![](media/bg.svg)

27
data/web/inc/lib/vendor/adldap2/adldap2/docs/_sidebar.md vendored Normal file
View File

@@ -0,0 +1,27 @@
<!-- _sidebar.md -->
* Getting Started
* [Introduction](/)
* [Installation](installation.md)
* [Setup](setup.md)
* Usage
* [Searching](searching.md)
* [Creating & Updating](models/model.md)
* [Events](events.md)
* [Logging](logging.md)
* [Working With Distiguished Names](distinguished-names.md)
* [Troubleshooting](troubleshooting.md)
* Models
* [Model (Base)](models/model.md)
* [Computer](models/computer.md)
* [Contact](models/contact.md)
* [Container](models/container.md)
* [Group](models/group.md)
* [Organizational Unit](models/ou.md)
* [Printer](models/printer.md)
* [RootDse](models/root-dse.md)
* [User](models/user.md)

167
data/web/inc/lib/vendor/adldap2/adldap2/docs/distinguished-names.md vendored Normal file
View File

@@ -0,0 +1,167 @@
## Working With Distinguished Names
Working with DN strings are a pain, but they're about to get easier. Adldap includes a DN builder for easily modifying and
creating DN strings.
> **Note**: All values inserted into DN methods are escaped. You do not need to escape **any** values before hand.
#### Creating a New DN
To create a new DN, construct a new `Adldap\Models\Attributes\DistinguishedName` instance:
```php
$dn = new Adldap\Models\Attributes\DistinguishedName();
```
You can also pass in a current DN string and start modifying it:
```php
$currentDn = 'cn=John Doe,ou=Accounting,dc=corp,dc=acme,dc=org';
$dn = new Adldap\Models\Attributes\DistinguishedName($currentDn);
```
#### Adding / Removing a Domain Component
```php
// Add Domain Component
$dn->addDc('corp');
// Remove Domain Component
$dn->removeDc('corp');
```
#### Adding / Removing an Organizational Unit
```php
// Add Organizational Unit
$dn->addOu('Accounting');
// Remove Organizational Unit
$dn->removeOu('Accounting');
```
#### Adding / Removing Common Names
```php
// Add Common Name
$dn->addCn('John Doe');
// Remove Common Name
$dn->removeCn('John Doe');
```
#### Setting a base
If you'd like to set the base DN, such as a domain component RDN, use the `setBase()` method:
```php
$base = 'dc=corp,dc=acme,dc=org';
$dn->setBase($base);
```
#### Creating a DN From A Model
When you're creating a new LDAP record, you'll need to create a distinguished name as well. Let's go through an example of
creating a new user.
```php
$user = $provider->make()->user();
$user->setCommonName('John Doe');
$user->setFirstName('John');
$user->setLastName('Doe');
```
So we've set the basic information on the user, but we run into trouble when we want to put the user into a certain container
(such as 'Accounting') which is done through the DN. Let's go through this example:
```php
$dn = $user->getDnBuilder();
$dn->addCn($user->getCommonName());
$dn->addOu('Accounting');
$dn->addDc('corp');
$dn->addDc('acme');
$dn->addDc('org');
// Returns 'cn=John Doe,ou=Accounting,dc=corp,dc=acme,dc=org'
echo $dn->get();
// The DistinguishedName object also contains the __toString() magic method
// so you can also just echo the object itself
echo $dn;
```
Now we've built a DN, and all we have to do is set it on the new user:
```php
$user->setDn($dn);
$user->save();
```
#### Modifying a DN From A Model
When you've received a model from a search result, you can build and modify the models DN like so:
```php
$user = $ad->users()->find('jdoe');
$dn = $user->getDnBuilder();
$dn->addOu('Users');
$user->setDn($dn)->save();
```
#### Retrieving the RDN components
To retrieve all of the RDN components of a Distinguished Name, call `getComponents()`:
```php
$dn = new Adldap\Models\Attributes\DistinguishedName(
'cn=John Doe,ou=Accounting,dc=corp,dc=acme,dc=org'
);
$components = $dn->getComponents();
var_dump($components);
// Output:
// array:5 [▼
// "cn" => array:1 [▼
// 0 => "John Doe"
// ]
// "uid" => []
// "ou" => array:1 [▼
// 0 => "Accounting"
// ]
// "dc" => array:3 [▼
// 0 => "corp"
// 1 => "acme"
// 2 => "org"
// ]
// "o" => []
// ]
```
You can also specify a component you would like returned by supplying it as an argument:
```php
$dn = new Adldap\Models\Attributes\DistinguishedName(
'cn=John Doe,ou=Accounting,dc=corp,dc=acme,dc=org'
);
$dcs = $dn->getComponents('dc');
var_dump($dcs);
// Output:
// array:3 [▼
// 0 => "corp"
// 1 => "acme"
// 2 => "org"
// ]
```

175
data/web/inc/lib/vendor/adldap2/adldap2/docs/events.md vendored Normal file
View File

@@ -0,0 +1,175 @@
# Events
Adldap2 events provide a method of listening for certain LDAP actions
that are called and execute tasks for that specific event.
> **Note**: The Adldap2 event dispatcher was actually derived from the
> [Laravel Framework](https://github.com/laravel/framework) with
> Broadcasting & Queuing omitted to remove extra dependencies
> that would be required with implementing those features.
>
> If you've utilized Laravel's events before, this will feel very familiar.
## Registering Listeners
> **Note**: Before we get to registering listeners, it's crucial to know that events throughout
> Adldap2 are fired irrespective of the current connection or provider in use.
>
> This means that when using multiple LDAP connections, the same events will be fired.
>
> This allows you to set listeners on events that occur for all LDAP connections you utilize.
>
> If you are required to determine which events are fired from alternate connections, see [below](#determining-the-connection).
To register a listener on an event, retrieve the event dispatcher and call the `listen()` method:
```php
use Adldap\Auth\Events\Binding;
$dispatcher = \Adldap\Adldap::getEventDispatcher();
$dispatcher->listen(Binding::class, function (Binding $event) {
// Do something with the Binding event information:
$event->connection; // Adldap\Connections\Ldap instance
$event->username; // 'jdoe@acme.org'
$event->password; // 'super-secret'
});
```
The first argument is the event name you would like to listen for, and the
second is either a closure or class name that should handle the event:
Using a class:
> **Note**: When using just a class name, the class must contain a public `handle()` method that will handle the event.
```php
use Adldap\Adldap;
use Adldap\Auth\Events\Binding;
$dispatcher = Adldap::getEventDispatcher();
$dispatcher->listen(Binding::class, MyApp\BindingEventHandler::class);
```
```php
namespace MyApp;
use Adldap\Auth\Events\Binding;
class BindingEventHandler
{
public function handle(Binding $event)
{
// Handle the event...
}
}
```
## Model Events
Model events are handled the same way as authentication events.
Simply call the event dispatcher `listen()` method with the model event you are wanting to listen for:
```php
use Adldap\Models\Events\Saving;
$dispatcher = \Adldap\Adldap::getEventDispatcher();
$dispatcher->listen(Saving::class, function (Saving $event) {
// Do something with the Saving event information:
// Returns the model instance being saved eg. `Adldap\Models\Entry`
$event->getModel();
});
```
## Wildcard Event Listeners
You can register listeners using the `*` as a wildcard parameter to catch multiple events with the same listener.
Wildcard listeners will receive the event name as their first argument, and the entire event data array as their second argument:
```php
$dispatcher = Adldap::getEventDispatcher();
// Listen for all model events.
$dispatcher->listen('Adldap\Models\Events\*', function ($eventName, array $data) {
echo $eventName; // Returns 'Adldap\Models\Events\Updating'
var_dump($data); // Returns [0] => (object) Adldap\Models\Events\Updating;
});
$user = $provider->search()->users()->find('jdoe');
$user->setTelephoneNumber('555 555-5555');
$user->save();
```
## Determining the Connection
If you're using multiple LDAP connections and you require the ability to determine which events belong
to a certain connection, you can do so by verifying the host of the LDAP connection.
Here's an example:
```php
$dispatcher = Adldap::getEventDispatcher();
$dispatcher->listen(\Adldap\Models\Events\Creating::class, function ($event) {
$connection = $event->model->getConnection();
$host = $connection->getHost();
echo $host; // Displays 'ldap://192.168.1.1:386'
});
```
Another example with auth events:
```php
$dispatcher = Adldap::getEventDispatcher();
$dispatcher->listen(\Adldap\Auth\Events\Binding::class, function ($event) {
$connection = $event->connection;
$host = $connection->getHost();
echo $host; // Displays 'ldap://192.168.1.1:386'
});
```
## List of Events
### Authentication Events
There are several events that are fired during initial and subsequent binds to your configured LDAP server.
Here is a list of all events that are fired:
| Event| Description |
|---|---|
| Adldap\Auth\Events\Attempting | When any authentication attempt is called via: `$provider->auth()->attempt()` |
| Adldap\Auth\Events\Passed | When any authentication attempts pass via: `$provider->auth()->attempt()` |
| Adldap\Auth\Events\Failed | When any authentication attempts fail via: `$provider->auth()->attempt()` *Or* `$provider->auth()->bind()` |
| Adldap\Auth\Events\Binding | When any LDAP bind attempts occur via: `$provider->auth()->attempt()` *Or* `$provider->auth()->bind()` |
| Adldap\Auth\Events\Bound | When any LDAP bind attempts are successful via: `$provider->auth()->attempt()` *Or* `$provider->auth()->bind()` |
### Model Events
There are several events that are fired during the creation, updating and deleting of all models.
Here is a list of all events that are fired:
| Event | Description |
|---|---|
| Adldap\Models\Events\Saving | When a model is in the process of being saved via: `$model->save()` |
| Adldap\Models\Events\Saved | When a model has been successfully saved via: `$model->save()` |
| Adldap\Models\Events\Creating | When a model is being created via: `$model->save()` *Or* `$model->create()` |
| Adldap\Models\Events\Created | When a model has been successfully created via: `$model->save()` *Or* `$model->create()` |
| Adldap\Models\Events\Updating | When a model is being updated via: `$model->save()` *Or* `$model->update()` |
| Adldap\Models\Events\Updated | When a model has been successfully updated via: `$model->save()` *Or* `$model->update()` |
| Adldap\Models\Events\Deleting | When a model is being deleted via: `$model->delete()` |
| Adldap\Models\Events\Deleted | When a model has been successfully deleted via: `$model->delete()` |

35
data/web/inc/lib/vendor/adldap2/adldap2/docs/index.html vendored Normal file
View File

@@ -0,0 +1,35 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Adldap2 Documentation</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="description" content="Adldap2 Documentation">
<meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
<link rel="stylesheet" href="https://unpkg.com/docsify/lib/themes/vue.css">
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
name: 'Adldap2',
repo: 'https://github.com/Adldap2/Adldap2',
autoHeader: true,
auto2top: true,
homepage: 'readme.md',
coverpage: true,
search: 'auto',
loadSidebar: true,
subMaxLevel: 3
}
</script>
<script src="https://unpkg.com/docsify/lib/docsify.min.js"></script>
<script src="https://unpkg.com/prismjs/components/prism-php.min.js"></script>
<script src="https://unpkg.com/docsify/lib/plugins/search.min.js"></script>
</body>
</html>

29
data/web/inc/lib/vendor/adldap2/adldap2/docs/installation.md vendored Normal file
View File

@@ -0,0 +1,29 @@
# Requirements
Adldap2 requires the following:
- PHP 7.0 or greater
- LDAP extension enabled in PHP
- An LDAP server (ActiveDirectory, OpenLDAP, FreeIPA etc.)
# Composer
Adldap2 uses [Composer](https://getcomposer.org) for installation.
Once you have composer installed, run the following command in the root directory of your project:
```bash
composer require adldap2/adldap2
```
Then, if your application doesn't already require Composer's autoload, you will need to do it manually.
Insert this line at the top of your projects PHP script (usually `index.php`):
```php
require __DIR__ . '/vendor/autoload.php';
```
You're all set!
Now, head over to the [setup guide](setup.md) to get up and running.

74
data/web/inc/lib/vendor/adldap2/adldap2/docs/logging.md vendored Normal file
View File

@@ -0,0 +1,74 @@
# Logging
Adldap2 includes an implementation of PSR's widely supported [Logger](https://github.com/php-fig/log) interface.
By default, all of Adldap2's [events](events.md) will call the logger you have set to utilize.
> **Note**: Adldap2 does not include a file / text logger. You must implement your own.
## Registering & Enabling a Logger
To register a logger call `Adldap::setLogger()`. The logger must implement the `Psr\Log\LoggerInterface`.
>**Note**: Be sure to set the logger prior to creating a new `Adldap` instance. This
> ensures all events throughout the lifecycle of the request use your logger.
```php
use Adldap\Adldap;
Adldap::setLogger($myLogger);
$config = ['...'];
$ad = new Adldap();
$ad->addProvider($config);
```
## Disabling Logging
If you need to disable the event logger after a certain set of operations, simply pass in `null` and logging will be disabled:
```php
use Adldap\Adldap;
Adldap::setLogger($myLogger);
$config = ['...'];
$ad = new Adldap();
$ad->addProvider($config);
try {
$ad->connect();
// Disable logging anything else.
Adldap::setLogger(null);
} catch (\Adldap\Connections\BindException $e) {
//
}
```
## Logged Information
Here is a list of events that are logged along with the information included:
| Authentication Events | Logged |
|---|---|
| `Adldap\Auth\Events\Attempting` | `LDAP (ldap://192.168.1.1:389) - Operation: Adldap\Auth\Events\Attempting - Username: CN=Steve Bauman,OU=Users,DC=corp,DC=acme,DC=org` |
| `Adldap\Auth\Events\Binding` |` LDAP (ldap://192.168.1.1:389) - Operation: Adldap\Auth\Events\Binding - Username: CN=Steve Bauman,OU=Users,DC=corp,DC=acme,DC=org` |
| `Adldap\Auth\Events\Bound` | `LDAP (ldap://192.168.1.1:389) - Operation: Adldap\Auth\Events\Bound - Username: CN=Steve Bauman,OU=Users,DC=corp,DC=acme,DC=org` |
| `Adldap\Auth\Events\Passed` | `LDAP (ldap://192.168.1.1:389) - Operation: Adldap\Auth\Events\Passed - Username: CN=Steve Bauman,OU=Users,DC=corp,DC=acme,DC=org` |
| `Adldap\Auth\Events\Failed` | `LDAP (ldap://192.168.1.1:389) - Operation: Adldap\Auth\Events\Failed - Username: CN=Steve Bauman,OU=Users,DC=corp,DC=acme,DC=org - Result: Invalid Credentials` |
| Model Events | Logged |
|---|---|
| `Adldap\Models\Events\Saving` | `LDAP (ldap://192.168.1.1:389) - Operation: Saving - On: Adldap\Models\User - Distinguished Name: cn=John Doe,dc=acme,dc=org` |
| `Adldap\Models\Events\Saved` | `LDAP (ldap://192.168.1.1:389) - Operation: Saved - On: Adldap\Models\User - Distinguished Name: cn=John Doe,dc=acme,dc=org` |
| `Adldap\Models\Events\Creating` | `LDAP (ldap://192.168.1.1:389) - Operation: Creating - On: Adldap\Models\User - Distinguished Name: cn=John Doe,dc=acme,dc=org` |
| `Adldap\Models\Events\Created` | `LDAP (ldap://192.168.1.1:389) - Operation: Created - On: Adldap\Models\User - Distinguished Name: cn=John Doe,dc=acme,dc=org` |
| `Adldap\Models\Events\Updating` | `LDAP (ldap://192.168.1.1:389) - Operation: Updating - On: Adldap\Models\User - Distinguished Name: cn=John Doe,dc=acme,dc=org` |
| `Adldap\Models\Events\Updated` | `LDAP (ldap://192.168.1.1:389) - Operation: Updated - On: Adldap\Models\User - Distinguished Name: cn=John Doe,dc=acme,dc=org` |
| `Adldap\Models\Events\Deleting` | `LDAP (ldap://192.168.1.1:389) - Operation: Deleting - On: Adldap\Models\User - Distinguished Name: cn=John Doe,dc=acme,dc=org` |
| `Adldap\Models\Events\Deleted` | `LDAP (ldap://192.168.1.1:389) - Operation: Deleted - On: Adldap\Models\User - Distinguished Name: cn=John Doe,dc=acme,dc=org` |

1
data/web/inc/lib/vendor/adldap2/adldap2/docs/media/bg.svg vendored Normal file
View File

@@ -0,0 +1 @@
<svg xmlns='http://www.w3.org/2000/svg' width='100%' height='100%' viewBox='0 0 1600 800'><rect fill='#46ff55' width='1600' height='800'/><g ><path fill='#51ff76' d='M486 705.8c-109.3-21.8-223.4-32.2-335.3-19.4C99.5 692.1 49 703 0 719.8V800h843.8c-115.9-33.2-230.8-68.1-347.6-92.2C492.8 707.1 489.4 706.5 486 705.8z'/><path fill='#57ff94' d='M1600 0H0v719.8c49-16.8 99.5-27.8 150.7-33.5c111.9-12.7 226-2.4 335.3 19.4c3.4 0.7 6.8 1.4 10.2 2c116.8 24 231.7 59 347.6 92.2H1600V0z'/><path fill='#5affb1' d='M478.4 581c3.2 0.8 6.4 1.7 9.5 2.5c196.2 52.5 388.7 133.5 593.5 176.6c174.2 36.6 349.5 29.2 518.6-10.2V0H0v574.9c52.3-17.6 106.5-27.7 161.1-30.9C268.4 537.4 375.7 554.2 478.4 581z'/><path fill='#57ffcd' d='M0 0v429.4c55.6-18.4 113.5-27.3 171.4-27.7c102.8-0.8 203.2 22.7 299.3 54.5c3 1 5.9 2 8.9 3c183.6 62 365.7 146.1 562.4 192.1c186.7 43.7 376.3 34.4 557.9-12.6V0H0z'/><path fill='#50ffe8' d='M181.8 259.4c98.2 6 191.9 35.2 281.3 72.1c2.8 1.1 5.5 2.3 8.3 3.4c171 71.6 342.7 158.5 531.3 207.7c198.8 51.8 403.4 40.8 597.3-14.8V0H0v283.2C59 263.6 120.6 255.7 181.8 259.4z'/><path fill='#7dffe9' d='M1600 0H0v136.3c62.3-20.9 127.7-27.5 192.2-19.2c93.6 12.1 180.5 47.7 263.3 89.6c2.6 1.3 5.1 2.6 7.7 3.9c158.4 81.1 319.7 170.9 500.3 223.2c210.5 61 430.8 49 636.6-16.6V0z'/><path fill='#9effe9' d='M454.9 86.3C600.7 177 751.6 269.3 924.1 325c208.6 67.4 431.3 60.8 637.9-5.3c12.8-4.1 25.4-8.4 38.1-12.9V0H288.1c56 21.3 108.7 50.6 159.7 82C450.2 83.4 452.5 84.9 454.9 86.3z'/><path fill='#baffea' d='M1600 0H498c118.1 85.8 243.5 164.5 386.8 216.2c191.8 69.2 400 74.7 595 21.1c40.8-11.2 81.1-25.2 120.3-41.7V0z'/><path fill='#d2ffea' d='M1397.5 154.8c47.2-10.6 93.6-25.3 138.6-43.8c21.7-8.9 43-18.8 63.9-29.5V0H643.4c62.9 41.7 129.7 78.2 202.1 107.4C1020.4 178.1 1214.2 196.1 1397.5 154.8z'/><path fill='#e9ffeb' d='M1315.3 72.4c75.3-12.6 148.9-37.1 216.8-72.4h-723C966.8 71 1144.7 101 1315.3 72.4z'/></g></svg>

32
data/web/inc/lib/vendor/adldap2/adldap2/docs/models/computer.md vendored Normal file
View File

@@ -0,0 +1,32 @@
# The Computer Model
> **Note**: This model contains the traits `HasDescription`, `HasLastLogonAndLogOff` & `HasCriticalSystemObject`.
> For more information, visit the documentation:
>
> [HasDescription](/models/traits/has-description.md),
> [HasLastLogonAndLogOff](/models/traits/has-last-login-last-logoff.md),
> [HasCriticalSystemObject](/models/traits/has-critical-system-object.md)
## Methods
```php
$computer = $provider->search()->computers()->find('ACME-EXCHANGE');
// Returns 'Windows Server 2003'
$computer->getOperatingSystem();
// Returns '5.2 (3790)';
$computer->getOperatingSystemVersion();
// Returns 'Service Pack 1';
$computer->getOperatingSystemServicePack();
// Returns 'ACME-DESKTOP001.corp.acme.org'
$computer->getDnsHostName();
$computer->getLastLogOff();
$computer->getLastLogon();
$computer->getLastLogonTimestamp();
```

13
data/web/inc/lib/vendor/adldap2/adldap2/docs/models/contact.md vendored Normal file
View File

@@ -0,0 +1,13 @@
# The Contact Model
The Contact model extends from the base `Adldap\Models\Model` class and contains
no specific methods / attributes that are limited to it.
## Creation
```php
// Adldap\Models\Contact
$contact = $provider->make()->contact([
'cn' => 'Suzy Doe',
]);
```

24
data/web/inc/lib/vendor/adldap2/adldap2/docs/models/container.md vendored Normal file
View File

@@ -0,0 +1,24 @@
# The Container Model
> **Note**: This model contains the trait `HasDescription` & `HasCriticalSystemObject`.
> For more information, visit the documentation:
>
> [HasDescription](/models/traits/has-description.md),
> [HasCriticalSystemObject](/models/traits/has-critical-system-object.md),
## Creation
```php
// Adldap\Models\Container
$container = $provider->make()->container([
'cn' => 'VPN Users',
]);
```
## Methods
The `Container` model contains only one unique method.
```php
$flags = $container->getSystemFlags();
```

253
data/web/inc/lib/vendor/adldap2/adldap2/docs/models/group.md vendored Normal file
View File

@@ -0,0 +1,253 @@
# The Group Model
> **Note**: This model contains the trait `HasMemberOf`.
> For more information, visit the documentation:
>
> [HasMemberOf](/models/traits/has-member-of.md)
## Creation
```php
// Adldap\Models\Group
$group = $provider->make()->group([
'cn' => 'Managers',
]);
// Create group's DN through the DN Builder:
$group = $provider->make()->group();
$dn = $group->getDnBuilder();
$dn->addOu('Workstation Computers');
$dn->addCn("Managers");
$group->setDn($dn);
// Or set the DN manually:
$ou->setDn('cn=Managers,ou=Workstation Computers,dc=test,dc=local,dc=com');
$group->save();
```
## Getting a groups members
When you receive a `Group` model instance, it will contain a `member`
attribute which contains the distinguished names of all
the members inside the group.
```php
$group = $provider->search()->groups()->first();
foreach ($group->members as $member) {
echo $member; // 'cn=John Doe,dc=corp,dc=acme,dc=org'
}
```
But this might not be useful, since we might actually want the models for each member.
This can be easily done with the `getMembers()` method on the group.
```php
$group = $provider->search()->groups()->first();
foreach ($group->getMembers() as $member) {
echo get_class($member); // Instance of `Adldap\Models\Model`
echo $member->getCommonName();
}
```
> **Note**: You should be aware however, that calling the `getMembers()` method will
> query your `AD` server for **every** member contained in the group to retrieve
> its model. For larger group sets it may be worth paginating them.
### Paginating Group Members
The group you're looking for might contain hundreds / thousands of members.
In this case, your server might only return you a portion of the groups members.
To get around this limit, you need to ask your server to paginate the groups members through a select:
```php
$group = $provider->search()->groups()->select('member;range=0-500')->first();
foreach ($group->members as $member) {
// We'll only have 500 members in this query.
}
```
Now, when we have the group instance, we'll only have the first `500` members inside this group.
However, calling the `getMembers()` method will automatically retrieve the rest of the members for you:
```php
$group = $provider->search()->groups()->select('member;range=0-500')->first();
foreach ($group->getMembers() as $member) {
// Adldap will automatically retrieve the next 500
// records until it's retrieved all records.
$member->getCommonName();
}
```
> **Note**: Groups containing large amounts of users (1000+) will require
> more memory assigned to PHP. Your mileage will vary.
#### Paginating large sets of Group Members
When requesting group members from groups that contain a large amount of members
(typically over 1000), you may receive PHP memory limit errors due to
the large amount of the objects being created in the request.
To resolve this, you will need to retrieve the members manually. However using
this route you will only be able to retrieve the members distinguished names.
```php
$from = 0;
$to = 500;
$range = "member;range=$from-$to";
// Retrieve the group.
$group = $provider->search()->select($range)->raw()->find('Accounting');
// Remove the count from the member array.
unset($group[$range]['count']);
// The array of group members distinguished names.
$members = $group[$range];
foreach ($members as $member) {
echo $member; // 'cn=John Doe,dc=acme,dc=org'
}
```
You can then encapsulate the above example into a recursive function to retrieve the remaining group members.
## Getting only a groups member names
To retrieve only the names of the members contained in a group, call the `getMemberNames()` method:
```php
foreach ($group->getMemberNames() as $name) {
// Returns 'John Doe'
echo $name;
}
```
> **Note**: This method does not query your server for each member to retrieve its name. It
> only parses the distinguished names from the groups `member` attribute. This means that
> if you have paginated group members, you will need to perform another query yourself
> to retrieve the rest of the member names (or just call the `getMembers()` method).
## Setting Group Members
To set members that are apart of the group, you can perform this in two ways:
> **Note**: Remember, this will remove **all** pre-existing members, and set the new given members on the group.
```php
$members = [
'cn=John Doe,dc=corp,dc=acme,dc=org',
'cn=Jane Doe,dc=corp,dc=acme,dc=org',
];
$group->setMembers($members);
$group->save();
```
Or manually:
```php
$group->member = [
'cn=John Doe,dc=corp,dc=acme,dc=org',
'cn=Jane Doe,dc=corp,dc=acme,dc=org',
];
$group->save();
```
## Adding One Member
To add a single member to a group, use the `addMember()` method:
> **Note**: You do not need to call the `save()` method after adding a
> member. It's automatically called so you can determine
> if the member was successfully added.
```php
// We can provide a model, or just a plain DN of the new member
$user = $provider->search()->users()->first();
if ($group->addMember($user)) {
// User was successfully added to the group!
}
// Or
$user = 'cn=John Doe,dc=corp,dc=acme,dc=org';
if ($group->addMember($user)) {
//
}
```
## Adding Multiple Group Members
To add multiple members to a group, use the `addMembers()` method:
> **Note**: You do not need to call the `save()` method after adding
> members. It's automatically called so you can determine
> if the members were successfully added.
```php
$members = [
'cn=John Doe,dc=corp,dc=acme,dc=org',
'cn=Jane Doe,dc=corp,dc=acme,dc=org',
];
$group->addMembers($members);
// Or
$user = $provider->search()->users()->first();
if ($group->addMembers($user)) {
//
}
```
## Removing One Member
To remove a single member to a group, use the `removeMember()` method:
```php
// We can provide a model, or just a plain DN of the existing member
$group = $provider->search()->groups()->first();
$member = $group->getMembers()->first();
if ($group->removeMember($member)) {
// Member was successfully removed from the group!
}
// Or
$user = 'cn=John Doe,dc=corp,dc=acme,dc=org';
if ($group->removeMember($user)) {
//
}
```
## Removing All Members
To remove all members, use the `removeMembers()` method:
```php
if ($group->removeMembers()) {
// All members were successfully removed!
}
```

655
data/web/inc/lib/vendor/adldap2/adldap2/docs/models/model.md vendored Normal file
View File

@@ -0,0 +1,655 @@
# Creating / Updating
## Introduction
Adldap2 implements the [ActiveRecord](https://en.wikipedia.org/wiki/Active_record_pattern) pattern.
This means that each LDAP record in your directory is represented as it's own model instance.
## Creating
Creating LDAP entries manually is always a pain, but Adldap2 makes it effortless. Let's get started.
When you have a provider instance, call the `make()` method. This returns an `Adldap\Models\Factory` instance:
```php
$factory = $provider->make();
```
Or you can chain all methods if you'd prefer:
```php
$user = $provider->make()->user();
```
### Available Make Methods
When calling a make method, all of them accept an `$attributes` parameter
to fill the model with your specified attributes.
```php
// Adldap\Models\User
$user = $provider->make()->user([
'cn' => 'John Doe',
]);
// Adldap\Models\Computer
$computer = $provider->make()->computer([
'cn' => 'COMP-101',
]);
// Adldap\Models\Contact
$contact = $provider->make()->contact([
'cn' => 'Suzy Doe',
]);
// Adldap\Models\Container
$container = $provider->make()->container([
'cn' => 'VPN Users',
]);
// Adldap\Models\Group
$group = $provider->make()->group([
'cn' => 'Managers',
]);
// Adldap\Models\OrganizationalUnit
$ou = $provider->make()->ou([
'name' => 'Acme',
]);
```
## Saving
When you have any model instance, you can call the `save()` method to persist the
changes to your server. This method returns a `boolean`. For example:
```php
$user = $provider->make()->user([
'cn' => 'New User',
]);
if ($user->save()) {
// User was saved.
} else {
// There was an issue saving this user.
}
```
> **Note**: When a model is saved successfully (whether created or updated), the
> models attributes are re-synced in the background from your LDAP server.
>
> This allows you to perform other operations during the same
> request that require an existing model.
### Creating (Manually)
If you are sure the model **does not exist** already inside your LDAP directory, you can use the `create()` method:
```php
$user = $provider->make()->user([
'cn' => 'New User',
]);
if ($user->create()) {
// User was created.
} else {
// There was an issue creating this user.
}
```
> **Note**: When you call the create method, if the model does not have a
> distinguished name, one will automatically be generated for you using your
> `base_dn` set in your configuration and the models common name.
### Updating (Manually)
If you are sure the model **does exist** already inside your LDAP directory, you can use the `update()` method:
```php
$user = $provider->search()->whereEquals('cn', 'John Doe')->firstOrFail();
$user->displayName = 'Suzy Doe';
if ($user->update()) {
// User was updated.
} else {
// There was an issue updating this user.
}
```
## Checking Existence
If you need to check the existence of a model, use the property `exists`.
How does it know if the model exists in your LDAP directory? Well, when models are constructed from
search results, the `exists` property on the model is set to `true`.
```php
$user = $provider->search()->find('jdoe');
$user->exists; // Returns true.
if ($user->delete()) {
$user->exists; // Returns false.
}
```
If a model is created successfully, the `exists` property is set to `true`:
```php
$user = $provider->make()->user([
'cn' => 'John Doe',
]);
$user->exists; // Returns false.
if ($user->save()) {
$user->exists; // Returns true.
}
```
## Attributes
Due to LDAPs multi-valued nature, all LDAP attributes inside a model have their own array.
For example, a models attributes may contain the following:
```php
var_dump($user->getAttributes());
// Returns:
/*
[
'cn' => [
0 => 'John Doe',
],
'sn' => [
0 => 'Doe',
],
'givenname' => [
0 => 'John'
],
'useraccountcontrol' => [
0 => 512
],
'mail' => [
0 => 'jdoe@acme.org',
1 => 'john-doe@acme.org',
],
'memberof' => [
0 => 'cn=Accountants,ou=Groups,dc=acme,dc=org',
1 => 'cn=Employees,ou=Groups,dc=acme,dc=org',
2 => 'cn=Users,ou=Groups,dc=acme,dc=org',
],
]
*/
```
You can notice in the above dumped array that each attribute contains
its own array with a value assigned to the first key.
Since all models extend from the base class `Adldap\Models\Model`, there
are many useful methods that you can use on every model to easily
retrieve these attributes you're looking for.
### Getting Attributes
You can get attributes in a few ways:
```php
// Returns an array all of the users attributes.
$user->getAttributes();
// Returns an array of all the users email addresses.
// Returns `null` if non-existent.
$user->getAttribute('mail');
// Returns the users first email address.
// Returns `null` if non-existent.
$user->getAttribute('mail', 0);
// Returns the users first email address.
// Returns `null` if non-existent.
$user->getFirstAttribute('mail');
// Returns an array of all the users email addresses.
$user->mail;
// Returns the users first email address.
$user->mail[0];
```
#### Using a Getter
Some attributes have methods for easier retrieval so you don't need to look up the LDAP attribute name.
For example, to retrieve a users email address, use the method `getEmail()`:
```php
$user->getEmail();
```
##### Other Methods
The following methods are available on all returned models:
```php
// Returns the model's 'name' attribute.
$model->getName();
// Returns the model's 'cn' attribute.
$model->getCommonName();
// Returns the model's 'displayname' attribute.
$model->getDisplayName();
// Returns the model's 'samaccountname' attriubte.
$model->getAccountName();
// Returns the model's 'samaccounttype` attribute.
$model->getAccountType();
// Returns the model's 'whencreated` attribute.
$model->getCreatedAt();
// Returns the model's 'whencreated` attribute in a MySQL timestamp format.
$model->getCreatedAtDate();
// Returns the model's 'whencreated' attribute in unix time.
$model->getCreatedAtTimestamp();
// Returns the model's 'whenchanged` attribute.
$model->getUpdatedAt();
// Returns the model's 'whenchanged` attribute in a MySQL timestamp format.
$model->getUpdatedAtDate();
// Returns the model's 'whenchanged` attribute in unix time.
$model->getUpdatedAtTimestamp();
// Returns the model's 'objectclass' attribute.
$model->getObjectClass();
// Returns the model's root object category string.
$model->getObjectCategory();
// Returns the model's object category in an array.
$model->getObjectCategoryArray();
// Returns the model's object category distinguished name.
$model->getObjectCategoryDn();
// Returns the model's SID in binary.
$model->getObjectSid();
// Returns the model's GUID in binary.
$model->getObjectGuid();
// Returns the model's SID in a string.
$model->getConvertedSid();
// Returns the model's GUID in a string.
$model->getConvertedGuid();
// Returns the model's primary group ID.
$model->getPrimaryGroupId();
// Returns the model's 'instancetype' attribute.
$model->getInstanceType();
// Returns the model's 'maxpwdage' attribute.
$model->getMaxPasswordAge();
```
For more documentation on specific getters, please take a look at the relevant model documentation.
#### Getting Dirty (Modified) Attributes
You can get a models modified attributes using the `getDirty()` method:
```php
$user = $provider->search()->users()->find('john');
// Returns array [0 => 'John Doe']
var_dump($user->cn);
$user->setAttribute('cn', 'Jane Doe');
// Returns array ['cn' => [0 => 'Jane Doe']]
var_dump($user->getDirty());
// The attribute has been modified - returns array [0 => 'Jane Doe']
var_dump($user->cn);
```
The method returns an array with the key being the modified attribute,
and the array being the new values of the attribute.
#### Getting Original (Unmodified) Attributes
You can get a models original attributes using the `getOriginal()` method:
```php
$user = $provider->search()->users()->find('john');
// Returns array [0 => 'John Doe']
var_dump($user->cn);
$user->setAttribute('cn', 'Jane Doe');
// The attribute has been modified - returns array [0 => 'Jane Doe']
var_dump($user->cn);
// Retrieving the original value - returns array [0 => 'John Doe']
var_dump($user->getOriginal()['cn']);
```
> **Note**: Keep in mind, when you `save()` a model, the models original
> attributes will be re-synchronized to the models new attributes.
### Setting Attributes
Just like getting model attributes, there's multiple ways of setting attributes as well:
```php
// Setting via method:
$user->setAttribute('cn', 'John Doe');
// Specifying a subkey for overwriting specific attributes:
$user->setAttribute('mail', 'other-mail@mail.com', 0);
// Setting the first attribute:
$user->setFirstAttribute('mail', 'jdoe@mail.com');
// Setting via property:
$user->cn = 'John Doe';
// Mass setting attributes:
$user->fill([
'cn' => 'John Doe',
'mail' => 'jdoe@mail.com',
]);
```
#### Setting Boolean Attributes
When setting boolean attribute values, you cannot use `0` / `1` / `true` / `false` as these
are simply converted to integer values when saving and your LDAP server will
likely return an error for doing so on certain attributes.
You will need to use the string versions of the boolean (`'TRUE'` / `'FALSE'`) for the
boolean attribute to be set properly on your LDAP server.
Here's an example:
```php
$user->setFirstAttribute('msExchHideFromAddressLists', 'TRUE');
$user->save();
```
### Creating Attributes
To create an attribute that does not exist on the model, you can set it like a regular property:
```php
$user = $provider->search()->whereEquals('cn', 'John Doe')->firstOrFail();
$user->new = 'New Attribute';
$user->save();
```
If the set attribute does not exist on the model already,
it will automatically be created when you call the `save()` method.
If you'd like manually create new attributes individually, call the `createAttribute($attribute, $value)` method:
```php
if ($user->createAttribute('new', 'New Attribute')) {
// Attribute created.
}
```
### Updating Attributes
To modify an attribute you can either use a setter method, or by setting it manually:
> **Note**: You can also utilize setters to create new attributes if your model does not already have the attribute.
```php
$user = $provider->search()->whereEquals('cn', 'John Doe')->firstOrFail();
$user->cn = 'New Name';
// Or use a setter:
$user->setCommonName('New Name');
$user->save();
```
If you'd like to update attributes individually, call the `updateAttribute($attribute, $value)` method:
```php
if ($user->updateAttribute('cn', 'New Name')) {
// Successfully updated attribute.
}
```
### Removing Attributes
To remove attributes, set the attribute to `NULL`:
```php
$user->cn = null;
$user->save();
```
Or, you can call the `deleteAttribute($attribute)` method:
```php
if ($user->deleteAttribute('cn')) {
// Attribute has been deleted.
}
```
### Checking Attributes
#### Checking Existence of Attributes
To see if a model contains an attribute, use the method `hasAttribute()`:
```php
// Checking if a base attribute exists:
if ($user->hasAttribute('mail')) {
// This user contains an email address.
}
// Checking if a sub attribute exists, by key:
if ($user->hasAttribute('mail', 1)) {
// This user contains a second email address.
}
```
#### Counting the Models Attributes
To retrieve the total number of attributes, use the method `countAttributes()`:
```php
$count = $user->countAttributes();
var_dump($count); // Returns int
```
#### Checking if a Model is contained in an OU
To check if a model is located inside an OU, use the `inOu()` method:
```php
if ($model->inOu('User Accounts')) {
// This model is inside the 'User Accounts' OU.
}
```
You can also use an OU model instance:
```php
$serviceAccounts = $provider->search()->ous()->find('Service Accounts');
if ($model->inOu($serviceAccounts)) {
// This model is inside the 'Service Accounts' OU.
}
```
#### Checking if a Model is Writable
To check if the model can be written to, use the method `isWritable()`:
```php
if ($model->isWritable()) {
// You can modify this model.
}
```
### Force Re-Syncing A Models Attributes
If you need to forcefully re-sync a models attributes, use the method `syncRaw()`:
```php
$user->syncRaw();
```
> **Note**: This will query your LDAP server for the current model, and re-synchronize
> it's attributes. This is only recommended if your creating / updating / deleting
> attributes manually through your LDAP connection.
## Moving / Renaming
To move a user from one DN or OU to another, use the `move()` method:
> **Note**: The `move()` method is actually an alias for the `rename()` method.
```php
// New parent distiguished name.
$newParentDn = 'OU=New Ou,DC=corp,DC=local';
if ($user->move($newParentDn)) {
// User was successfully moved to the new OU.
}
```
You can also provide a model to move the child model into:
```php
// New parent OU.
$newParentOu = $provider->search()->ous()->find('Accounting');
if ($user->move($newParentOu)) {
// User was successfully moved to the new OU.
}
```
If you would like to keep the models old RDN along side their new RDN, pass in false in the second parameter:
```php
// New parent distiguished name.
$newParentDn = 'OU=New Ou,DC=corp,DC=local';
if ($user->move($newParentDn, $deleteOldRdn = false)) {
// User was successfully moved to the new OU,
// and their old RDN has been left in-tact.
}
```
To rename a users DN, just pass in their new relative distinguished name in the `rename()` method:
```php
$newRdn = 'cn=New Name';
if ($user->rename($newRdn)) {
// User was successfully renamed.
}
```
## Deleting
To delete a model, just call the `delete()` method:
```php
$user = $provider->search()->whereEquals('cn', 'John Doe')->firstOrFail();
echo $user->exists; // Returns true.
if ($user->delete()) {
// Successfully deleted user.
echo $user->exists; // Returns false.
}
```
## Extending
> **Note**: This feature was introduced in `v8.0.0`.
To use your own models, you will need to create a new [Schema](../schema.md).
Once you have created your own schema, you must insert it inside the construct of your provider.
Let's walk through this process.
First we'll create our model we'd like to extend / override:
> **Note**: Your custom model **must** extend from an existing Adldap2 model.
> This is due to methods and attributes that only exist on these classes.
```php
namespace App\Ldap\Models;
use Adldap\Models\User as Model;
class User extends Model
{
public function getCommonName()
{
// Overriding model method.
}
}
```
Now, we'll create our custom schema and return our models class name:
```php
namespace App\Ldap\Schemas;
use App\Ldap\Models\User;
class LdapSchema extends ActiveDirectory
{
public function userModel()
{
return User::class;
}
}
```
Finally, when we create a provider, we need to insert our Schema into the configuration:
```php
$config = [
'hosts' => ['...'],
'username' => 'admin',
'password' => 'P@ssword',
'schema' => MyApp\LdapSchema::class,
];
$ad = new Adldap($config);
$provider = $ad->connect();
// If `jdoe` exists, your custom model will be returned.
$user = $provider->search()->users()->find('jdoe');
```

19
data/web/inc/lib/vendor/adldap2/adldap2/docs/models/organization.md vendored Normal file
View File

@@ -0,0 +1,19 @@
# The Organization Model
The Organization model extends from the base `Adldap\Models\Model` class and contains
no specific methods / attributes that are limited to it.
## Creation
```php
// Adldap\Models\Organization
$org = $provider->make()->organization([
'o' => 'Some Company',
]);
// Set the DN manually:
$org->setDn('o=Some Company,dc=test,dc=local,dc=com');
$org->save();
```

27
data/web/inc/lib/vendor/adldap2/adldap2/docs/models/ou.md vendored Normal file
View File

@@ -0,0 +1,27 @@
# The OrganizationalUnit Model
The OrganizationalUnit model extends from the base `Adldap\Models\Model` class and contains
no specific methods / attributes that are limited to it.
## Creation
```php
// Adldap\Models\OrganizationalUnit
$ou = $provider->make()->ou([
'name' => 'Workstation Computers',
]);
// Generate the OU's DN through the DN Builder:
$dn = $ou->getDnBuilder();
$dn->addOu('Workstation Computers');
$ou->setDn($dn);
// Or set the DN manually:
$ou->setDn('ou=Workstation Computers,dc=test,dc=local,dc=com');
$ou->save();
```

49
data/web/inc/lib/vendor/adldap2/adldap2/docs/models/printer.md vendored Normal file
View File

@@ -0,0 +1,49 @@
# The Printer Model
## Methods
```php
$printer->getPrinterName();
$printer->getPrinterShareName();
$printer->getMemory();
$printer->getUrl();
$printer->getLocation();
$printer->getServerName();
$printer->getColorSupported();
$printer->getDuplexSupported();
$printer->getMediaSupported();
$printer->getStaplingSupported();
$printer->getPrintBinNames();
$printer->getPrintMaxResolution();
$printer->getPrintOrientations();
$printer->getDriverName();
$printer->getDriverVersion();
$printer->getPriority();
$printer->getPrintStartTime();
$printer->getPrintEndTime();
$printer->getPortName();
$printer->getVersionNumber();
$printer->getPrintRate();
$printer->getPrintRateUnit();
```

33
data/web/inc/lib/vendor/adldap2/adldap2/docs/models/root-dse.md vendored Normal file
View File

@@ -0,0 +1,33 @@
# The RootDse Model
## Getting the Root DSE
To get the Root DSE of your LDAP server, call the `getRootDse()` method off a new search:
```php
$rootDse = $provider->search()->getRootDse();
```
## Getting the schema naming context
To get the Root DSE schema naming context, call the `getSchemaNamingContext()`:
```php
$rootDse = $provider->search()->getRootDse();
$context = $rootDse->getSchemaNamingContext();
// Returns 'cn=Schema,cn=Configuration,dc=corp,dc=acme,dc=org'
echo $context;
```
## Getting the root domain naming context
To get the Root DSE domain naming context, call the `getRootDomainNamingContext()`:
```php
$context = $rootDse->getRootDomainNamingContext();
// Returns 'dc=corp,dc=acme,dc=org'
echo $context;
```

13
data/web/inc/lib/vendor/adldap2/adldap2/docs/models/traits/has-critical-system-object.md vendored Normal file
View File

@@ -0,0 +1,13 @@
# HasCriticalSystemObject Trait
Models that contain this trait, have the `isCriticalSystemObject` attribute.
There is only one method that accompanies this trait:
```php
if ($model->isCriticalSystemObject()) {
//
}
```

11
data/web/inc/lib/vendor/adldap2/adldap2/docs/models/traits/has-description.md vendored Normal file
View File

@@ -0,0 +1,11 @@
# HasDescription Trait
Models that contain this trait, have the `description` attribute.
There are only two methods that accompany this trait:
```php
$model->getDescription();
$model->setDescription('The models description');
```

16
data/web/inc/lib/vendor/adldap2/adldap2/docs/models/traits/has-last-login-last-logoff.md vendored Normal file
View File

@@ -0,0 +1,16 @@
# HasLastLoginAndLastLogoff Trait
Models that contain this trait have the `lastlogoff`, `lastlogon` and `lastlogontimestamp` attributes.
## Methods
```php
// Returns the models's last log off attribute.
$computer->getLastLogOff();
// Returns the models's last log on attribute.
$computer->getLastLogon();
// Returns the models's last log on timestamp attribute.
$computer->getLastLogonTimestamp();
```

166
data/web/inc/lib/vendor/adldap2/adldap2/docs/models/traits/has-member-of.md vendored Normal file
View File

@@ -0,0 +1,166 @@
# HasMemberOf Trait
Models that contain this trait, have the ability to be apart of a group.
There's many helpful methods to assist you in all of the operations related to group membership, let's get started!
## Retrieving Groups
To retrieve the groups that a model is apart of, call the `getGroups()` method:
```php
$user = $provider->search()->users()->find('jdoe');
$groups = $user->getGroups();
foreach ($groups as $group) {
$group->getCommonName(); // ex. 'Accounting'
}
```
We can also pass in specific fields we need from the returned groups to speed up our queries.
For example, if we only need the groups common name:
```php
// Group models will be returned with only their common name.
$groups = $user->getGroups(['cn']);
```
However, calling `getGroups()` will only retrieve the models immediate groups (non-recursive).
To retrieve nested groups, pass in `true` into the second parameter:
```php
$groups = $user->getGroups([], $recursive = true);
```
## Retrieve Group Names
If you only want the models group names, call the `getGroupNames()` method:
```php
$names = $user->getGroupNames();
foreach ($names as $name) {
echo $name; // ex. 'Accounting'
}
```
However, this method will also retrieve only the immediate groups names
much like the `getGroups()` method. You'll need to pass in `true` in
the first parameter to retrieve results recursively.
```php
$names = $user->getGroupNames($recursive = true);
```
## Checking if the Model is apart of a Group
To check if a model is apart of a certain group, use the `inGroup()` method:
```php
$group = $provider->search()->groups()->find('Office');
if ($user->inGroup($group)) {
//
}
```
You can also check for multiple memberships by passing in an array of groups:
```php
$groups = $provider->search()->findManyBy('cn', ['Accounting', 'Office']));
if ($user->inGroup($groups->toArray()) {
// This user is apart of the 'Accounting' and 'Office' group!
}
```
> **Note**: Much like the other methods above, you'll need to provide a `$recursive`
> flag to the `inGroup()` method if you'd like recursive results included.
We can also provide distinguished names instead of Group model instances:
```php
$dns = [
'cn=Accounting,ou=Groups,dc=acme,dc=org',
'cn=Office,ou=Groups,dc=acme,dc=org',
];
if ($user->inGroup($dns, $recursive = true)) {
//
}
```
Or, we can also just provide the name(s) of the group(s).
```php
$names = [
'Accounting',
'Office',
];
if ($user->inGroup($names, $recursive = true)) {
//
}
```
## Adding a Group
To add the model to a specific group, call the `addGroup()` method:
```php
$group = $provider->search()->groups()->find('Accounting');
// You can either provide a Group model:
if ($user->addGroup($group)) {
//
}
// Or a Groups DN:
if ($user->addGroup('cn=Accounting,ou=Groups,dc=acme,dc=org')) {
//
}
```
> **Note**: You do not need to call the `save()` method for adding / removing groups.
> This is done automatically so you can perform clean `if` statements on the method.
## Removing a Group
To remove the model from a specific group, call the `removeGroup()` method:
```php
$group = $user->getGroups()->first();
// You can either provide a Group model:
if ($user->removeGroup($group)) {
//
}
// Or the groups DN:
if ($user->removeGroup('cn=Accounting,ou=Office Groups,dc=acme,dc=org')) {
//
}
```

180
data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md vendored Normal file
View File

@@ -0,0 +1,180 @@
# The User Model
> **Note**: This model contains the trait `HasMemberOf`. For more information, visit the documentation:
> [HasMemberOfTrait](/models/traits/has-member-of.md)
## Creating
> **Note**: If you need to create users with passwords, SSL or TLS **must** be enabled on your configured connection.
>
> The password you enter for the user **must** also obey your LDAP servers password requirements,
> otherwise you will receive a "Server is unwilling to perform" LDAP exception upon saving.
```php
// Construct a new User model instance.
$user = $provider->make()->user();
// Create the users distinguished name.
// We're adding an OU onto the users base DN to have it be saved in the specified OU.
$dn = $user->getDnBuilder()->addOu('Users'); // Built DN will be: "CN=John Doe,OU=Users,DC=acme,DC=org";
// Set the users DN, account name.
$user->setDn($dn);
$user->setAccountName('jdoe');
$user->setCommonName('John Doe');
// Set the users password.
// NOTE: This password must obey your AD servers password requirements
// (including password history, length, special characters etc.)
// otherwise saving will fail and you will receive an
// "LDAP Server is unwilling to perform" message.
$user->setPassword('correct-horse-battery-staple');
// Get a new account control object for the user.
$ac = $user->getUserAccountControlObject();
// Mark the account as enabled (normal).
$ac->accountIsNormal();
// Set the account control on the user and save it.
$user->setUserAccountControl($ac);
// Save the user.
$user->save();
// All done! An enabled user will be created and is ready for use.
```
## Methods
There's a ton of available methods for the User model. Below is a list for a quick reference.
> **Note**: Don't see a method for an LDAP attribute? Create an issue and let us know!
```php
// Get the users display name.
$user->getDisplayName();
// Get the users first email address.
$user->getEmail();
// Get the users title.
$user->getTitle();
// Get the users department.
$user->getDepartment();
// Get the users first name.
$user->getFirstName();
// Get the users last name.
$user->getLastName();
// Get the users info.
$user->getInfo();
// Get the users initials.
$user->getInitials();
// Get the users country.
$user->getCountry();
// Get the users street address.
$user->getStreetAddress();
// Get the users postal code.
$user->getPostalCode();
// Get the users physical delivery office name.
$user->getPhysicalDeliveryOfficeName();
// Get the users phone number.
$user->getTelephoneNumber();
// Get the users locale.
$user->getLocale();
// Get the users company.
$user->getCompany();
// Get the users other email addresses.
$user->getOtherMailbox();
// Get the users home mailbox database location (stored as a distinguished name).
$user->getHomeMdb();
// Get the users email nickname.
$user->getMailNickname();
// Get the users principal name.
$user->getUserPrincipalName();
// Get the users proxy email addresses.
$user->getProxyAddresses();
// Get the users failed login attempts.
$user->getBadPasswordCount();
// Get the users last failed login attempt timestamp.
$user->getBadPasswordTime();
// Get the users last password change timestamp.
$user->getPasswordLastSet();
// Get the users last password change timestamp in unix time.
$user->getPasswordLastSetTimestamp();
// Get the users last password change timestamp in MySQL date format.
$user->getPasswordLastSetDate();
// Get the users lockout time.
$user->getLockoutTime();
// Get the users user account control integer.
$user->getUserAccountControl();
// Get the users roaming profile path.
$user->getProfilePath();
// Get the users legacy exchange distinguished name.
$user->getLegacyExchangeDn();
// Get the users account expiry timestamp.
$user->getAccountExpiry();
// Get the boolean that determines whether to show this user in the global address book.
$user->getShowInAddressBook();
// Get the users thumbnail photo.
$user->getThumbnail();
// Get the users thumbnail photo (base64 encoded for HTML <img src=""> tags).
$user->getThumbnailEncoded();
// Get the users jpeg photo.
$user->getJpegPhoto();
// Get the users jpeg photo (base64 encoded for HTML <img src=""> tags).
$user->getJpegPhotoEncoded();
// Get the users manager.
$user->getManager();
// Get the users employee ID.
$user->getEmployeeId();
// Get the users employee number.
$user->getEmployeeNumber();
// Get the users employee type
$user->getEmployeeType();
// Get the users room number.
$user->getRoomNumber();
// Get the users department number.
$user->getDepartmentNumber();
// Get the users personal title.
$user->getPersonalTitle();
```

115
data/web/inc/lib/vendor/adldap2/adldap2/docs/readme.md vendored Normal file
View File

@@ -0,0 +1,115 @@
# Introduction
## What is Adldap2?
Adldap2 is a PHP LDAP package that allows you to:
1. Easily manage multiple LDAP connections at once
2. Perform authentication
3. Search your LDAP directory with a fluent and easy to use query builder
4. Create / Update / Delete LDAP entities with ease
5. And more
## History of Adldap2
Adldap2 was originally created as a fork of the original LDAP library [adLDAP](https://github.com/adldap/adLDAP) due to bugs, and it being completely abandoned.
Adldap2 contains absolutely no similarities to the original repository, and was built to be as easily accessible as possible, with great documentation, and easily understandable syntax.
Much of the API was constructed with Ruby's ActiveRecord and Laravel's Eloquent in mind, and to be an answer to the question:
> _Why can't we use LDAP like we use a database?_
## Why should you use Adldap2?
Working with LDAP in PHP can be a messy and confusing endeavor, especially when using multiple connections, creating and managing entities, performing moves, resetting passwords, and performing ACL modifications to user accounts.
Wrapper classes for LDAP are usually always created in PHP applications.
Adldap2 allows you to easily manage the above problems without reinventing the wheel for every project.
## Implementations
- [Laravel](https://github.com/Adldap2/Adldap2-Laravel)
## Quick Start
Install the package via `composer`:
```
composer require adldap2/adldap2
```
Use Adldap2:
```php
// Construct new Adldap instance.
$ad = new \Adldap\Adldap();
// Create a configuration array.
$config = [
// An array of your LDAP hosts. You can use either
// the host name or the IP address of your host.
'hosts' => ['ACME-DC01.corp.acme.org', '192.168.1.1'],
// The base distinguished name of your domain to perform searches upon.
'base_dn' => 'dc=corp,dc=acme,dc=org',
// The account to use for querying / modifying LDAP records. This
// does not need to be an admin account. This can also
// be a full distinguished name of the user account.
'username' => 'admin@corp.acme.org',
'password' => 'password',
];
// Add a connection provider to Adldap.
$ad->addProvider($config);
try {
// If a successful connection is made to your server, the provider will be returned.
$provider = $ad->connect();
// Performing a query.
$results = $provider->search()->where('cn', '=', 'John Doe')->get();
// Finding a record.
$user = $provider->search()->find('jdoe');
// Creating a new LDAP entry. You can pass in attributes into the make methods.
$user = $provider->make()->user([
'cn' => 'John Doe',
'title' => 'Accountant',
'description' => 'User Account',
]);
// Setting a model's attribute.
$user->cn = 'John Doe';
// Saving the changes to your LDAP server.
if ($user->save()) {
// User was saved!
}
} catch (\Adldap\Auth\BindException $e) {
// There was an issue binding / connecting to the server.
}
```
## Versioning
Adldap2 is versioned under the [Semantic Versioning](http://semver.org/) guidelines as much as possible.
Releases will be numbered with the following format:
`<major>.<minor>.<patch>`
And constructed with the following guidelines:
* Breaking backward compatibility bumps the major and resets the minor and patch.
* New additions without breaking backward compatibility bumps the minor and resets the patch.
* Bug fixes and misc changes bumps the patch.
Minor versions are not maintained individually, and you're encouraged to upgrade through to the next minor version.
Major versions are maintained individually through separate branches.

662
data/web/inc/lib/vendor/adldap2/adldap2/docs/searching.md vendored Normal file
View File

@@ -0,0 +1,662 @@
# Searching
## Introduction
Using the Adldap2 query builder makes building LDAP queries feel effortless.
It allows you to generate LDAP filters using a fluent and
convenient interface, similar to Eloquent in Laravel.
> **Note:** The Adldap2 query builder escapes all fields & values
> given to its `where()` methods. There is no need to clean or
> escape strings before passing them into the query builder.
## Creating a new Query
To create a new search query, call the `search()` method on your connection provider instance:
```php
$search = $provider->search();
```
Or you can chain all your methods if you'd prefer:
```php
$results = $provider->search()->where('cn', '=', 'John Doe')->get();
```
## Selects
> **Note:** Fields are case in-sensitive. For example, you can
> insert `CN`, `cn` or `cN`, they will return the same result.
#### Selecting attributes
Selecting only the LDAP attributes you need will increase the speed of your queries.
```php
// Passing in an array of attributes
$search->select(['cn', 'samaccountname', 'telephone', 'mail']);
// Passing in each attribute as an argument
$search->select('cn', 'samaccountname', 'telephone', 'mail');
```
## Executing Searches
#### Finding a specific record
If you're trying to find a single record, but not sure what the record might be, use the `find()` method:
```php
$record = $search->find('John Doe');
if ($record) {
// Record was found!
} else {
// Hmm, looks like we couldn't find anything...
}
```
> **Note**: Using the `find()` method will search for LDAP records using ANR
> (ambiguous name resolution) and return the first result.
>
> Since ActiveDirectory is the only LDAP distribution that supports ANR,
> an equivalent query will be created for other LDAP distributions
> that are not compatible.
>
> For a more fine-tuned search, use the `findBy()` method below.
##### Finding a record (or failing)
If you'd like to try and find a single record and throw an exception when it hasn't been
found, use the `findOrFail()` method:
```php
try {
$record = $search->findOrFail('John Doe');
} catch (Adldap\Models\ModelNotFoundException $e) {
// Record wasn't found!
}
```
#### Finding a record by a specific attribute
If you're looking for a single record with a specific attribute, use the `findBy()` method:
```php
// We're looking for a record with the 'samaccountname' of 'jdoe'.
$record = $search->findBy('samaccountname', 'jdoe');
```
##### Finding a record by a specific attribute (or failing)
If you'd like to try and find a single record by a specific attribute and throw
an exception when it cannot be found, use the `findByOrFail()` method:
```php
try {
$record = $search->findByOrFail('samaccountname', 'jdoe');
} catch (Adldap\Models\ModelNotFoundException $e) {
// Record wasn't found!
}
```
#### Finding a record by its distinguished name
If you're looking for a single record with a specific DN, use the `findByDn()` method:
```php
$record = $search->findByDn('cn=John Doe,dc=corp,dc=org');
```
###### Finding a record by its distinguished name (or failing)
If you'd like to try and find a single record by a specific DN and throw
an exception when it hasn't been found, use the `findByDnOrFail()` method:
```php
try {
$record = $search->findByDnOrFail('cn=John Doe,dc=corp,dc=org');
} catch (Adldap\Models\ModelNotFoundException $e) {
// Record wasn't found!
}
```
#### Retrieving results
To get the results from a search, simply call the `get()` method:
```php
$results = $search->select(['cn', 'samaccountname'])->get();
```
> **Note**: Executed searches via the `get()` method will return them inside an
> `Illuminate\Support\Collection` instance (a glorified array), with allows
> you to utilize [some extremely handy methods](https://laravel.com/docs/collections).
>
> Executed searches via the `first()` method will return **a model instance only**.
##### Retrieving the first record
To retrieve the first record of a search, call the `first()` method:
```php
$record = $search->first();
```
> **Note**: If you are using `sortBy()`, calling `first()` will not take this into account. Sorts
> are performed **after** retrieving query results. If you would like the first record of
> a sorted result set, call `first()` on a `Collection` of returned models.
###### Retrieving the first record (or failing)
To retrieve the first record of a search or throw an exception when one isn't found, call the `firstOrFail()` method:
```php
try {
$record = $search->firstOrFail();
} catch (Adldap\Models\ModelNotFoundException $e) {
// Record wasn't found!
}
```
## Limit
To limit the results records returned from your LDAP server and increase the
speed of your queries, you can use the `limit()` method:
```php
// This will only return 5 records that contain the name of 'John':
$records = $search->where('cn', 'contains', 'John')->limit(5)->get();
```
## Wheres
To perform a where clause on the search object, use the `where()` function:
```php
$search->where('cn', '=', 'John Doe');
```
This query would look for a record with the common name of 'John Doe' and return the results.
We can also perform a 'where equals' without including the operator:
```php
$search->whereEquals('cn', 'John Doe');
```
We can also supply an array of key - value pairs to quickly add multiple wheres:
```php
$wheres = [
'cn' => 'John Doe',
'samaccountname' => 'jdoe',
];
$search->where($wheres);
```
Or, if you require conditionals, you can quickly add multiple wheres with nested arrays:
```php
$search->where([
['cn', '=', 'John Doe'],
['manager', '!', 'Suzy Doe'],
]);
```
#### Where Starts With
We could also perform a search for all objects beginning with the common name of 'John' using the `starts_with` operator:
```php
$results = $provider->search()->where('cn', 'starts_with', 'John')->get();
// Or use the method whereStartsWith($attribute, $value):
$results = $provider->search()->whereStartsWith('cn', 'John')->get();
```
#### Where Ends With
We can also search for all objects that end with the common name of `Doe` using the `ends_with` operator:
```php
$results = $provider->search()->where('cn', 'ends_with', 'Doe')->get();
// Or use the method whereEndsWith($attribute, $value):
$results = $provider->search()->whereEndsWith('cn', 'Doe')->get();
```
#### Where Between
To search for records between two values, use the `whereBetween` method.
For the example below, we'll retrieve all users who were created between two dates:
```php
$from = (new DateTime('October 1st 2016'))->format('YmdHis.0\Z');
$to = (new DateTime('January 1st 2017'))->format('YmdHis.0\Z');
$users = $provider->search()
->users()
->whereBetween('whencreated', [$from, $to])
->get();
```
#### Where Contains
We can also search for all objects with a common name that contains `John Doe` using the `contains` operator:
```php
$results = $provider->search()->where('cn', 'contains', 'John Doe')->get();
// Or use the method whereContains($attribute, $value):
$results = $provider->search()->whereContains('cn', 'John Doe')->get();
```
##### Where Not Contains
You can use a 'where not contains' to perform the inverse of a 'where contains':
```php
$results = $provider->search()->where('cn', 'not_contains', 'John Doe')->get();
// Or use the method whereNotContains($attribute, $value):
$results = $provider->search()->whereNotContains('cn', 'John Doe');
```
#### Where Has
Or we can retrieve all objects that have a common name attribute using the wildcard operator (`*`):
```php
$results = $provider->search()->where('cn', '*')->get();
// Or use the method whereHas($field):
$results = $provider->search()->whereHas('cn')->get();
```
This type of filter syntax allows you to clearly see what your searching for.
##### Where Not Has
You can use a 'where not has' to perform the inverse of a 'where has':
```php
$results = $provider->search->where('cn', '!*')->get();
// Or use the method whereNotHas($field):
$results = $provider->search()->whereNotHas($field)->get();
```
## Or Wheres
To perform an `or where` clause on the search object, use the `orWhere()` method. However,
please be aware this function performs differently than it would on a database.
For example:
```php
$results = $search
->where('cn', '=', 'John Doe')
->orWhere('cn', '=', 'Suzy Doe')
->get();
```
This query would return no results. Since we're already defining that the common name (`cn`) must equal `John Doe`, applying
the `orWhere()` does not amount to 'Look for an object with the common name as "John Doe" OR "Suzy Doe"'. This query would
actually amount to 'Look for an object with the common name that <b>equals</b> "John Doe" OR "Suzy Doe"
To solve the above problem, we would use `orWhere()` for both fields. For example:
```php
$results = $search
->orWhere('cn', '=', 'John Doe')
->orWhere('cn', '=', 'Suzy Doe')
->get();
```
Now, we'll retrieve both John and Suzy's LDAP records, because the common name can equal either.
> **Note**: You can also use all `where` methods as an or where, for example:
> `orWhereHas()`, `orWhereContains()`, `orWhereStartsWith()`, `orWhereEndsWith()`
## Dynamic Wheres
To perform a dynamic where, simply suffix a `where` with the field you're looking for.
This feature was directly ported from Laravel's Eloquent.
Here's an example:
```php
// This query:
$result = $search->where('cn', '=', 'John Doe')->first();
// Can be converted to:
$result = $search->whereCn('John Doe')->first();
```
You can perform this on **any** attribute:
```php
$result = $search->whereTelephonenumber('555-555-5555')->first();
```
You can also chain them:
```php
$result = $search
->whereTelephonenumber('555-555-5555')
->whereGivenname('John Doe')
->whereSn('Doe')
->first();
```
You can even perform multiple dynamic wheres by separating your fields by an `And`:
```php
// This would perform a search for a user with the
// first name of 'John' and last name of 'Doe'.
$result = $search->whereGivennameAndSn('John', 'Doe')->first();
```
## Nested Filters
By default, the Adldap2 query builder automatically wraps your queries in `and` / `or` filters for you.
However, if any further complexity is required, nested filters allow you
to construct any query fluently and easily.
#### andFilter
The `andFilter` method accepts a closure which allows you to construct a query inside of an `and` LDAP filter:
```php
$query = $provider->search()->newQuery();
// Creates the filter: (&(givenname=John)(sn=Doe))
$results = $query->andFilter(function (Adldap\Query\Builder $q) {
$q->where('givenname', '=', 'John')
->where('sn', '=', 'Doe');
})->get();
```
The above query would return records that contain the first name `John` **and** the last name `Doe`.
#### orFilter
The `orFilter` method accepts a closure which allows you to construct a query inside of an `or` LDAP filter:
```php
$query = $provider->search()->newQuery();
// Creates the filter: (|(givenname=John)(sn=Doe))
$results = $query->orFilter(function (Adldap\Query\Builder $q) {
$q->where('givenname', '=', 'John')
->where('sn', '=', 'Doe');
})->get();
```
The above query would return records that contain the first name `John` **or** the last name `Doe`.
#### notFilter
The `notFilter` method accepts a closure which allows you to construct a query inside a `not` LDAP filter:
```php
$query = $provider->search()->newQuery();
// Creates the filter: (!(givenname=John)(sn=Doe))
$results = $query->notFilter(function (Adldap\Query\Builder $q) {
$q->where('givenname', '=', 'John')
->where('sn', '=', 'Doe');
})->get();
```
The above query would return records that **do not** contain the first name `John` **or** the last name `Doe`.
#### Complex Nesting
The above methods `andFilter` / `orFilter` can be chained together and nested
as many times as you'd like for larger complex queries:
```php
$query = $provider->search()->newQuery();
$query = $query->orFilter(function (Adldap\Query\Builder $q) {
$q->where('givenname', '=', 'John')->where('sn', '=', 'Doe');
})->andFilter(function (Adldap\Query\Builder $q) {
$q->where('department', '=', 'Accounting')->where('title', '=', 'Manager');
})->getUnescapedQuery();
echo $query; // Returns '(&(|(givenname=John)(sn=Doe))(&(department=Accounting)(title=Manager)))'
```
## Raw Filters
> **Note**: Raw filters are not escaped. **Do not** accept user input into the raw filter method.
Sometimes you might just want to add a raw filter without using the query builder.
You can do so by using the `rawFilter()` method:
```php
$filter = '(samaccountname=jdoe)';
$results = $search->rawFilter($filter)->get();
// Or use an array
$filters = [
'(samaccountname=jdoe)',
'(surname=Doe)',
];
$results = $search->rawFilter($filters)->get();
// Or use multiple arguments
$results = $search->rawFilter($filters[0], $filters[1])->get();
// Multiple raw filters will be automatically wrapped into an `and` filter:
$query = $search->getUnescapedQuery();
echo $query; // Returns (&(samaccountname=jdoe)(surname=Doe))
```
## Sorting
Sorting is really useful when your displaying tabular LDAP results. You can
easily perform sorts on any LDAP attribute by using the `sortBy()` method:
```php
$results = $search->whereHas('cn')->sortBy('cn', 'asc')->get();
```
You can also sort paginated results:
```php
$results = $search->whereHas('cn')->sortBy('cn', 'asc')->paginate(25);
```
> **Note**: Sorting occurs *after* results are returned. This is due
> to PHP not having the functionality of sorting records on
> the server side before they are returned.
## Paginating
Paginating your search results will allow you to return more results than
your LDAP cap (usually 1000) and display your results in pages.
> **Note**: Calling `paginate()` will retrieve **all** records from your LDAP server for the current query.
>
> This **does not** operate the same way pagination occurs in a database. Pagination of
> an LDAP query simply allows you to return a larger result set than your
> LDAP servers configured maximum (usually 1000).
>
> The pagination object is simply a collection that allows you to iterate
> through all the resulting records easily and intuitively.
To perform this, call the `paginate()` method instead of the `get()` method:
```php
$recordsPerPage = 50;
$currentPage = $_GET['page'];
// This would retrieve all records from your LDAP server inside a new Adldap\Objects\Paginator instance.
$paginator = $search->paginate($recordsPerPage, $currentPage);
// Returns total number of pages, int
$paginator->getPages();
// Returns current page number, int
$paginator->getCurrentPage();
// Returns the amount of entries allowed per page, int
$paginator->getPerPage();
// Returns all of the results in the entire paginated result
$paginator->getResults();
// Returns the total amount of retrieved entries, int
$paginator->count();
// Iterate over the results like normal
foreach($paginator as $result)
{
echo $result->getCommonName();
}
```
## Scopes
Search scopes allow you to easily retrieve common models of a particular 'scope'.
Each scope simply applies the required filters to the search object
that (when executed) will only return the relevant models.
Here is a list of all available scopes:
```php
// Retrieve all users (Adldap\Models\User).
$results = $search->users()->get();
// Retrieve all printers (Adldap\Models\Printer).
$results = $search->printers()->get();
// Retrieve all organizational units (Adldap\Models\OrganizationalUnit).
$results = $search->ous()->get();
// Retrieve all organizational units (Adldap\Models\OrganizationalUnit).
$results = $search->organizations()->get();
// Retrieve all groups (Adldap\Models\Group).
$results = $search->groups()->get();
// Retrieve all containers (Adldap\Models\Container).
$results = $search->containers()->get();
// Retrieve all contacts (Adldap\Models\Contact).
$results = $search->contacts()->get();
// Retrieve all computers (Adldap\Models\Computer).
$results = $search->computers()->get();
```
## Base DN
To set the base DN of your search you can use one of two methods:
```php
// Using the `in()` method:
$results = $provider->search()->in('ou=Accounting,dc=acme,dc=org')->get();
// Using the `setDn()` method:
$results = $provider->search()->setDn('ou=Accounting,dc=acme,dc=org')->get();
// You can also include `in()` with the scope
$results = $provider->search()->organizations()->in('ou=Accounting,dc=acme,dc=org')->get()
```
Either option will return the same results. Use which ever method you prefer to be more readable.
## Search Options
#### Recursive
By default, all searches performed are recursive.
If you'd like to disable recursive search and perform a single level search, use the `listing()` method:
```php
$result = $provider->search()->listing()->get();
```
This would perform an `ldap_listing()` instead of an `ldap_search()`.
#### Read
If you'd like to perform a read instead of a listing or a recursive search, use the `read()` method:
```php
$result = $provider->search()->read()->where('objectClass', '*')->get();
```
This would perform an `ldap_read()` instead of an `ldap_listing()` or an `ldap_search()`.
> **Note**: Performing a `read()` will always return *one* record in your result.
#### Raw
If you'd like to retrieve the raw LDAP results, use the `raw()` method:
```php
$rawResults = $provider->search()->raw()->where('cn', '=', 'John Doe')->get();
var_dump($rawResults); // Returns an array
```
## Retrieving the ran query
If you'd like to retrieve the current query to save or run it at another
time, use the `getQuery()` method on the query builder.
This will return the escaped filter.
```php
$query = $provider->search()->where('cn', '=', 'John Doe')->getQuery();
echo $query; // Returns '(cn=\4a\6f\68\6e\20\44\6f\65)'
```
To retrieve the unescaped filter, call the `getUnescapedQuery()` method:
```php
$query = $provider->search()->where('cn', '=', 'John Doe')->getUnescapedQuery();
echo $query; // Returns '(cn=John Doe)'
```
Now that you know how to search your directory, lets move onto [creating / modifying LDAP records](models/model.md).

552
data/web/inc/lib/vendor/adldap2/adldap2/docs/setup.md vendored Normal file
View File

@@ -0,0 +1,552 @@
# Setup
## Configuration
To configure your LDAP connections, you can use two methods:
1. Using an array
2. Using a `Adldap\Configuration\DomainConfiguration` object
Either or will produce the same results. Use whichever you feel most comfortable with.
### Using an array
```php
$config = [
'hosts' => [
'DC-01.corp.acme.org',
],
'...'
];
```
### Using a `DomainConfiguration` object
```php
// Setting options via first argument:
$config = new Adldap\Configuration\DomainConfiguration([
'hosts' => [
'DC-01.corp.acme.org',
],
]);
// Setting via the `set()` method:
$config->set('hosts', [
'DC-01.corp.acme.org',
]);
```
### Options
#### Array Example With All Options
```php
// Create the configuration array.
$config = [
// Mandatory Configuration Options
'hosts' => ['corp-dc1.corp.acme.org', 'corp-dc2.corp.acme.org'],
'base_dn' => 'dc=corp,dc=acme,dc=org',
'username' => 'admin',
'password' => 'password',
// Optional Configuration Options
'schema' => Adldap\Schemas\ActiveDirectory::class,
'account_prefix' => 'ACME-',
'account_suffix' => '@acme.org',
'port' => 389,
'follow_referrals' => false,
'use_ssl' => false,
'use_tls' => false,
'version' => 3,
'timeout' => 5,
// Custom LDAP Options
'custom_options' => [
// See: http://php.net/ldap_set_option
LDAP_OPT_X_TLS_REQUIRE_CERT => LDAP_OPT_X_TLS_HARD
]
];
```
#### Required Options
##### Hosts
The hosts option is an array of IP addresses or hostnames located
on your network that serve Active Directory.
You insert as many servers or as little as you'd like depending on your forest (with the minimum of one of course).
> **Note:** Do not append your port to your IP addresses or hostnames. Use the `port` configuration option instead.
##### Base Distinguished Name
The base distinguished name is the base distinguished name you'd like to perform operations on.
An example base DN would be `DC=corp,DC=acme,DC=org`.
If one is not defined, you will not retrieve any search results.
> **Note**: Your base DN is **case insensitive**. You do not need to worry about incorrect casing.
##### Username & Password
To connect to your LDAP server, a username and password is required to be able to query and run operations on your server(s).
You can use any account that has these permissions.
> **Note**: To run administration level operations, such as resetting passwords,
> this account **must** have permissions to do so on your directory.
#### Optional Options
##### Schema
The schema option allows you to configure which directory you're connecting to.
This is a somewhat optional, however this **must** be changed if you're connecting
to an alternate LDAP variant such as OpenLDAP or FreeIPA.
Below are available schemas:
- `Adldap\Schemas\ActiveDirectory`
- `Adldap\Schemas\OpenLDAP`
- `Adldap\Schemas\FreeIPA`
By default, this option is set to the `Adldap\Schemas\ActiveDirectory` schema.
##### Account Prefix
The account prefix option is a string to *prepend* to all usernames that go through the `Guard::attempt()` method.
This option is just for convenience.
It is usually not needed (if utilizing the account suffix), however the functionality is
in place if you would like to only allow certain users with the specified prefix
to login, or add a domain so your users do not have to specify one.
##### Account Suffix
The account suffix option is a string to *append* to all usernames that go
through the `Adldap\Auth\Guard::attempt()` method.
This option is just for convenience.
An example use case for this would be inserting your LDAP users `userPrincipalName` suffix so you don't need to append it manually.
For example, with a `account_suffix` in your configuration set to `@corp.acme.org`:
```php
$username = 'jdoe';
$password = 'password';
// Here, an `ldap_bind()` will be called with a username of 'jdoe@corp.acme.org`
$provider->auth()->attempt($username, $password);
```
##### Port
The port option is used for authenticating and binding to your LDAP server.
The default ports are already used for non SSL and SSL connections (389 and 636).
Only insert a port if your LDAP server uses a unique port.
##### Follow Referrals
The follow referrals option is a boolean to tell active directory to follow a referral to another server on your network if the server queried knows the information your asking for exists, but does not yet contain a copy of it locally.
This option is defaulted to false.
Disable this option if you're experiencing search / connectivity issues.
For more information, visit: https://technet.microsoft.com/en-us/library/cc978014.aspx
##### SSL & TLS
These Boolean options enable an SSL or TLS connection to your LDAP server.
Only **one** can be set to `true`. You must chose either or.
> **Note**: You **must** enable SSL or TLS to reset passwords in ActiveDirectory.
These options are definitely recommended if you have the ability to connect to your server securely.
> **Note**: TLS is recommended over SSL, as SSL is now labelled as a depreciated mechanism for securely running LDAP operations.
##### Version
The LDAP version to use for your connection.
Must be an integer and can either be `2` or `3`.
##### Timeout
The timeout option allows you to configure the amount of seconds to wait until
your application receives a response from your LDAP server.
The default is 5 seconds.
##### Custom Options
Arbitrary options can be set for the connection to fine-tune TLS and connection behavior.
Please note that `LDAP_OPT_PROTOCOL_VERSION`, `LDAP_OPT_NETWORK_TIMEOUT` and `LDAP_OPT_REFERRALS` will be ignored if set.
These are set above with the `version`, `timeout` and `follow_referrals` keys respectively.
Valid options are listed in the [PHP documentation for ldap_set_option](http://php.net/ldap_set_option).
## Getting Started
Each LDAP connection you have will be contained inside the `Adldap` instance as its own **connection provider**.
There are a couple of ways you can easily add each of your LDAP connections. Let's walk through them:
**Using a configuration array:**
```php
$config = ['...'];
$ad = new Adldap\Adldap();
$ad->addProvider($config);
// You can also specify the name of the
// connection as the second argument:
$ad->addProvider($config, 'connection-one');
```
**Using a DomainConfiguration object:**
```php
$ad = new Adldap\Adldap();
$config = new Adldap\Configuration\DomainConfiguration(['...']);
$ad->addProvider($config, 'connection-one');
```
**Using the constructor:**
> **Note**: When inserting your configuration into a new `Adldap` instance, you
> need to set a key for each connection. **This will be its connection name**.
```php
$connections = [
'connection1' => [
'hosts' => ['...'],
],
'connection2' => [
'hosts' => ['...'],
],
];
$ad = new Adldap\Adldap($connections);
```
## Connecting
The easiest way to get connected is to call the `connect($name)` method on your `Adldap` instance.
Its first argument accepts the name of your configured connection.
This method will return you a connected **connection provider** when
successful, and throw an exception when unsuccessful:
```php
$ad = new Adldap\Adldap();
$config = ['...'];
$connectionName = 'my-connection';
$ad->addProvider($config, $connectionName);
try {
$provider = $ad->connect($connectionName);
// Great, we're connected!
} catch (Adldap\Auth\BindException $e) {
// Failed to connect.
}
```
### Using an alternate username / password
If you'd like to connect to your configured connection using a different username and password than your configuration, then simply provide them in the second and third arguments:
```php
$username = 'server-admin';
$password = 'my-super-secret-password';
$provider = $ad->connect($connectionName, $username, $password);
```
### Dynamically Connecting
If you're like me and like chainable (fluent) API's in PHP, then dynamically connecting is a nice option to have.
To dynamically connect, simply call any connection provider method on your `Adldap` instance.
> **Note**: Your default connection will be used when dynamically connecting.
> More on this below.
Here's an example:
```php
$ad = new Adldap\Adldap();
$ad->addProvider($config = ['...']);
try {
$users = $ad->search()->users()->get();
} catch (Adldap\Auth\BindException $e) {
// Failed to connect.
}
```
### Anonymously Binding
If you'd like to anonymously bind, set your `username` and `password` configuration to `null`:
```php
$ad = new Adldap\Adldap();
$config = [
'username' => null,
'password' => null,
];
$ad->addProvider($config);
try {
$provider = $ad->connect();
// ...
} catch (BindException $e) {
// Failed.
}
```
Or, manually bind your provider and don't pass in a `username` or `password` parameter:
```php
$config = [
'hosts' => ['...'],
];
$ad->addProvider($config);
$provider = $ad->getDefaultProvider();
try {
$provider->auth()->bind();
// Successfully bound.
} catch (BindException $e) {
// Failed.
}
```
### Setting a Default Connection
Setting a default LDAP connection is used for dynamically connecting.
To set your default connection, call the `setDefaultProvider($name)` method:
```php
$ad->setDefaultProvider('my-connection');
$computers = $ad->search()->computers()->get();
```
## Authenticating
If you're looking to authenticate (bind) users using your LDAP connection, call
the `auth()->attempt()` method on your provider instance:
```php
$username = 'jdoe';
$password = 'Password@1';
try {
if ($provider->auth()->attempt($username, $password)) {
// Passed.
} else {
// Failed.
}
} catch (Adldap\Auth\UsernameRequiredException $e) {
// The user didn't supply a username.
} catch (Adldap\Auth\PasswordRequiredException $e) {
// The user didn't supply a password.
}
```
If you'd like all LDAP operations during the same request to be ran under the
authenticated user, pass in `true` into the last paramter:
```php
if ($provider->auth()->attempt($username, $password, $bindAsUser = true)) {
// Passed.
} else {
// Failed.
}
```
---
Now that you've learned the basics of configuration and
getting yourself connected, continue on to learn
[how to search your LDAP directory](searching.md).
## Using Other LDAP Servers (OpenLDAP / FreeIPA / etc.)
Alternate LDAP server variants such as OpenLDAP or FreeIPA contain
some different attribute names than ActiveDirectory.
The Adldap2 schema offers an attribute map for each available LDAP attribute, and
is completely configurable and customizable.
If you're using an alternate LDAP server variant such as OpenLDAP or FreeIPA, you **must** change the default schema inside your configuration array. If you do not, you won't receive the correct model instances for results, and you won't be
able to utilize some standard methods available on these models.
By default, Adldap2 is configured to be used with **Microsoft ActiveDirectory**.
When creating your configuration array, set your schema using the `schema` key:
**Using configuration array:**
```php
$ad = new Adldap\Adldap();
$config = [
'...',
'schema' => Adldap\Schemas\OpenLDAP::class
];
$ad->addProvider($config);
```
**Using configuration object:**
```php
$ad = new Adldap\Adldap();
$config = new Adldap\Configuration\DomainConfiguration();
$config->set('schema', Adldap\Schemas\OpenLDAP::class);
$ad->addProvider($config);
```
Once you've set the schema of your connection provider, you can use the same API interacting with different LDAP servers.
Continue onto the [searching](searching.md) documentation to learn how to begin querying your LDAP server(s).
## Using G-Suite Secure LDAP Service
G-Suite LDAP service only uses client certificates and no username + password, make sure yo match base_dn with your domian.
```php
$ad = new \Adldap\Adldap();
// Create a configuration array.
$config = [
'hosts' => ['ldap.google.com'],
'base_dn' => 'dc=your-domain,dc=com',
'use_tls' => true,
'version' => 3,
'schema' => Adldap\Schemas\GSuite::class,
'custom_options' => [
LDAP_OPT_X_TLS_CERTFILE => 'Google_2023_02_05_35779.crt',
LDAP_OPT_X_TLS_KEYFILE => 'Google_2023_02_05_35779.key',
]
];
$ad->addProvider($config);
try {
$provider = $ad->connect();
$results = $provider->search()->ous()->get();
echo 'OUs:'."\r\n";
echo '==============='."\r\n";
foreach($results as $ou) {
echo $ou->getDn()."\r\n";
}
echo "\r\n";
$results = $provider->search()->users()->get();
echo 'Users:'."\r\n";
echo '==============='."\r\n";
foreach($results as $user) {
echo $user->getAccountName()."\r\n";
}
echo "\r\n";
$results = $provider->search()->groups()->get();
echo 'Groups:'."\r\n";
echo '==============='."\r\n";
foreach($results as $group) {
echo $group->getCommonName().' | '.$group->getDisplayName()."\r\n";
}
} catch (\Adldap\Auth\BindException $e) {
echo 'Error: '.$e->getMessage()."\r\n";
}
```
## Raw Operations
### Introduction
If you want to connect to your LDAP server without utilizing Adldap's models (old fashion way), and want to get back the data in a raw format you can easily do so.
If you call `getConnection()` on your connected provider instance, you can perform all LDAP functions on a container class that encapsulates all of PHP's LDAP methods.
You can view all methods avaialble by browsing the LDAP class [here](https://github.com/Adldap2/Adldap2/blob/master/src/Connections/Ldap.php).
Now for some examples:
### Examples
```php
$ad = new Adldap\Adldap();
$config = ['...'];
$ad->addProvider($config);
$provider = $ad->connect();
$rawConnection = $provider->getConnection();
// Performing a raw search.
$result = $rawConnection->search($basedn = 'dc=corp,dc=acme,dc=org', $filter = "cn=johndoe", $selectedAttributes = ['cn', 'department']);
$dn = "cn=John Smith,ou=Wizards,dc=example,dc=com";
// Adding a new LDAP record.
$result = $rawConnection->add($dn, $entry);
// Batch modifying an LDAP record.
$modifs = [
[
"attrib" => "telephoneNumber",
"modtype" => LDAP_MODIFY_BATCH_ADD,
"values" => ["+1 555 555 1717"],
],
];
$result = $rawConnection->modifyBatch($dn, $modifs);
// Deleting an LDAP record.
$result = $rawConnection->delete($dn);
// .. etc
```

122
data/web/inc/lib/vendor/adldap2/adldap2/docs/troubleshooting.md vendored Normal file
View File

@@ -0,0 +1,122 @@
# Troubleshooting
#### Creating and Setting a Users Password
To set a users password when you've created a new one, you need to enable their account, **then** set their password.
For example:
```php
// Construct a new user instance.
$user = $provider->make()->user();
// Set the user profile details.
$user->setAccountName('jdoe');
$user->setFirstName('John');
$user->setLastName('Doe');
$user->setCompany('ACME');
$user->setEmail('jdoe@acme.com');
// Save the new user.
if ($user->save()) {
// Enable the new user (using user account control).
$user->setUserAccountControl(512);
// Set new user password
$user->setPassword('Password123');
// Save the user.
if($user->save()) {
// The password was saved successfully.
}
}
```
#### Determining and Troubleshooting a Binding Failure
> **Note**: The below guide is using ActiveDirectory. Your mileage will vary using other LDAP distributions.
To determine the reason why a bind attempt failed, you can use the event dispatcher to listen for
the `Failed` event, and retrieve the errors that were returned from your LDAP server:
```php
use Adldap\Adldap;
use Adldap\Auth\Events\Failed;
$d = Adldap::getEventDispatcher();
$d->listen(Failed::class, function (Failed $event) {
$conn = $event->connection;
echo $conn->getLastError(); // 'Invalid credentials'
echo $conn->getDiagnosticMessage(); // '80090308: LdapErr: DSID-0C09042A, comment: AcceptSecurityContext error, data 532, v3839'
if ($error = $conn->getDetailedError()) {
$error->getErrorCode(); // 49
$error->getErrorMessage(); // 'Invalid credentials'
$error->getDiagnosticMessage(); // '80090308: LdapErr: DSID-0C09042A, comment: AcceptSecurityContext error, data 532, v3839'
}
});
```
The above diagnostic message can be parsed down further if needed. The error code after the 'data' string
in the above message indicates several things about the bind failure. Here is a list:
- 525 - user not found
- 52e - invalid credentials
- 530 - not permitted to logon at this time
- 531 - not permitted to logon at this workstation
- 532 - password expired
- 533 - account disabled
- 701 - account expired
- 773 - user must reset password
- 775 - user account locked
From the example above, you can see that the authenticating account has their password expired, due to "532" error code.
#### Retrieving All Records Inside a Group
To retrieve all records inside a particular group (including nested groups), use the `rawFilter()` method:
```php
// The `memberof:1.2.840.113556.1.4.1941:` string indicates
// that we want all nested group records as well.
$filter = '(memberof:1.2.840.113556.1.4.1941:=CN=MyGroup,DC=example,DC=com)';
$users = $provider->search()->rawFilter($filter)->get();
```
#### I'm connected but not getting any search results!
The first thing you need to ensure is your `base_dn` in your configuration.
Your `base_dn` needs to identical to the base DN on your domain. Even one mistyped character will result in no search results.
If you also include an `ou` in your base DN (ex. `ou=Accounting,dc=corp,dc=acme,dc=org`), you will only receive results inside the `Accounting` OU.
Once you're connected to your LDAP server, retrieve the Root DSE record.
Here's a full example:
```php
$providers = [
'default' => [
'base_dn' => '',
'...',
]
];
$ad = new Adldap\Adldap($providers);
try {
$provider = $ad->connect();
$root = $provider->search()->getRootDse();
// ex. Returns 'dc=corp,dc=acme,dc=org'
die($root->getRootDomainNamingContext());
} catch (Adldap\Auth\BindException $e) {
//
}
```