README

PHPAuth

注意！（2020年1月10日 pr）

PHPAuth正在进行全面重写，以使代码保持最新，该项目已经搁置了很长时间，我决定再次着手处理它，确保每个人都可以使用它，而不仅仅是高级程序员。我的目标是创建一个安全、可扩展且适合所有人的认证框架。这需要一些时间，但我们已经有一些用户在使用这个代码，并且愿意提供帮助。

目标

将代码提升到最新的PHP版本，至少为v7.1到v7.4（如果在重写代码期间出现新版本，代码也将升级到该版本）
- PHP 7改进
通过添加一次性密钥（OTP，2FA等）等方式使代码更加安全
确保代码可以被每个人使用，包括初学者
编写更好的文档。
加快数据库查询速度。
优化代码。
减少问题数量。
更快地响应问题和PR。
等等！

是什么

PHPAuth是一个安全的PHP网站用户认证类，使用强大的密码哈希系统（感谢ZxcvbnPhp\Zxcvbn）和攻击拦截来确保您的网站和用户安全。

PHPAuth是一个正在进行中的项目，不是为那些不知道如何编程的人设计的，它是为那些知道自己在做什么的人设计的。我们无法帮助每个人，因为他们不理解这个类。

它不仅仅是针对初学者的！

特性

通过电子邮件和密码组合进行认证
使用bcrypt来哈希密码，这是一个安全的算法，使用昂贵的密钥设置阶段
为每个用户使用单独的128位盐，从/dev/urandom中获取，使彩虹表无用
使用PHP的PDO数据库接口，并使用预处理语句，这意味着一个高效的系统，对SQL注入具有抵抗力
在门户上任何数量的失败操作之后，拦截（或验证）攻击者IP的任何定义时间
系统不会发送或存储任何纯文本密码
可以轻松集成到大多数现有网站中，并且可以作为新项目的良好起点
轻松配置多个系统参数
允许通过SMTP或sendmail发送电子邮件
阻止注册时的垃圾邮件地址

用户行为

登录
注册
激活账户
重新发送激活邮件
重置密码
更改密码
更改电子邮件地址
删除账户
注销

要求

PHP 7.1+
MySQL / MariaDB数据库或PostGreSQL数据库

Composer支持

PHPAuth现在可以使用以下命令安装

composer require phpauth/phpauth:dev-master

然后： require 'vendor/autoload.php';

配置

数据库表config包含多个参数，允许您配置类的一些功能。

site_name：在激活和密码重置电子邮件中显示的网站名称
site_url：Auth根的URL，您安装系统的位置，不包含尾部斜杠，用于电子邮件。
site_email：用于发送激活和密码重置电子邮件的电子邮件地址
site_key：用于验证cookie以确保它们未被篡改的随机字符串，您应该修改它
site_timezone：用于正确DateTime值的时区
site_activation_page：激活电子邮件中附加到site_url的激活页面名称
site_activation_page_append_code：1用于在激活电子邮件中将/key附加到site_url以简化用户体验，应为此选项实现RESTful API
site_password_reset_page：密码重置电子邮件中附加到site_url的密码重置页面名称
site_password_reset_page_append_code：1用于在重置电子邮件中将/key附加到site_url以简化用户体验，应为此选项实现RESTful API
cookie_name：包含会话信息的cookie的名称，除非必要，否则不要更改
cookie_path：会话cookie的路径，除非必要，否则不要更改
cookie_domain：会话cookie的域名，除非必要，否则不要更改
cookie_samesite：cookie的same-site设置。默认为Strict，除非必要，否则不要更改
cookie_secure：会话cookie的HTTPS-only设置，默认情况下只允许通过HTTPS通道进行调用，除非必要，否则不要更改
cookie_http：会话cookie的HTTP only协议设置，默认为true，除非必要，否则不要更改
cookie_remember：当在登录时勾选“记住我”时，用户将保持登录状态的时间。必须遵守PHP的strtotime格式。
cookie_forget：当在登录时不勾选“记住我”时，用户将保持登录状态的时间。必须遵守PHP的strtotime格式。
cookie_renew：在允许会话续期之前，会话过期时间和最后页面加载之间允许的最大时间差。必须遵守PHP的strtotime格式。
allow_concurrent_sessions：允许用户有多个活动会话（布尔值）。如果为false（默认），登录将结束任何现有会话。
bcrypt_cost：bcrypt散列函数的算法成本，可以根据硬件能力进行更改
smtp：0使用sendmail发送电子邮件，1使用SMTP
smtp_debug：0禁用SMTP调试，1启用SMTP调试，当您遇到电子邮件/SMTP问题时很有用
smtp_host：SMTP服务器的主机名
smtp_auth：0如果SMTP服务器不需要身份验证，1如果需要身份验证
smtp_username：SMTP服务器的用户名
smtp_password：SMTP服务器的密码
smtp_port：SMTP服务器的端口号
smtp_security：NULL表示无加密，tls表示TLS加密，ssl表示SSL加密
verify_password_min_length：最小密码长度，默认为3
verify_email_min_length：最小电子邮件长度，默认为5
verify_email_max_length：最大电子邮件长度，默认为100
verify_email_use_banlist：在检查允许的电子邮件时使用banlist（参见/files/domains.json），默认为1（true）
attack_mitigation_time : 滚动尝试超时所用时间，默认为 +30 分钟。必须遵守 PHP 的 strtotime 格式。
attempts_before_verify : 在需要验证码之前，在 attack_mitigation_time 内允许的最大尝试次数。默认为 5
attempt_before_ban : 在 attack_mitigation_time 内允许的最大尝试次数，超过后暂时阻止 IP 地址。默认为 30
password_min_score : 允许的 zxcvbn 最低得分。默认为 3
translation_source: 翻译源，可能的值：'sql'（使用 .php 加载翻译），'ini'（使用 languages/.ini 文件）
table_translations : 包含所有消息翻译的表名
table_attempts : 包含所有尝试的表名（默认为 'phpauth_attempts'）
table_requests : 包含所有请求的表名（默认为 'phpauth_requests'）
table_sessions : 包含所有会话的表名（默认为 'phpauth_sessions'）
table_users : 包含所有用户的表名（默认为 'phpauth_users'）
table_emails_banned : 包含所有被禁止的电子邮件域的表名（默认为 'phpauth_emails_banned'）
recaptcha_enabled: 1 表示启用 Google reCaptcha，0 - 禁用（默认）
recaptcha_site_key: 字符串，包含公开的 reCaptcha 密钥（用于javascripts）
recaptcha_secret_key: 字符串，包含秘密的 reCaptcha 密钥

其余参数通常不需要更改。

CAPTCHA 实现

如果 isBlocked() 返回 verify，则应显示 CAPTCHA 代码。调用 checkCaptcha($captcha) 方法来验证 CAPTCHA 代码。默认情况下，此方法返回 true，但应重写以验证 CAPTCHA。

例如，如果您使用 Google 的 ReCaptcha NoCaptcha，请使用以下代码

    private function checkCaptcha($captcha)
    {
 try {

        $url = 'https://www.google.com/recaptcha/api/siteverify';
        $data = ['secret'   => 'your_secret_here',
            'response' => $captcha,
            'remoteip' => $this->getIp()];

        $options = [
            'http' => [
                'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
                'method'  => 'POST',
                'content' => http_build_query($data)
            ]
        ];

        $context  = stream_context_create($options);
        $result = file_get_contents($url, false, $context);
        return json_decode($result)->success;
    }
    catch (\Exception $e) {
        return false;
    }
}

如果不需要使用 CAPTCHA，请确保将 attempt_before_block 设置为与 attempts_before_verify 相同的值。

此外，可以调用 Auth::checkReCaptcha() 方法。

如何保护页面

使页面仅对认证用户可用非常快且简单，只需要在页面顶部几行代码

<?php

include("Config.php");
include("Auth.php");

$dbh = new PDO("mysql:host=localhost;dbname=phpauth", "username", "password");

$config = new PHPAuth\Config($dbh);
$auth   = new PHPAuth\Auth($dbh, $config);

if (!$auth->isLogged()) {
    header('HTTP/1.0 403 Forbidden');
    echo "Forbidden";

    exit();
}

?>

或

<?php

require_once 'vendor/autoload.php';

use PHPAuth\Config as PHPAuthConfig;
use PHPAuth\Auth as PHPAuth;

$dbh = new PDO("mysql:host=localhost;dbname=phpauth", "username", "password");

$config = new PHPAuthConfig($dbh);
$auth = new PHPAuth($dbh, $config);

if (!$auth->isLogged()) {
    header('HTTP/1.0 403 Forbidden');
    echo "Forbidden";

    exit();
}

?>

注意：通过 composer 安装的必需包：composer require phpauth/phpauth:dev-master!!!

在前端验证用户密码

PHPAuth 通过 addUser() 函数评估用户注册和手动添加的用户密码强度。接受密码的最低分数通过 password_min_score 配置参数控制。

在此示例中，前端基于 html，通过 php 生成。分数作为javascript变量传递

<?php echo 'let minimum_score =' . $config->password_min_score; ?>

完整示例可以在源代码中找到：/examples/html-frontend-password-strength-gui-feedback/index.php

注意：需要包含来自 database_defs 的 phpauth 表的数据库

自定义配置源

默认情况下，在 phpauth_config 数据表中定义配置。

可以定义来自其他源的自定义配置：ini 文件、其他 SQL 表或 php 数组

Config($dbh, $config_source, $config_type, $config_language)

config_source -
- 对于 'sql'：自定义配置表的名称
- 对于 'ini'：INI 文件的路径和名称（例如：'$/config/config.ini'，'$' 表示应用程序根目录）
- 对于 'array'：它是一个包含配置的数组
config_type:
- 'sql'（或空值）- 从数据库加载配置，
- 'ini' - 配置必须在 INI 文件中声明（可以使用部分提高可读性，但不会进行解析）
- 'array' - 从 $config_source（数组类型）加载配置
config_language - 网站自定义语言，作为地区值（默认为 'en_GB'）

示例

new Config($dbh); // load config from SQL table 'phpauth_config', language is 'en_GB'

new Config($dbh, 'my_config', ''); // load config from SQL table 'my_config', language is 'en_GB'

new Config($dbh, '$/config/phpauth.ini', 'ini'); // configuration will be loaded from INI file, '$' means Application basedir

new Config($dbh, $CONFIG_ARRAY, 'array'); // configuration must be defined in $CONFIG_ARRAY value

new Config($dbh, '', '', 'ru_RU'); // load configuration from default SQL table and use ru_RU locale

消息语言

PHPAuth 返回的错误和成功消息的语言可以通过在 Auth 构造函数中传递可用的语言之一来配置，作为第三个参数。如果没有提供语言参数，则使用默认的 en_GB 语言。

示例：$auth = new PHPAuth\Auth($dbh, $config, "fr_FR");

可用语言

ar-TN
bs-BA
cs_CZ
da_DK
de_DE
en_GB（默认）
es_MX
fa_IR
fr_FR
gr_GR
hu_HU
id_ID
it_IT
nl_BE
nl_NL
no_NB
pl_PL
ps_AF
pt_BR
ro_RO
ru_RU
se_SE
sk_SK
sl_SI
sr_RS
th_TH
tr_TR
uk_UA
vi_VN
zh_CN
zh_TW

文档

所有类方法都在 Wiki 中有文档说明。系统错误代码在此列出并解释此处

贡献

任何人都可以为改进或修复 PHPAuth 做出贡献，为此，您可以报告一个问题（错误、想法...）或分叉存储库，修改您的分叉，然后请求合并。

致谢

password_compat - @ircmaxell
disposable - @lavab
PHPMailer - @PHPMailer
zxcvbn-php - @bjeavons

捐赠

您可以通过捐赠来帮助我们，这样我们就可以租用服务器进行测试，我们还可以作为感谢他们的帮助而向贡献者表示感谢。

比特币：1PrXRMb9R8GkSRB8wSJ2MWhF9cc6YXCS8w

贡献者 ✨

感谢这些可爱的人 (emoji key)

此项目遵循 all-contributors 规范。欢迎任何形式的贡献！

jaredpack / phpauth

维护者

详细信息