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，如下所示。注意邮件组件的 messageConfig 属性中的 from 键。有关更多选项，请查看模块。
2. 使用提供的示例 User 模型或在现有 User 模型中实现所需的接口。这些将在下一章中描述。

示例配置（请参阅 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 模块的所有功能，身份（用户）类必须实现以下接口之一或全部。

可编辑

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

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

此接口允许

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

请记住，从可编辑接口的 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），是否允许用户登录。这仅在模式为 'counter' 时有意义，密钥在注册用户时生成，并通过电子邮件发送代码。
• 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