README

Usr 提供基本的用户操作，例如

• 登录和注销。
• 密码恢复和重置（如果已过期）。
• 可选电子邮件验证的注册。
• 查看和更新最小用户配置文件，以及更改密码。
• 使用良好的密码哈希。
• 用户管理。

高级功能

• 注册和恢复表单上的验证码。
• 密码短语生成器，帮助用户选择安全的密码。
• 无需修改现有的用户数据库表和模型即可更容易地集成到现有项目中。提供示例模型和迁移。
• 支持使用一次性密码进行两步认证的 Google Authenticator。
• 支持使用社交网站身份进行 OAuth 登录。

查看演示。

安装

1. 使用您首选的方法安装 Yii2
2. 通过 composer 安装包

• 运行 php composer.phar require nineinchnick/yii2-usr "dev-master" 或在 composer.json 的 require 部分添加 "nineinchnick/yii2-usr": "dev-master"
• 如果将使用一次性密码，则还安装 "sonata-project/google-authenticator"
• 如果将使用 OAuth，则还安装 "yiisoft/yii2-authclient"

1. 更新配置文件 config/web.php 如下所示。注意邮件组件消息配置属性中的 from 键。查看模块获取更多选项。
2. 使用提供的示例用户模型或在现有用户模型中实现所需接口。这些将在下一章中描述。

示例配置（有关完整选项参考，请参阅 Module.php 文件）

$config = [
    // .........
	'aliases' => [
		'@nineinchnick/usr' => '@vendor/nineinchnick/yii2-usr',
	],
	'modules' => [
		'usr' => [
			'class' => 'nineinchnick\usr\Module',
		],
	],
	'components' => [
		'user' => [
			'identityClass' => 'app\models\User',
			'loginUrl' => ['usr/login'],
		],
		'mail' => [
			'class' => 'yii\swiftmailer\Mailer',
			'useFileTransport' => YII_DEBUG,
			'messageConfig' => [
				'from' => 'noreply@yoursite.com',
			],
		],
		// ..........
	],
]

身份（用户）类的需求将在下一章中描述。

用户界面

要使用 Usr 模块的所有功能，身份（用户）类必须实现以下接口之一或全部。

可编辑

此接口允许创建新的身份（注册）和更新现有的身份。

活动/禁用和电子邮件验证

此接口允许

• 使用其属性之一查找现有的身份。
• 生成和验证用于验证电子邮件和发送恢复链接的激活键

请记住，在 Editable 接口的 save() 方法中，如果电子邮件更改，则使电子邮件无效。

密码历史

此接口允许使用可选的已用密码跟踪进行密码重置。这允许检测过期的密码并防止用户重新使用旧密码。

请参阅以下 ExpiredPasswordBehavior 描述。

OAuth

此接口允许查找与远程身份（来自外部社交网站）关联的本地身份并创建此类关联。

一次性密码

此接口允许保存和检索用于生成一次性密码的秘密。同时，还保存和检索最后使用的密码和用于生成最后密码的计数器，以防止重放攻击。

请参阅以下 OneTimePasswordFormBehavior 描述。

个人头像

允许用户上传个人头像。示例身份使用 Gravatar 提供默认图片。

可管理

允许管理用户

• 更新他们的配置文件（和图片）
• 更改密码
• 分配授权角色
• 激活/禁用并标记电子邮件为已验证
• 查看账户创建时间戳、最后配置文件更新时间戳和最后访问时间戳

自定义登录行为

可以通过将自定义行为附加到LoginForm来扩展登录操作。这是通过配置UsrModule.loginFormBehaviors属性来完成的。

yii-usr模块提供了两种这样的行为

• ExpiredPasswordBehavior
• OneTimePasswordFormBehavior

ExpiredPasswordBehavior

验证当前密码是否已过期，并强制用户在登录前更改它。

选项

• passwordTimeout - 用户在登录后需要重置密码的天数

OneTimePasswordFormBehavior

使用一次性密码进行两步验证。

选项

• authenticator - 如果为null，则设置为GoogleAuthenticator类的新实例。
• mode - 如果设置为OneTimePasswordFormBehavior::OTP_TIME或OneTimePasswordFormBehavior::OTP_COUNTER，则使用一次性密码启用两步验证。时间模式使用当前时间生成的代码，并要求用户使用外部应用程序，如Android上的Google Authenticator。计数器模式使用序列生成的代码，并将它们发送到用户的电子邮件。
• required - 即使尚未生成密钥（为null），用户是否也被允许登录。这仅在模式为'计数器'时才有意义，密钥在注册用户时生成，并通过电子邮件发送代码。
• timeout - 上次验证代码有效的秒数。

示例用法

'loginFormBehaviors' => array(
    'expiredPasswordBehavior' => array(
        'class' => 'ExpiredPasswordBehavior',
        'passwordTimeout' => 10,
    ),
    'oneTimePasswordBehavior' => array(
        'class' => 'OneTimePasswordFormBehavior',
        'mode' => OneTimePasswordFormBehavior::OTP_TIME,
        'required' => true,
        'timeout' => 123,
    ),
    // ... other behaviors
),

用户模型示例

分别在'models'和'migrations'文件夹中提供了示例ExampleUser和ExampleUserUsedPassword模型以及相应的数据库迁移。

它们可以直接通过扩展或复制并修改以更好地适应项目。

要使用提供的迁移，最好将它们复制到您的迁移目录中，并调整文件名和类名以反映当前日期和时间。它们还可以进行修改以删除不需要的功能。

Diceware即密码生成器

提供了一种简单的Diceware密码短语生成器实现，以帮助用户在需要创建一个既长又容易记住的密码短语时使用。

安装nineinchnick/diceware composer包来使用它。

更多信息请参阅Diceware密码短语主页。

使用场景

可以通过启用或禁用以下功能来创建各种场景

• 注册
• 电子邮件验证
• 账户激活

实现这些场景需要一些超出此模块范围的外部逻辑。

公开网站

用户可以自行注册。他们的账户可以立即激活或经过电子邮件验证后激活。

受控网站

用户可以注册，但为了允许他们登录，管理员必须手动激活他们的账户，可选地分配一个授权配置文件。电子邮件验证是可选的，激活可以触发电子邮件通知。

许可

MIT或BSD