Authentication

简介
- 数据库注意事项
快速认证
手动认证用户
- 记住用户
- 其认证方法
HTTP 基础认证
- 无状态 HTTP 基础认证
退出
- 让其他的设备上 Session 失效
社交认证
增加自定义看守器
- 闭包看守器
增加自定义用户提供器
- 用户提供器契约
- 认证契约
事件

简介

{tip} 想要快点开始？ 只需在新的 Laravel 应用上运行 php artisan make:auth 和 php artisan migrate 命令。然后，可以用浏览器访问 http://your-app.test/register 或者你在程序中定义的其他 URL 。这两个命令就可以构建好整个认证系统！

Laravel 中实现用户认证非常简单。事实上，几乎所有的东西都已经为你配置好了。其配置文件位于 config/auth.php，其中包含了用于调整认证服务行为的注释清晰的选项配置。

其核心是由 Laravel 的认证组件的「看守器」和「提供器」组成。看守器定义了该如何认证每个请求中的用户。例如， Laravel 自带的 session 看守器会使用 session 存储和 cookies来维护状态。

提供器中定义了该如何从持久化的存储数据中检索用户。 Laravel 自带支持使用 Eloquent 和数据库查询构造器来检索用户。当然，你可以根据需要自定义其他提供器。

不过不用担心，对于大多数应用而言，可能永远都不需要修改默认身份认证配置。

数据库注意事项

默认情况下， Laravel 在 app 目录中包含了一个 Eloquent 模型 App\User 。这个模型和默认的 Eloquent 认证驱动一起使用。如果你的应用不使用 Eloquent ，也可以使用 Laravel 查询构造器的 database 认证驱动。

为 App\User 模型创建数据库表结构时，确保密码字段至少长度为 60 个字符以及默认字符串长度为 255 个字符。

此外，你要验证的用户（或等效的）表要包含一个空的、长度为 100 的字符串 remember_token 。这个字段将用于存储当用户登录应用并勾选「记住我」时的令牌。

快速认证

Laravel 自带几个预构建的认证控制器，它们被放置在 App\Http\Controllers\Auth 命名空间内。 RegisterController 处理新用户注册， LoginController 处理用户认证， ForgotPasswordController 处理用于重置密码的邮件链接，而 ResetPasswordController 包含重置密码的逻辑。这些控制器都使用 trait 来引入所必要的方法。对于大多数应用而言，你根本不需要修改这些控制器。

路由

Laravel 提供了一个简单的命令来快速生成身份验证所需的路由和视图：

php artisan make:auth

该命令最好在新的应用下使用，它会生成布局、注册和登录视图以及所有的认证接口的路由。同时它还会生成 HomeController 来处理应用的登录请求。

视图

php artisan make:auth 命令会在 resources/views/auth 目录创建所有认证需要的视图。

同时， make:auth 命令还创建了 resources/views/layouts 目录，该目录包含了应用的基本布局视图。所有这些视图都是用 Bootstrap CSS 框架，你也可以根据需要对其自定义。

认证

现在，已经为认证的控制器设置好了路由和视图，你可以为应用注册和认证新用户了！你现在可以在浏览器中访问你的应用了，因为控制器已经默认包含了验证用户是否存在和保存用户到数据库中的认证逻辑（通过 traits实现的）。

自定义路径

当一个用户成功通过身份认证后，将会重定向到 /home 的 URI。你可以通过在 LoginController， RegisterController，和 ResetPasswordController 中设置 redirectTo 属性来自定义重定向的路径：

protected $redirectTo = '/';

接下来，修改 RedirectIfAuthenticated 中间件的 handle 方法以便在重定向用户时重定向到新的 URI。

如果重定向路径需要自定义生成逻辑，你可以定义 redirectTo 方法替代 redirectTo 属性：

protected function redirectTo()
{
    return '/path';
}

{提示} redirectTo 方法优先于 redirectTo 属性。

自定义用户名

Laravel 默认使用 email 字段来认证。如果你想使用其他的字段，可以在 LoginController 控制器里面定义一个 username 方法：

public function username()
{
    return 'username';
}

自定义看守器

你还可以自定义用户认证和注册的「看守器」。要实现这一功能，需要在 LoginController， RegisterController，和ResetPasswordController 中定义 guard 方法。该方法需要返回一个看守器实例：

use Illuminate\Support\Facades\Auth;
protected function guard()
{
    return Auth::guard('guard-name');
}

自定义验证 / 存储

为了修改新用户在注册时所需要填写的表单字段，或者自定义如何将新用户存储到数据库中，你可以修改 RegisterController 类。该类负责验证和创建新用户。RegisterController 类的 validator 方法包含了验证新用户的规则，你可以按照需要自定义该方法。RegisterController 的 create 方法负责使用 Eloquent ORM 在数据库中创建新的 App\User 记录。你可以根据数据库的需要自定义该方法。

检索认证用户

你可以通过 Auth facade 来访问已认证的用户：

use Illuminate\Support\Facades\Auth;
// 获取当前通过认证的用户...
$user = Auth::user();
// 获取当前通过认证的用户 ID...
$id = Auth::id();

或者，你可以通过 Illuminate\Http\Request 实例来访问已认证的用户。别忘了，类型提示的类会被自动注入到你的控制器方法中：

<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
class ProfileController extends Controller
{
    /**
     * 更新用户简介
     *
     * @param  Request  $request
     * @return Response
     */
    public function update(Request $request)
    {
        // $request->user() 返回已认证的用户的实例...
    }
}

确认当前用户是否被认证

你可以使用 Auth facade 的 check 方法来检查用户是否已认证。如果已认证，将会返回 true：

use Illuminate\Support\Facades\Auth;
if (Auth::check()) {
    // 用户已认证...
}

{提示} 虽然可以使用 check 方法确认用户是否被认证，但是在允许用户访问的某些路由 / 控制器之前，通常还是会使用中间件来验证用户是否进行过身份验证。想要了解更多信息，请查看有关路由保护的文档。

保护路由

路由中间件可以用于只允许通过认证的用户访问给定的路由。Laravel 自带了一个 auth 中间件, 它定义于 Illuminate\Auth\Middleware\Authenticate。由于这个中间件已经在HTTP 内核中注册，你所有需要做的只是把这个中间件附加到路由定义中：

Route::get('profile', function () {
    // 只有认证过的用户可以进入...
})->middleware('auth');

当然，如果你使用控制器，你可以在控制器的构造函数中调用 middleware 方法来直接将其附加到路由定义中：

public function __construct()
{
    $this->middleware('auth');
}

重定向未认证的用户

当 auth 中间件检测到一个未认证用户时，它将返回一个 401 的JSON响应，或者，如果不是 AJAX 请求，重定向用户到名为 login 的命名路由.

你可以在 app/Exceptions/Handler.php 文件中定义一个 unauthenticated 方法来修改这个行为：

use Illuminate\Auth\AuthenticationException;
protected function unauthenticated($request, AuthenticationException $exception)
{
    return $request->expectsJson()
                ? response()->json(['message' => $exception->getMessage()], 401)
                : redirect()->guest(route('login'));
}

指定看守器

当你把 auth 中间件添加到路由中时，同时也能指定使用哪个看守器进行用户认证。指定的看守器应该对应你的 auth.php 中guards 数组的一个键：

public function __construct()
{
    $this->middleware('auth:api');
}

登录限制

如果你使用 Laravel 内置的 LoginController 类，Illuminate\Foundation\Auth\ThrottlesLogins trait 已经包含在控制器中。默认的，如果用户经过多次的登录尝试，依然无法提供正确的登录凭据，那么这个用户在一分钟内将不能再次尝试登录。这基于用户的用户名/邮箱地址和他的 IP 地址形成的特定限制。

手动认证用户

当然，你不一定需要使用 Laravel 内置的认证控制器。如果你选择删除这些控制器，你将需要使用 Laravel 的认证类直接进行用户认证的管理。别担心，这很简单 !

我们将使用Auth facade 来访问 Laravel 的认证服务，所以我们需要确保在类的顶部引入 Auth facade。接下来，让我们看看 attempt 方法：

<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
class LoginController extends Controller
{
    /**
     * 处理认证尝试
     *
     * @param  \Illuminate\Http\Request $request
     *
     * @return Response
     */
    public function authenticate(Request $request)
    {
        $credentials = $request->only('email', 'password');
        if (Auth::attempt($credentials)) {
            // Authentication passed...
            return redirect()->intended('dashboard');
        }
    }
}

attempt 方法接受一个键值对数组作为其第一个参数。数组中的值将被用于在数据表中查找用户。所以，在上例中，用户将通过 email 字段的值进行检索。如果找到了这个用户，数据库中保存的哈希密码将被用来与传递给方法的数组中 password 的哈希值进行比较。你不应该将指定为密码的 password 的值进行哈希操作，因为框架将在比较前，自动对其进行hash操作。如果这两个哈希密码匹配，就会为用户开启一个已认证的会话。

如果认证成功那么 attempt 方法将返回 true。反之，会返回 false 。

重定向器上的 intended 方法将重定向用户到他们曾经希望访问的 URL，这个 URL 之前被用户认证中间件拦截了。可以给这个方法传递一个回退 URI，用于预期的地址不可用的情况。

指定额外条件

如果您愿意，除了用户的电子邮件和密码之外，您还可以为身份认证查询添加额外的条件。例如，我们可以验证用户是否标记为「激活」状态：

if (Auth::attempt(['email' => $email, 'password' => $password, 'active' => 1])) {
    // 用户是激活状态，没有被暂停，而且存在
}

{note} 在这些例子中 email 不是必需的选项，它仅用作示例。你应该使用数据库中任何与「用户名」对应的字段的名称。

访问指定的看守器实例

您可以使用Auth facade 上的 guard 方法指定要使用的看守器实例。这允许你使用完全独立的可认证模型或用户表来管理应用程序的单独部分的身份验证。

传递给 guard 方法的的看守器名称，应该与你的 auth.php 配置文件中配置的某个值对应：

if (Auth::guard('admin')->attempt($credentials)) {
    //
}

注销登录

要将用户从应用中注销，你可以使用 Auth facade 上的 logout 方法。这将清除用户会话中的认证信息：

Auth::logout();

记住用户

如果你想在应用中提供「记住我」的功能，你可以给 attempt 方法的第二个参数传入一个布尔值，这将永久保持用户的认证状态，或者直到他们手动注销登录。当然，你的 users 表必须包含名为 remember_token 的字符串字段，它将被用于保存「记住我」的令牌。

if (Auth::attempt(['email' => $email, 'password' => $password], $remember)) {
    // 这个用户被记住了...
}

{tip} 如果你使用的是 Laravel 附带的内置 LoginController，「记住」用户的恰当逻辑已经由控制器中的 trait 实现。

如果你启用了「记住」用户，你可以使用 viaRemember 方法确定用户是否正使用「记住我」的cookie令牌进行的认证：

if (Auth::viaRemember()) {
    //
}

其它认证方式

验证用户实例

如果你需要把现存的用户实例登入应用，你可以调用 login 方法并附带用户实例作为参数。给定的这个对象必须实现 Illuminate\Contracts\Auth\Authenticatable 契约。当然，Laravel自带的 App\User 模型已经实现了这个接口：

Auth::login($user);
// 登录并且「记住」给定的用户...
Auth::login($user, true);

当然，你可以指定想要使用的看守器实例：

Auth::guard('admin')->login($user);

通过 ID 验证用户

要使用用户的 ID 登录应用，你可以使用 loginUsingId 方法。这个方法接受需要认证的用户主键：

Auth::loginUsingId(1);
// 登录并且「记住」给定的用户...
Auth::loginUsingId(1, true);

仅验证用户一次

你可以在单次请求中使用 once 方法将用户登录到应用中。这将不会使用任何 Session 或者 Cookie，这意味着在构建无状态API时，此方法可能会有所帮助：

if (Auth::once($credentials)) {
    //
}

HTTP 基础认证

HTTP 基础认证提供了一种快速方法来验证你应用程序中的用户，而无需设置专用的「登录」页面。开始之前，先把 auth.basic 中间件附加到你的路由中。auth.basic 中间件已包含在 Laravel 框架中，所以你不需要定义它：

Route::get('profile', function () {
    // 只有认证过的用户可以进入...
})->middleware('auth.basic');

将中间件附加到路由后，在浏览器中访问此路由时将自动提示您输入凭据。默认的，auth.basic 中间件把用户记录上的 email 字段作为「用户名」。

FastCGI 的注意事项

如果你正使用 PHP FastCGI 模式，HTTP 基础认证可能无法正常工作。需要把下面几行添加到你的 .htaccess 文件中：

RewriteCond %{HTTP:Authorization} ^(.+)$
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

无状态 HTTP 基础认证

你也可以使用 HTTP 基础身份验证，而无需在会话中设置用户标识符cookie，这对 API 的身份验证特别有用。为此，请定义一个中间件它将调用 onceBasic 方法。如果 onceBasic 方法没有返回任何响应，那么请求就可以进一步传递到应用程序中：

<?php
namespace App\Http\Middleware;
use Illuminate\Support\Facades\Auth;
class AuthenticateOnceWithBasicAuth
{
    /**
     * 处理传入的请求
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Closure  $next
     * @return mixed
     */
    public function handle($request, $next)
    {
        return Auth::onceBasic() ?: $next($request);
    }
}

接着，注册路由中间件并将它附加到路由：

Route::get('api/user', function () {
    // 只有认证过的用户可以进入...
})->middleware('auth.basic.once');

退出

要手动把用户从应用中退出登录，你可以使用 Auth facade 上的 logout 方法。这将清除用户会话中的身份认证信息：

use Illuminate\Support\Facades\Auth;
Auth::logout();

让其它设备上的 Session 失效

Laravel 还提供了一种机制，用于将其它设备上的用户 Session 失效和「注销」，而不会使其当前设备上的 Session 失效。首先，你需要保证Illuminate\Session\Middleware\AuthenticateSession 中间件在你的app/Http/Kernel.php 类中的 web 中间件组中，并且没有被注释掉：

'web' => [
    // ...
    \Illuminate\Session\Middleware\AuthenticateSession::class,
    // ...
],

然后，你就可以使用 Auth facade 上的 logoutOtherDevices 方法。此方法要求用户提供其当前密码，你的应用程序应通过输入表单接受该密码：

use Illuminate\Support\Facades\Auth;
Auth::logoutOtherDevices($password);

{note} 当调用logoutOtherDevices方法后，用户的其它 Session 将完全失效，这意味着他们将「退出」他们之前通过身份认证的所有看守器。

添加自定义的看守器

你可以使用 Auth facade 的 extend 方法来定义自己的身份验证看守器。你应该在服务提供器中调用 extend 方法。由于 Laravel 已经附带了 AuthServiceProvider，我们可以将代码放在该提供器中：

<?php
namespace App\Providers;
use App\Services\Auth\JwtGuard;
use Illuminate\Support\Facades\Auth;
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;
class AuthServiceProvider extends ServiceProvider
{
    /**
     * 注册任意应用认证／授权服务。
     *
     * @return void
     */
    public function boot()
    {
        $this->registerPolicies();
        Auth::extend('jwt', function ($app, $name, array $config) {
            // 返回一个 Illuminate\Contracts\Auth\Guard 实例...
            return new JwtGuard(Auth::createUserProvider($config['provider']));
        });
    }
}

正如你在上面的示例中所看到的，传递给 extend 方法的回调应该返回一个实现 Illuminate\Contracts\Auth\Guard 接口的实例。这个接口包含了一些你需要在自定义的看守器中实现的方法。当你的自定义看守器定义完成之后，你可以在 auth.php 配置文件的 guards 配置中使用这个看守器：

'guards' => [
    'api' => [
        'driver' => 'jwt',
        'provider' => 'users',
    ],
],

请求闭包看守器

实现基于HTTP请求的自定义身份验证系统的最简单方法，是使用 Auth::viaRequest 方法。此方法允许您使用单个闭包来快速定义身份验证过程。

首先，在 AuthServiceProvider 的 boot 方法中调用 Auth::viaRequest 方法。viaRequest 方法接受一个看守器名称作为其第一个参数。此名称可以是描述你自定义看守器的任何字符串。传递给该方法的第二个参数应该是一个闭包函数，它接收传入的HTTP请求并返回一个用户实例，或者，如果验证失败，则为 null：

use App\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
/**
 * 注册任意应用认证／授权服务。
 *
 * @return void
 */
public function boot()
{
    $this->registerPolicies();
    Auth::viaRequest('custom-token', function ($request) {
        return User::where('token', $request->token)->first();
    });
}

当你完成了自定义看守器后，就可以在 auth.php 配置文件的 guards 配置中使用这个看守器：

'guards' => [
    'api' => [
        'driver' => 'custom-token',
    ],
],

添加自定义用户提供器

如果您没有使用传统的关系型数据库来存储用户，则需要使用自己的身份验证用户提供器来扩展 Laravel。我们将在 Auth facade上使用 provider 方法来自定义一个用户提供器：

<?php
namespace App\Providers;
use Illuminate\Support\Facades\Auth;
use App\Extensions\RiakUserProvider;
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;
class AuthServiceProvider extends ServiceProvider
{
    /**
     * 注册任何应用认证／授权服务。
     *
     * @return void
     */
    public function boot()
    {
        $this->registerPolicies();
        Auth::provider('riak', function ($app, array $config) {
            // Return an instance of Illuminate\Contracts\Auth\UserProvider...
            return new RiakUserProvider($app->make('riak.connection'));
        });
    }
}

使用 provider 方法注册提供器后，可以在 auth.php 配置文件中切换到新的用户提供器。首先，定义一个使用新驱动的 provider：

'providers' => [
    'users' => [
        'driver' => 'riak',
    ],
],

最后，你可以在 guards 配置中使用此提供器：

'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],
],

用户提供器契约

Illuminate\Contracts\Auth\UserProvider 的实现只负责从永久存储系统（如 MySQL、Riak 等）中获取 Illuminate\Contracts\Auth\Authenticatable 的实现实例。无论用户数据的存储方式或用于表示用户数据的类是什么，这两个接口都允许 Laravel 身份验证机制继续运行。

让我们来看看 Illuminate\Contracts\Auth\UserProvider 契约：

<?php
namespace Illuminate\Contracts\Auth;
interface UserProvider {
    public function retrieveById($identifier);
    public function retrieveByToken($identifier, $token);
    public function updateRememberToken(Authenticatable $user, $token);
    public function retrieveByCredentials(array $credentials);
    public function validateCredentials(Authenticatable $user, array $credentials);
}

retrieveById 函数通常接收代表用户的键，例如来自 MySQL 数据库的自动递增 ID。同时，应该检索并返回与 ID 匹配的 Authenticatable 实现。

retrieveByToken 函数通过用户唯一的 $identifier 和「记住我」 $token 来检索用户，后者存储在字段 remember_token 中。与前面的方法一样，它应该返回 Authenticatable 的实现实例。

updateRememberToken 方法用新的 $token 更新 $user 的 remember_token 字段。在成功使用「记住我」登录后或用户注销时分配新令牌。

在尝试登录应用程序时，retrieveByCredentials 方法接收 Auth::attempt 方法传递的凭证数组。然后该方法应该「查询」底层持久存储中匹配这些凭据的用户。通常，此方法将使用 $credentials['username'] 执行一个「where」查询。这个方法应该返回一个 Authenticatable 的实现实例。此方法不应尝试进行任何密码验证或身份验证。

validateCredentials 方法应该将给定的 $user 与 $credentials 进行比较，来验证用户。例如，这个方法可能应该使用 Hash::check 来比较 $user->getAuthPassword() 和 $credentials['password'] 的值。这个方法应该返回 true 或者 false 来指示密码是否有效。

认证契约

现在我们已经探讨了 UserProvider 上的每个方法，让我们来看看 Authenticatable 契约。记住，提供器中 retrieveById， retrieveByToken 和 retrieveByCredentials 方法应该返回此接口的实例：

<?php

namespace Illuminate\Contracts\Auth;

interface Authenticatable {

    public function getAuthIdentifierName();
    public function getAuthIdentifier();
    public function getAuthPassword();
    public function getRememberToken();
    public function setRememberToken($value);
    public function getRememberTokenName();

}

这个接口很简单。getAuthIdentifierName 方法应该返回用户「主键」字段的名称，而 getAuthIdentifier 应该返回用户主键的值。重申一次，在 MySQL 后台，这个主键是指自增的主键。getAuthPassword 应该返回用户的哈希密码。此接口允许身份验证系统与任何的 User 类一起使用，无论你使用的是什么ORM或存储抽象层。默认情况下，Laravel 的app 目录中包含一个 User 类，它实现了这个接口，所以你可以参考这个类来获得一个实现例子。

事件

Laravel 在身份认证过程中引发了各种事件。你可以在 EventServiceProvider 中为这些事件添加监听器：

/**
 * The event listener mappings for the application.
 *
 * @var array
 */
protected $listen = [
    'Illuminate\Auth\Events\Registered' => [
        'App\Listeners\LogRegisteredUser',
    ],

    'Illuminate\Auth\Events\Attempting' => [
        'App\Listeners\LogAuthenticationAttempt',
    ],

    'Illuminate\Auth\Events\Authenticated' => [
        'App\Listeners\LogAuthenticated',
    ],

    'Illuminate\Auth\Events\Login' => [
        'App\Listeners\LogSuccessfulLogin',
    ],

    'Illuminate\Auth\Events\Failed' => [
        'App\Listeners\LogFailedLogin',
    ],

    'Illuminate\Auth\Events\Logout' => [
        'App\Listeners\LogSuccessfulLogout',
    ],

    'Illuminate\Auth\Events\Lockout' => [
        'App\Listeners\LogLockout',
    ],

    'Illuminate\Auth\Events\PasswordReset' => [
        'App\Listeners\LogPasswordReset',
    ],
];

本文章首发在 LearnKu.com 网站上。

本文中的所有译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。