README

composer require matthewslouismarie/auth-abstractor

A PHP library which aims to completely abstract the authentication logic from your PHP web application. You won't even have to create the views!

它通过充当中间件来实现这一点。只需传入HTTP请求，你将获得一个HTTP响应以及AuthenticationProcess类的对象。

文档

您可以在此处浏览auth-abstractor的API文档。

功能

• Web框架无关性：auth-abtractor可以与任何Web框架一起使用，或者根本不使用任何Web框架！
• 简单易用：auth-abstractor需要的代码量最少，即使是处理整个认证或注册过程（例如创建注册页面或登录页面）。
• 强大的功能：auth-abstractor几乎完全抽象了认证和注册过程。您只需几行代码即可创建一个完整的注册页面、登录页面等。auth-abstractor负责显示视图、散列密码和验证响应。
• 可定制：auth-abstractor可以轻松定制和扩展。可以轻松添加更多用户认证方式，并可以自定义或完全替换默认视图。

如何使用它

概述

要使用它，您首先需要创建一个AuthenticationKernel对象。此对象可以在整个Web应用程序中共享（可以注册为服务）。现在，当用户到达一个页面，比如一个登录页面，您需要创建一个新的AuthenticationProcess对象。然后，您将此对象以及HTTP请求传递给您之前创建的AuthenticationKernel对象。AuthenticationKernel返回一个HTTP响应和一个新的AuthenticationProcess。您将AuthenticationProcess存储在某个地方（例如会话中），然后将HTTP响应发送给用户。

注意：在auth-abstractor中，认证指的是认证和注册。

security-comparator是一个使用auth-abstractor来抽象整个注册和认证过程的Web应用程序。

您甚至可以查看一个页面示例，演示了如何使用auth-abstractor与Symfony一起使用。

创建AuthenticationKernel对象

您需要通过传递IApplicationConfiguration的实现来构造AuthenticationKernel。但是，您不必定义自己的IApplicationConfiguration实现。相反，您也可以简单地传递一个ApplicationConfiguration对象。

    $kernel = new AuthenticationKernel(new ApplicationConfiguration(
        'https://example.org', // HTTPS URL of your app (for U2F)
        'https://example.org/assets', // Assets base URL
        // This function is responsible for fetching members from the database.
        // It must return null if the member does not exist.
        function (string $username) use ($repo): ?IMember {
            return $repo->findOneBy([
                'username' => $username,
            ]);
        }
    ));

IMember是应用程序成员（有账户的用户）的接口。如果您已经有代表成员的类，您可以简单地使其实现IMember接口。否则，您也可以使用便利实现Member。

AuthenticationKernel是一个可以在整个Web应用程序中通用的对象，因此如果您支持依赖注入（例如Symfony）的Web应用程序，您可以将它注册为服务。

创建认证过程

用户首次访问页面，例如登录页面时，认证过程不存在。因此，您需要创建它。建议使用 AuthenticationProcessFactory 来实现

    $authProcess = $kernel
        ->getAuthenticationProcessFactory()
        ->createProcess([
            CredentialChallenge::class, // class that is part of auth-abstractor
        ]
    );

您将挑战类名数组传递给 createProcess。挑战是认证或注册过程中的一个步骤（例如，要求用户输入密码的页面，或要求用户连接他们的 U2F 设备的页面）。这些类需要是 IChallenge 的实现。当然，您可以定义自己的。 auth-abstractor 包含以下挑战

• CredentialChallenge，用于要求用户输入他们的用户名和密码，
• CredentialRegistrationChallenge，用于要求用户创建账户并给出有效的用户名和密码，
• EmailChallenge，用于要求用户输入发送到其电子邮件地址的代码。
• ExistingUsernameChallenge，用于要求用户输入一个有效、已存在的用户名。
• NamedU2fRegistrationChallenge，与 U2fChallenge 相同，但要求输入一个名称，
• PasswordChallenge，用于要求用户输入他们的密码，
• PasswordUpdateChallenge，用于要求用户找到一个新的密码，
• U2fChallenge，用于要求用户使用他们的 U2F 设备确认他们的身份。
• U2fRegistrationChallenge，用于要求用户注册一个新的 U2F 设备。

您可以将这些（即在传递给 AuthenticationProcessFactory 的数组中组合这些）结合起来。有时，特定的顺序是必要的：例如，在处理 PasswordChallenge 之前，必须知道用户的用户名。实现这一点的一种方法是在其中放置一个 ExistingUsernameChallenge。

每个挑战都依赖于一定数量的参数被定义。您在通过认证过程工厂创建认证过程时传递这些参数。

AuthenticationProcessFactory 支持附加的、可选的参数，例如，指定当前用户的用户名。

处理认证过程

您现在需要调用 AuthenticationKernel 的 processHttpRequest。

您将传递：一个 PSR-7 的 HTTP 请求表示，创建或检索的认证过程，以及一个回调。

回调需要是一个 IAuthenticationCallback 的实现，但您可以简单地实例化一个 Callback。

    $authResponse = $kernel->processHttpRequest(
        $httpRequest,
        $authProcess, // The $authProcess object just created or retrieved from session
        new Callback(
            function ($authProcess) { // if the user fails authenticating
                new Response('You tried too many login attempts!');
            },
            function ($authProcess) { // if the user succeeds logging in
                $_SESSION['logged_in'] = true;
                new Response('You\'re logged in!');
            }
        )
    );

Symfony 提供了将响应和请求转换为和从 PSR-7 对象的工具。

然后您可以以某种方式存储新的 AuthenticationProcess（例如，在会话中），稍后将其检索，而不是实例化一个新的 AuthenticationProcess 对象。当然，您返回一个 HTTP 响应。

    // store new auth_process in session
    $_SESSION['auth_process'] = $response->getAuthenticationProcess();

    // display http response to user
    return $response->getHttpResponse();

您可以在这里看到一个使用 auth-abstractor 的完整示例.

持久化更改

auth-abstractor 从不直接更改您的应用程序。它不知道您使用的是哪种 DBMS，甚至不知道您是否使用数据库！然而，在某个时候，它需要能够通知您应该持久化的更改。例如，如果您使用 CredentialRegistrationChallenge 创建认证过程，您需要将创建账户的成员持久化到某处！

这样做的方法是简单地调用 AuthenticationProcess 对象上的 getPersistOperation()。从回调的 handleSuccessfulProcess() 方法

    foreach ($authProcess->getPersistOperations() as $operation) {
        if ($operation->getType()->is(new Operation(Operation::CREATE))) {
            $member = $operation->getObject();
            if (is_a($member, IMember::class)) {
                // Saves $member in the database
            }
        }
    }

资产

为了使 U2F 注册和认证工作，您将需要 google-u2f-api.js 和 jquery。这些文件需要放在 getAssetUri() 返回的路径所在的文件夹中。

当然，您可以覆盖U2F视图，使用您自己的视图，这些视图可以使用不同的JavaScript库。

待办事项

• 不要使用硬编码的值来访问已键入的映射
• 挑战不应依赖于IAuthenticationProcess的实现
• 库应该是挑战无关的。（代码的任何部分都不应直接引用ICallenge实现，除非是仅由挑战使用的类。）目前，IApplicationConfiguration和IAuthenticationProcess与一些ICallenge规范相关联。
• 挑战是否能够直接访问已键入的映射并直接修改它？认证处理程序可以处理这个问题。这意味着挑战不需要担心已键入映射的有效性。但认证处理程序需要知道键及其关联的类型。
• 更新Composer包。