laravel
6. 安全
授权

简介

除了提供内置的认证服务外,Laravel 还提供了一种简单的方法来授权用户对给定资源执行操作。例如,即使用户已通过身份验证,他们可能也未被授权更新或删除您的应用程序管理的某些 Eloquent 模型或数据库记录。Laravel 的授权功能提供了一种简单、有组织的方式来管理这些类型的授权检查。

Laravel 提供了两种主要的授权操作方式:门(Gates)策略(Policies)。可以把门(Gates)和策略(Policies)想象成路由(routes)和控制器(controllers)。门(Gates)提供了一种简单的、基于闭包的授权方法,而策略(Policies)则像控制器一样,围绕特定的模型或资源对逻辑进行分组。在本文档中,我们将首先探讨门(Gates),然后再研究策略(Policies)。

在构建应用程序时,您不需要在仅使用门(Gates)或仅使用策略(Policies)之间进行选择。大多数应用程序很可能会包含门(Gates)和策略(Policies)的某种组合,这是完全没问题的!门(Gates)最适用于与任何模型或资源无关的操作,例如查看管理员仪表板。相比之下,当您希望为特定的模型或资源授权操作时,应该使用策略(Policies)。

门(Gates)

编写门(Gates)

[!警告]
门(Gates)是学习 Laravel 授权功能基础知识的好方法;然而,在构建强大的 Laravel 应用程序时,您应该考虑使用策略(Policies)来组织您的授权规则。

门(Gates)只是确定用户是否被授权执行给定操作的闭包。通常,门(Gates)在App\Providers\AppServiceProvider类的boot方法中使用Gate外观(Facade)进行定义。门(Gates)始终将用户实例作为其第一个参数,并可以选择接收其他参数,例如相关的 Eloquent 模型。

在这个示例中,我们将定义一个门(Gate)来确定用户是否可以更新给定的App\Models\Post模型。该门(Gate)将通过比较用户的id与创建该帖子的用户的user_id来实现此目的:

use App\Models\Post;
use App\Models\User;
use Illuminate\Support\Facades\Gate;

/**
 * 引导任何应用程序服务。
 */
public function boot(): void
{
    Gate::define('update-post', function (User $user, Post $post) {
        return $user->id === $post->user_id;
    });
}

像控制器一样,门(Gates)也可以使用类回调数组来定义:

use App\Policies\PostPolicy;
use Illuminate\Support\Facades\Gate;

/**
 * 引导任何应用程序服务。
 */
public function boot(): void
{
    Gate::define('update-post', [PostPolicy::class, 'update']);
}

授权操作

要使用门(Gates)授权操作,您应该使用Gate外观(Facade)提供的allowsdenies方法。请注意,您不需要将当前经过身份验证的用户传递给这些方法。Laravel 会自动将用户传递到门(Gate)闭包中。通常在应用程序的控制器中执行需要授权的操作之前调用门(Gate)授权方法:

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use App\Models\Post;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Gate;

class PostController extends Controller
{
    /**
     * 更新给定的帖子。
     */
    public function update(Request $request, Post $post): RedirectResponse
    {
        if (! Gate::allows('update-post', $post)) {
            abort(403);
        }

        // 更新帖子...

        return redirect('/posts');
    }
}

如果您想确定除当前经过身份验证的用户之外的用户是否被授权执行操作,您可以在Gate外观(Facade)上使用forUser方法:

if (Gate::forUser($user)->allows('update-post', $post)) {
    // 该用户可以更新帖子...
}

if (Gate::forUser($user)->denies('update-post', $post)) {
    // 该用户不能更新帖子...
}

您可以使用anynone方法一次授权多个操作:

if (Gate::any(['update-post', 'delete-post'], $post)) {
    // 该用户可以更新或删除帖子...
}

if (Gate::none(['update-post', 'delete-post'], $post)) {
    // 该用户不能更新或删除帖子...
}

授权或抛出异常

如果您想尝试授权操作,并在用户未被允许执行给定操作时自动抛出Illuminate\Auth\Access\AuthorizationException,您可以使用Gate外观(Facade)的authorize方法。AuthorizationException的实例会被 Laravel 自动转换为 403 HTTP 响应:

Gate::authorize('update-post', $post);

// 该操作已授权...

提供额外上下文

用于授权能力的门(Gate)方法(allowsdeniescheckanynoneauthorizecancannot)和授权Blade 指令@can@cannot@canany)可以将数组作为其第二个参数。这些数组元素作为参数传递给门(Gate)闭包,并可在做出授权决策时用于提供额外上下文:

use App\Models\Category;
use App\Models\User;
use Illuminate\Support\Facades\Gate;

Gate::define('create-post', function (User $user, Category $category, bool $pinned) {
    if (! $user->canPublishToGroup($category->group)) {
        return false;
    } elseif ($pinned &&! $user->canPinPosts()) {
        return false;
    }

    return true;
});

if (Gate::check('create-post', [$category, $pinned])) {
    // 该用户可以创建帖子...
}

门(Gate)的响应

到目前为止,我们只研究了返回简单布尔值的门(Gates)。然而,有时您可能希望返回更详细的响应,包括错误消息。为此,您可以从您的门(Gate)中返回一个Illuminate\Auth\Access\Response

use App\Models\User;
use Illuminate\Auth\Access\Response;
use Illuminate\Support\Facades\Gate;

Gate::define('edit-settings', function (User $user) {
    return $user->isAdmin
               ? Response::allow()
                : Response::deny('您必须是管理员。');
});

即使您从门(Gate)中返回授权响应,Gate::allows方法仍将返回一个简单的布尔值;但是,您可以使用Gate::inspect方法获取门(Gate)返回的完整授权响应:

$response = Gate::inspect('edit-settings');

if ($response->allowed()) {
    // 该操作已授权...
} else {
    echo $response->message();
}

当使用Gate::authorize方法时,如果操作未被授权,它将抛出一个AuthorizationException,授权响应提供的错误消息将传播到 HTTP 响应中:

Gate::authorize('edit-settings');

// 该操作已授权...

自定义 HTTP 响应状态

当通过门(Gate)拒绝操作时,将返回403HTTP 响应;然而,有时返回替代的 HTTP 状态码可能会很有用。您可以使用Illuminate\Auth\Access\Response类的denyWithStatus静态构造函数来自定义授权检查失败时返回的 HTTP 状态码:

use App\Models\User;
use Illuminate\Auth\Access\Response;
use Illuminate\Support\Facades\Gate;

Gate::define('edit-settings', function (User $user) {
    return $user->isAdmin
               ? Response::allow()
                : Response::denyWithStatus(404);
});

因为通过404响应隐藏资源是 Web 应用程序的一种常见模式,所以为了方便提供了denyAsNotFound方法:

use App\Models\User;
use Illuminate\Auth\Access\Response;
use Illuminate\Support\Facades\Gate;

Gate::define('edit-settings', function (User $user) {
    return $user->isAdmin
               ? Response::allow()
                : Response::denyAsNotFound();
});

拦截门(Gate)检查

有时,您可能希望授予特定用户所有能力。您可以使用before方法定义一个在所有其他授权检查之前运行的闭包:

use App\Models\User;
use Illuminate\Support\Facades\Gate;

Gate::before(function (User $user, string $ability) {
    if ($user->isAdministrator()) {
        return true;
    }
});

如果before闭包返回一个非空结果,则该结果将被视为授权检查的结果。

您可以使用after方法定义一个在所有其他授权检查之后执行的闭包:

use App\Models\User;

Gate::after(function (User $user, string $ability, bool|null $result, mixed $arguments) {
    if ($user->isAdministrator()) {
        return true;
    }
});

before方法类似,如果after闭包返回一个非空结果,则该结果将被视为授权检查的结果。

内联授权

有时,您可能希望确定当前经过身份验证的用户是否被授权执行给定操作,而无需编写与该操作相对应的专用门。Laravel 允许您通过 Gate::allowIfGate::denyIf 方法执行这些类型的“内联”授权检查。内联授权不会执行任何定义的"授权前或授权后钩子"

use App\Models\User;
use Illuminate\Support\Facades\Gate;
 
Gate::allowIf(fn (User $user) => $user->isAdministrator());
 
Gate::denyIf(fn (User $user) => $user->banned());

如果操作未被授权或当前没有用户经过身份验证,Laravel 将自动抛出一个 Illuminate\Auth\Access\AuthorizationException 异常。AuthorizationException 实例会被 Laravel 的异常处理程序自动转换为 403 HTTP 响应。

创建策略

生成策略

策略是围绕特定模型或资源组织授权逻辑的类。例如,如果您的应用程序是一个博客,您可能有一个 App\Models\Post 模型和一个相应的 App\Policies\PostPolicy 来授权用户执行诸如创建或更新帖子等操作。

您可以使用 make:policy Artisan 命令生成策略。生成的策略将被放置在 app/Policies 目录中。如果您的应用程序中不存在此目录,Laravel 将为您创建:

php artisan make:policy PostPolicy

make:policy 命令将生成一个空的策略类。如果您希望生成一个具有与查看、创建、更新和删除资源相关的示例策略方法的类,您可以在执行命令时提供 --model 选项:

php artisan make:policy PostPolicy --model=Post

注册策略

策略发现

默认情况下,只要模型和策略遵循标准的 Laravel 命名约定,Laravel 就会自动发现策略。具体来说,策略必须在包含您的模型的目录或其上级目录中的 Policies 目录中。例如,模型可能放置在 app/Models 目录中,而策略可能放置在 app/Policies 目录中。在这种情况下,Laravel 将首先在 app/Models/Policies 中检查策略,然后在 app/Policies 中检查。此外,策略名称必须与模型名称匹配,并具有 Policy 后缀。因此,User 模型将对应于 UserPolicy 策略类。

如果您想定义自己的策略发现逻辑,可以使用 Gate::guessPolicyNamesUsing 方法注册一个自定义的策略发现回调。通常,此方法应在应用程序的 AppServiceProviderboot 方法中调用:

use Illuminate\Support\Facades\Gate;

Gate::guessPolicyNamesUsing(function (string $modelClass) {
    // 返回给定模型的策略类名称...
});

手动注册策略

使用 Gate 外观,您可以在应用程序的 AppServiceProviderboot 方法中手动注册策略及其对应的模型:

use App\Models\Order;
use App\Policies\OrderPolicy;
use Illuminate\Support\Facades\Gate;

/**
 * 引导任何应用程序服务。
 */
public function boot(): void
{
    Gate::policy(Order::class, OrderPolicy::class);
}

编写策略

策略方法

一旦策略类已注册,您可以为其授权的每个操作添加方法。例如,让我们在我们的 PostPolicy 上定义一个 update 方法,该方法确定给定的 App\Models\User 是否可以更新给定的 App\Models\Post 实例。

update 方法将接收一个 User 和一个 Post 实例作为其参数,并应返回 truefalse,表示用户是否被授权更新给定的 Post。因此,在这个例子中,我们将验证用户的 id 是否与帖子上的 user_id 匹配:

<?php

namespace App\Policies;

use App\Models\Post;
use App\Models\User;

class PostPolicy
{
    /**
     * 确定给定的帖子是否可以被用户更新。
     */
    public function update(User $user, Post $post): bool
    {
        return $user->id === $post->user_id;
    }
}

您可以根据需要继续在策略上定义其他方法,以授权各种相关操作。例如,您可以定义 viewdelete 方法来授权各种与 Post 相关的操作,但请记住,您可以根据自己的喜好为策略方法命名。

如果您在通过 Artisan 控制台生成策略时使用了 --model 选项,它将已经包含了 viewAnyviewcreateupdatedeleterestoreforceDelete 操作的方法。

[!NOTE]
所有策略都是通过 Laravel 服务容器解析的,允许您在策略的构造函数中类型提示任何需要的依赖项,以便它们自动注入。

策略响应

到目前为止,我们只研究了返回简单布尔值的策略方法。然而,有时您可能希望返回更详细的响应,包括错误消息。为此,您可以从策略方法中返回一个 Illuminate\Auth\Access\Response 实例:

use App\Models\Post;
use App\Models\User;
use Illuminate\Auth\Access\Response;

/**
 * 确定给定的帖子是否可以被用户更新。
 */
public function update(User $user, Post $post): Response
{
    return $user->id === $post->user_id
               ? Response::allow()
                : Response::deny('您不拥有此帖子。');
}

当从您的策略中返回授权响应时,Gate::allows 方法仍将返回一个简单的布尔值;但是,您可以使用 Gate::inspect 方法获取门返回的完整授权响应:

use Illuminate\Support\Facades\Gate;

$response = Gate::inspect('update', $post);

if ($response->allowed()) {
    // 操作被授权...
} else {
    echo $response->message();
}

当使用 Gate::authorize 方法时,如果操作未被授权,将抛出一个 AuthorizationException,授权响应提供的错误消息将传播到 HTTP 响应中:

Gate::authorize('update', $post);

// 操作被授权...

自定义 HTTP 响应状态

当通过策略方法拒绝操作时,将返回一个 403 HTTP 响应;然而,有时返回一个替代的 HTTP 状态码可能会很有用。您可以使用 Illuminate\Auth\Access\Response 类上的 denyWithStatus 静态构造函数来自定义授权检查失败时返回的 HTTP 状态码:

use App\Models\Post;
use App\Models\User;
use Illuminate\Auth\Access\Response;

/**
 * 确定给定的帖子是否可以被用户更新。
 */
public function update(User $user, Post $post): Response
{
    return $user->id === $post->user_id
               ? Response::allow()
                : Response::denyWithStatus(404);
}

因为通过 404 响应隐藏资源是 Web 应用程序的一种常见模式,所以为了方便提供了 denyAsNotFound 方法:

use App\Models\Post;
use App\Models\User;
use Illuminate\Auth\Access\Response;

/**
 * 确定给定的帖子是否可以被用户更新。
 */
public function update(User $user, Post $post): Response
{
    return $user->id === $post->user_id
               ? Response::allow()
                : Response::denyAsNotFound();
}

没有模型的方法

某些策略方法只接收当前经过身份验证的用户的实例。这种情况在授权 create 操作时最为常见。例如,如果您正在创建一个博客,您可能希望确定用户是否被授权创建任何帖子。在这些情况下,您的策略方法应该只期望接收一个用户实例:

/**
 * 确定给定的用户是否可以创建帖子。
 */
public function create(User $user): bool
{
    return $user->role == 'writer';
}

访客用户

默认情况下,如果传入的 HTTP 请求不是由经过身份验证的用户发起的,那么所有门和策略都会自动返回 false。但是,您可以通过为用户参数定义声明一个“可选”的类型提示或提供一个 null 默认值,来允许这些授权检查传递到您的门和策略中:

<?php

namespace App\Policies;

use App\Models\Post;
use App\Models\User;

class PostPolicy
{
    /**
     * 确定给定的帖子是否可以被用户更新。
     */
    public function update(?User $user, Post $post): bool
    {
        return $user?->id === $post->user_id;
    }
}

策略过滤器

对于某些用户,您可能希望在给定的策略中授权所有操作。要实现这一点,可以在策略上定义一个 before 方法。before 方法将在策略上的任何其他方法之前执行,使您有机会在实际调用预期的策略方法之前授权操作。此功能最常用于授权应用程序管理员执行任何操作:

use App\Models\User;

/**
 * 执行预授权检查。
 */
public function before(User $user, string $ability): bool|null
{
    if ($user->isAdministrator()) {
        return true;
    }

    return null;
}

如果您想拒绝为某一特定类型的用户进行所有授权检查,那么您可以从 before 方法中返回 false。如果返回 null,授权检查将传递到策略方法。

[!WARNING]
如果策略类中不包含与正在检查的能力名称匹配的方法名称,则不会调用该策略类的 before 方法。

使用策略授权操作

通过用户模型

您的 Laravel 应用程序中包含的 App\Models\User 模型包含两个有助于授权操作的方法:cancannotcancannot 方法接收您希望授权的操作名称以及相关模型。例如,让我们确定用户是否被授权更新给定的 App\Models\Post 模型。通常,这将在控制器方法中完成:

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use App\Models\Post;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class PostController extends Controller
{
    /**
     * 更新给定的帖子。
     */
    public function update(Request $request, Post $post): RedirectResponse
    {
        if ($request->user()->cannot('update', $post)) {
            abort(403);
        }

        // 更新帖子...

        return redirect('/posts');
    }
}

如果为给定模型注册了策略,则 can 方法将自动调用适当的策略并返回布尔结果。如果未为模型注册策略,则 can 方法将尝试调用与给定操作名称匹配的基于闭包的门。

不需要模型的操作

请记住,某些操作可能对应于像 create 这样不需要模型实例的策略方法。在这些情况下,您可以将类名传递给 can 方法。该类名将用于确定在授权操作时使用哪个策略:

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use App\Models\Post;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class PostController extends Controller
{
    /**
     * 创建一个帖子。
     */
    public function store(Request $request): RedirectResponse
    {
        if ($request->user()->cannot('create', Post::class)) {
            abort(403);
        }

        // 创建帖子...

        return redirect('/posts');
    }
}

通过 Gate 外观

除了为 App\Models\User 模型提供的有用方法外,您还可以始终通过 Gate 外观的 authorize 方法授权操作。

can 方法一样,此方法接受您希望授权的操作名称以及相关模型。如果操作未被授权,authorize 方法将抛出 Illuminate\Auth\Access\AuthorizationException 异常,Laravel 异常处理程序将自动将其转换为具有 403 状态码的 HTTP 响应:

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use App\Models\Post;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Gate;

class PostController extends Controller
{
    /**
     * 更新给定的博客帖子。
     *
     * @throws \Illuminate\Auth\Access\AuthorizationException
     */
    public function update(Request $request, Post $post): RedirectResponse
    {
        Gate::authorize('update', $post);

        // 当前用户可以更新博客帖子...

        return redirect('/posts');
    }
}

不需要模型的操作

如前所述,像 create 这样的一些策略方法不需要模型实例。在这些情况下,您应该将类名传递给 authorize 方法。该类名将用于确定在授权操作时使用哪个策略:

use App\Models\Post;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Gate;

/**
 * 创建一个新的博客帖子。
 *
 * @throws \Illuminate\Auth\Access\AuthorizationException
 */
public function create(Request $request): RedirectResponse
{
    Gate::authorize('create', Post::class);

    // 当前用户可以创建博客帖子...

    return redirect('/posts');
}

通过中间件

Laravel 包含一个中间件,该中间件可以在传入请求甚至到达您的路由或控制器之前授权操作。默认情况下,Illuminate\Auth\Middleware\Authorize 中间件可以使用 can 中间件别名 附加到路由,该别名由 Laravel 自动注册。让我们探讨一个使用 can 中间件授权用户可以更新帖子的示例:

use App\Models\Post;

Route::put('/post/{post}', function (Post $post) {
    // 当前用户可以更新帖子...
})->middleware('can:update,post');

在这个示例中,我们向 can 中间件传递了两个参数。第一个是我们希望授权的操作名称,第二个是我们希望传递给策略方法的路由参数。在这种情况下,由于我们使用了隐式模型绑定,一个 App\Models\Post 模型将被传递给策略方法。如果用户未被授权执行给定操作,中间件将返回具有 403 状态码的 HTTP 响应。

为了方便起见,您也可以使用 can 方法将 can 中间件附加到您的路由:

use App\Models\Post;

Route::put('/post/{post}', function (Post $post) {
    // 当前用户可以更新帖子...
})->can('update', 'post');

不需要模型的操作

同样,像 create 这样的一些策略方法不需要模型实例。在这些情况下,您可以将类名传递给中间件。该类名将用于确定在授权操作时使用哪个策略:

Route::post('/post', function () {
    // 当前用户可以创建帖子...
})->middleware('can:create,App\Models\Post');

在字符串中间件定义中指定整个类名可能会变得很麻烦。因此,您可以选择使用 can 方法将 can 中间件附加到您的路由:

use App\Models\Post;

Route::post('/post', function () {
    // 当前用户可以创建帖子...
})->can('create', Post::class);

通过 Blade 模板

在编写 Blade 模板时,您可能希望仅在用户被授权执行给定操作时才显示页面的一部分。例如,您可能希望仅在用户实际可以更新博客帖子时才显示更新表单。在这种情况下,您可以使用 @can@cannot 指令:

@can('update', $post)
    <!-- 当前用户可以更新帖子... -->
@elsecan('create', App\Models\Post::class)
    <!-- 当前用户可以创建新帖子... -->
@else
    <!--... -->
@endcan
 
@cannot('update', $post)
    <!-- 当前用户不能更新帖子... -->
@elsecannot('create', App\Models\Post::class)
    <!-- 当前用户不能创建新帖子... -->
@endcannot

这些指令是编写 @if@unless 语句的便捷快捷方式。上面的 @can@cannot 语句等同于以下语句:

@if (Auth::user()->can('update', $post))
    <!-- 当前用户可以更新帖子... -->
@endif
 
@unless (Auth::user()->can('update', $post))
    <!-- 当前用户不能更新帖子... -->
@endunless

您还可以确定用户是否被授权从给定的操作数组中执行任何操作。要实现此目的,请使用 @canany 指令:

@canany(['update', 'view', 'delete'], $post)
    <!-- 当前用户可以更新、查看或删除帖子... -->
@elsecanany(['create'], \App\Models\Post::class)
    <!-- 当前用户可以创建帖子... -->
@endcanany

不需要模型的操作

与大多数其他授权方法一样,如果操作不需要模型实例,您可以将类名传递给 @can@cannot 指令:

@can('create', App\Models\Post::class)
    <!-- 当前用户可以创建帖子... -->
@endcan
 
@cannot('create', App\Models\Post::class)
    <!-- 当前用户不能创建帖子... -->
@endcannot

提供额外上下文

在使用策略授权操作时,您可以将数组作为第二个参数传递给各种授权函数和助手。数组的第一个元素将用于确定应调用哪个策略,而数组的其余元素将作为参数传递给策略方法,并可在做出授权决策时用于提供额外上下文。例如,考虑以下包含额外 $category 参数的 PostPolicy 方法定义:

/**
 * 确定给定的帖子是否可以由用户更新。
 */
public function update(User $user, Post $post, int $category): bool
{
    return $user->id === $post->user_id &&
           $user->canUpdateCategory($category);
}

当尝试确定经过身份验证的用户是否可以更新给定的帖子时,我们可以像这样调用此策略方法:

/**
 * 更新给定的博客帖子。
 *
 * @throws \Illuminate\Auth\Access\AuthorizationException
 */
public function update(Request $request, Post $post): RedirectResponse
{
    Gate::authorize('update', [$post, $request->category]);

    // 当前用户可以更新博客帖子...

    return redirect('/posts');
}

授权与 Inertia

尽管授权必须始终在服务器上处理,但为您的前端应用程序提供授权数据以便正确呈现应用程序的 UI 通常会很方便。Laravel 没有为向基于 Inertia 的前端公开授权信息定义必需的约定。

但是,如果您正在使用 Laravel 的基于 Inertia 的入门套件之一,您的应用程序已经包含一个 HandleInertiaRequests 中间件。在这个中间件的 share 方法中,您可以返回将提供给应用程序中所有 Inertia 页面的共享数据。此共享数据可以作为为用户定义授权信息的方便位置:

<?php
 
namespace App\Http\Middleware;
 
use App\Models\Post;
use Illuminate\Http\Request;
use Inertia\Middleware;
 
class HandleInertiaRequests extends Middleware
{
    //...
 
    /**
     * 定义默认共享的属性。
     *
     * @return array<string, mixed>
     */
    public function share(Request $request)
    {
        return [
           ...parent::share($request),
            'auth' => [
                'user' => $request->user(),
                'permissions' => [
                    'post' => [
                        'create' => $request->user()->can('create', Post::class),
                    ],
                ],
            ],
        ];
    }
}