yii2-adldap-module v4 (wrapper for Adldap v8)

Howto contribute or support the extension

As you as delevoper know, it's not only source code that matters. The best code is worthless if no documentation exists.
My focus is to provide a comprehensive documentation for this extension. This should help YOU to do your task fast and without strugle.
Updating this extension take days starting with programming, writing the docs and write test for the code and the docs.

I'am glad to see that many persons use the plugin!

If you want to help you can do the following:

Extend or correct the docs and create a Pull-Request

Fix or extend the plugins source code and create a Pull-Request

Add further tests and create a Pull-Request

Open a issue for questions or problems

If this project help you reduce time to develop, you can spend me a cup of coffee :)

Configuration

Add this code in your components section of the application configuration (eg. config/main.php for advanced template or config/web.php for basic template):

'components' => [
//.....
// other components ...
//.....
'ad' => [
'class' => 'Edvlerblog\Adldap2\Adldap2Wrapper',
/*
* Set the default provider to one of the providers defined in the
* providers array.
*
* If this is commented out, the entry 'default' in the providers array is
* used.
*
* See https://github.com/Adldap2/Adldap2/blob/master/docs/connecting.md
* Setting a default connection
*
*/
// 'defaultProvider' => 'another_provider',
/*
* Adlapd2 can handle multiple providers to different Active Directory sources.
* Each provider has it's own config.
*
* In the providers section it's possible to define multiple providers as listed as example below.
* But it's enough to only define the "default" provider!
*/
'providers' => [
/*
* Always add a default provider!
*
* You can get the provider with:
* $provider = \Yii::$app->ad->getDefaultProvider();
* or with $provider = \Yii::$app->ad->getProvider('default');
*/
'default' => [ //Providername default
// Connect this provider on initialisation of the LdapWrapper Class automatically
'autoconnect' => true,
// The provider's schema. Default is \Adldap\Schemas\ActiveDirectory set in https://github.com/Adldap2/Adldap2/blob/master/src/Connections/Provider.php#L112
// You can make your own https://github.com/Adldap2/Adldap2/blob/master/docs/schema.md or use one from https://github.com/Adldap2/Adldap2/tree/master/src/Schemas
// Example to set it to OpenLDAP:
// 'schema' => new \Adldap\Schemas\OpenLDAP(),
// The config has to be defined as described in the Adldap2 documentation.
// https://github.com/Adldap2/Adldap2/blob/master/docs/configuration.md
'config' => [
// Your account suffix, for example: matthias.maderer@example.lan
'account_suffix' => '@example.lan',
// You can use the host name or the IP address of your controllers.
'domain_controllers' => ['server01.example.lan', 'server02.example.lan'],
// Your base DN. This is usually your account suffix.
'base_dn' => 'dc=example,dc=lan',
// The account to use for querying / modifying users. This
// does not need to be an actual admin account.
'admin_username' => 'username_ldap_access',
'admin_password' => 'password_ldap_access!',
// To enable SSL/TLS read the docs/SSL_TLS_AD.md and uncomment
// the variables below
//'port' => 636,
//'use_ssl' => true,
//'use_tls' => true,
]
],
/*
* Another Provider
* You don't have to define another provider if you don't need it. It's just an example.
*
* You can get the provider with:
* or with $provider = \Yii::$app->ad->getProvider('another_provider');
*/
'another_provider' => [ //Providername another_provider
// Connect this provider on initialisation of the LdapWrapper Class automatically
'autoconnect' => false,
// The provider's schema. Default is \Adldap\Schemas\ActiveDirectory set in https://github.com/Adldap2/Adldap2/blob/master/src/Connections/Provider.php#L112
// You can make your own https://github.com/Adldap2/Adldap2/blob/master/docs/schema.md or use one from https://github.com/Adldap2/Adldap2/tree/master/src/Schemas
// Example to set it to OpenLDAP:
// 'schema' => new \Adldap\Schemas\OpenLDAP(),
// The config has to be defined as described in the Adldap2 documentation.
// https://github.com/Adldap2/Adldap2/blob/master/docs/configuration.md
'config' => [
// Your account suffix, for example: matthias.maderer@test.lan
'account_suffix' => '@test.lan',
// You can use the host name or the IP address of your controllers.
'domain_controllers' => ['server1.test.lan', 'server2'],
// Your base DN. This is usually your account suffix.
'base_dn' => 'dc=test,dc=lan',
// The account to use for querying / modifying users. This
// does not need to be an actual admin account.
'admin_username' => 'username_ldap_access',
'admin_password' => 'password_ldap_access',
// To enable SSL/TLS read the docs/SSL_TLS_AD.md and uncomment
// the variables below
//'port' => 636,
//'use_ssl' => true,
//'use_tls' => true,
] // close config
], // close provider
], // close providers array
], //close ad

Usage - Method 1, Method 2 and Method 3

Usage method 1: Simple usage without a user model

If you are need to query some informations for a user from the Active Directory this would be best way.
No additional configuration is needed and the only thing to do is to add the configuration as described above to your components section.

You only use the extension in the regular Yii2 style:

//...
$un = 'testuser';
/*
There are three ways available to call Adldap2 function.
If you use more providers (multiple Active Directory connections)
you make one as default and you can call this one with Method1 or Method2
and the second one will be called with Method3.
*/
//Get the Ldap object for the user.
//$ldapObject holds a class of type Adldap\Models\User from the Adldap project!
// Method 1: uses the default provider given in the configuration above (array key defaultProvider)
$ldapObject = \Yii::$app->ad->search()->findBy('sAMAccountname', $un);
// Method 2: uses the default provider given in the configuration above (array key defaultProvider)
$ldapObject = \Yii::$app->ad->getDefaultProvider()->search()->findBy('sAMAccountname', $un);
// Method 3: get the provider by name (here name default is used).
$ldapObject = \Yii::$app->ad->getProvider('default')->search()->findBy('sAMAccountname', $un);
//Examples
//Please note that all fields from ldap are arrays!
//Access it with ..[0] if it is a single value field.
$givenName = $ldapObject['givenname'][0];
$surname = $ldapObject['surname'][0];
$displayname = $ldapObject['displayname'][0];
$telephone = $ldapObject['telephonenumber'][0];
echo 'gn: ' . $givenName . ' sn: ' . $surname .
' dispname: ' . $displayname . ' phone: ' . $telephone;
//Print all possible attributes
echo '<pre>' . print_r($ldapObject,true) . '</pre>';
// More ways to get attributes:
// https://github.com/Adldap2/Adldap2/blob/master/docs/models/model.md#getting-attributes

You create a user in Active Directory and assign this user to a group starting with yii2_ (e.g. yii2_example_group).

In yii2 a role with the same name exists (yii2_example_group). The role has some permissions assigned.

If you try to login with your new user, the user is created automatically in yii2 and role yii2_example_group is assigned automatically on login.
For the user this is transparent. The only feedback to the user is a successull login and that it is possible to use the functions which he has permissions to access.

Usage method 3: Create, modify and delete Active Directory objects

To create or modify attributes of a Active Directory object use a bind user in your configuration with rights to change the attributes of the objects (a dirty but very discourraged way is to add the bind user to the domain-admins group)!

For some actions like change password you need a SSL/TLS connection. See configuration for further hints.

Create the config class tests\base\TestConfig.php from the template tests\base\TestConfigSample.php.

Start the tests in windows with:

// WARNING!! NOT RUN ON PRODUCTION!!
// TABLES ARE TRUNCATED AND ACTIVE DIRECTORY IS MODIFIED!
// TAKE A LOOK AT THE SOURCE CODE BEFORE RUNNING THE TESTS.
cd vendor/edvlerblog/yii2-adldap-module
..\..\bin\phpunit -v --debug
..\..\bin\phpunit --testdox