README

Yii2扩展，用于Adldap2（https://packagist.org.cn/packages/adldap2/adldap2）

• 查询Active Directory用户、组、计算机、组织单元等...
• RBAC用户模型
• 创建/更新/编辑Active Directory对象
• 广泛的测试套件

如果您从旧版本升级到v5或v6，请阅读此内容

Adldap2在版本9中更改了选项键。如果您从旧版本升级，您必须更改您的config/web.conf（基本模板）或common/config/main.conf（高级模板）以及您的config/console.conf（基本模板）或console/config/main.conf（高级模板）。

有关所有Adldap 2选项，请参阅https://adldap2.github.io/Adldap2/#/setup?id=array-example-with-all-options。

必须更改的选项包括

• admin_username: 重命名为username
• admin_password: 重命名为password
• domain_controllers: 重命名为hosts

如果您配置用户名，请将您的域追加为 @domain.name。否则，您可能会收到 Adldap\Auth\Bindexception: Invalid Credentials。

...
 'username' => 'username_ldap_access@example.lan',
...

有关示例，请参阅配置部分。

如何为扩展做出贡献或提供支持

正如您作为开发者所知，不仅仅是源代码很重要。如果没有文档，最好的代码也是毫无价值的。我的重点是为此扩展提供全面的文档。这应该有助于您快速且无困难地完成任务。从编程、编写文档到编写代码和文档的测试，更新此扩展需要花费数天。

我很高兴看到很多人使用这个插件！

如果您想帮忙，您可以做以下事情

• 扩展或纠正文档并创建一个Pull-Request
• 修复或扩展插件的源代码并创建一个Pull-Request
• 添加更多测试并创建一个Pull-Request
• 为问题或问题创建一个issue

如果此项目帮助您减少开发时间，您可以请我喝一杯咖啡：）

内容列表

• 概述

  • 版本
  • 扩展功能

• 安装和配置

  • 安装
  • 配置

• 使用方法

  • 方法1 查询信息
  • 方法2 RBAC用户模型
  • 方法3 创建和修改对象

• 为开发者

  • 测试

版本

当前版本：yii2-adldap-module 从标签v6.0.0开始的版本保留给Adldap2 v10.*。相应的Adldap2存储库为 https://github.com/Adldap2/Adldap2/tree/master

如果您正在浏览Adldap2的GitHub存储库，请记住这一点

扩展功能

自2014年1月29日以来已经走了很长的路，添加了许多功能。我注意到自己可能需要简短概述，以便每个人都能看到可能的内容。

简单 方法 1

• 仅从活动目录查询信息。

与方法 2深度集成。

• 无需在yii2中做任何操作，即可使用活动目录用户登录。唯一需要执行的操作是创建一个活动目录用户并将其添加到活动目录中的组。
• 全面支持yii2的RBAC概念。
• 默认使用sAMAccountName登录 Edvlerblog\Adldap2\model\UserDbLdap.php::findByUsername($username)。但也可以使用任何属性 Edvlerblog\Adldap2\model\UserDbLdap.php::findByAttribute($attribute,$searchValue)。
• 默认情况下，登录时会检查活动目录账户状态和组分配。根据结果，登录可能成功或失败。
• 您可以访问用户的每个活动目录属性。 方法 2
• 此yii2扩展高度可配置。

使用方法 3: docs/CREATE_MODIFY_DELETE_OBJECTS.md创建、修改或删除活动目录对象。

• 多亏了Adldap2，创建、修改或删除对象变得非常简单。

如何开始？

• 我的建议是您应该从方法 1 开始。按照以下描述进行配置，并进行一些简单的查询。如果您了解了它的工作方式，您可以尝试方法 2。

如果您有任何问题...

• 请参阅每个方法的单独howto。
• 方法 1: docs/USAGE_WITHOUT_USER_MODEL.md
• 方法 2: docs/USAGE_WITH_USER_MODEL.md
• 方法 3: docs/CREATE_MODIFY_DELETE_OBJECTS.md
• 打开一个问题或拉取请求。

安装

安装此扩展的首选方式是通过Composer。

运行以下命令

php composer.phar require edvlerblog/yii2-adldap-module "^6.0.0"

或添加

"edvlerblog/yii2-adldap-module": "^6.0.0"

到您的composer.json的require部分

配置

将此代码添加到应用程序配置的components部分（例如，advanced模板的config/main.php或基本模板的config/web.php）

'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.
				'hosts'    => ['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.
				'username'        => 'username_ldap_access@example.lan',
				'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.
				'hosts'    => ['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.
				'username'        => 'username_ldap_access@test.lan',
				'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

有关所有配置选项，请参阅官方文档。
https://adldap2.github.io/Adldap2/#/setup?id=options

用法 - 方法 1、方法 2 和方法 3

使用方法 1：无用户模型的使用

如果您需要从活动目录查询有关用户的一些信息，这将是最简单的方法。无需额外的配置，您只需将上述描述的配置添加到您的components部分即可。

您将像在常规Yii2风格中使用扩展

//...
$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['sn'][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

带有示例的进一步文档： docs/USAGE_WITHOUT_USER_MODEL.md

也可以修改属性。请参阅方法 3。

使用方法 2：与用户模型深度集成到yii2框架中

第二种方法使您能够使用特殊用户模型对Active Directory进行用户身份验证。它与yii2的RBAC安全概念集成得非常好 (https://yiiframework.cn/doc-2.0/guide-security-authorization.html#rbac)。

您可以使用yii2用户集成的一切功能。

一些示例

//...
//Has user a permission?
$hasPermission = \Yii::$app->user->can('permissionDisplayDetailedAbout');


//Query informations from Active Directory. You can use it in a controller, a view, everywhere in yii2!
if (!\Yii::$app->user->isGuest) {
    //Get the yii2 identitiy, which was set by the Yii::$app->user->login(..,..) function
    //See model/LoginForm.php in the basic template for the login logic
    $yii2IdentityObject = \Yii::$app->user->identity;
    
    $rolesOfUser = \Yii::$app->authManager->getRolesByUser($yii2IdentityObject->getId());
    echo '<pre>' . print_r($rolesOfUser,true) . '</pre>';
    
    //Get the Ldap object for the user.
    //$ldapObject holds a class of type Adldap\Models\User from the Adldap project!
    //No performance issues, because the queryLdapUserObject function uses a cache.
    $ldapObject = $yii2IdentityObject->queryLdapUserObject();
    
    //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 of a user model:
    // https://adldap2.github.io/Adldap2/#/models/user
}
//...

如果您使用Edvlerblog\Adldap2\model\UserDbLdap.php类，您可以在yii2中执行诸如登录用户但无需在yii2中创建用户等操作。创建用户、分配角色和与Active Directory验证密码等任务都可以自动从Edvlerblog\Adldap2\model\UserDbLdap.php类中完成。

例如，想象以下情况

• 您在Active Directory中创建了一个用户，并将该用户分配给了以yii2_开头的组（例如：yii2_example_group）。
• 在yii2中存在一个同名角色（yii2_example_group），该角色已分配了一些权限。

如果您尝试使用新用户登录，该用户将在yii2中自动创建，并在登录时自动分配角色yii2_example_group。
对于人类来说，这是透明的。人类唯一能得到的反馈是成功登录以及可以使用他有权访问的功能。

有关设置和示例的进一步文档： docs/USAGE_WITH_USER_MODEL.md

使用方法3：创建、修改和删除Active Directory对象

Adldap2提供创建、修改和删除Active Directory对象的功能。有关文档，请参阅https://adldap2.github.io/Adldap2/#/models/model。

先决条件

• 要创建或修改Active Directory对象的属性，请使用具有更改对象属性权限的绑定用户配置（一种脏但非常不建议的方法是将绑定用户添加到域管理员组）！
• 对于某些操作，如更改密码，您需要SSL/TLS连接。有关更多信息，请参阅配置。

一个示例：修改用户的显示名称

// https://adldap2.github.io/Adldap2/#/searching?id=finding-a-record-by-a-specific-attribute
// Step 1: Query the ldap object (via method 1 or method 2) 
$un = 'testuser';
$ldapObject = \Yii::$app->ad->getProvider('default')->search()->findBy('sAMAccountname', $un);

// Step 2: Update the attribute
// 
$ldapObject->setDisplayName('Fancy New Displayname');

// Step 3: Save an check return value
// https://adldap2.github.io/Adldap2/#/models/model?id=attributes
// https://adldap2.github.io/Adldap2/#/models/model?id=updating-attributes
if ($ldapObject->save()) {
    echo "// Displayname successfully updated.";
} else {
    echo "// There was an issue updating this user.";
} 

进一步文档： docs/CREATE_MODIFY_DELETE_OBJECTS.md

测试

本节仅针对可能扩展功能的功能开发者。

以下是一些测试类

• tests/InitialTest.php：删除、创建和修改用户和组，并检查结果
• tests/UserModelTest.php：测试src/model/UserDbLdap.php

对于UserModelTest测试，需要按照以下方式设置深度集成：docs/USAGE_WITH_USER_MODEL.md

使用方法

• 使用yii2中的phpunit。它位于vendor\bin\phpunit。
• 从模板tests\base\TestConfigSample.php创建config类tests\base\TestConfig.php。

在Windows中启动测试：

// 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