用户授权 11个月前

简介

除了提供内置的 authentication（身份验证）服务外，Laravel 还提供了一种可以很简单就进行使用的方法，来对用户与资源的授权关系进行管理。 它很安全，即使用户已经通过了「身份验证（authentication)」, 用户也可能无权对应用程序中重要的模型或数据库记录进行删除或更改。简单、条理化的系统性，是 Laravel 对授权管理的特性。

Laravel 主要提供了两种授权操作的方法: 拦截器和策略。 可以把拦截器（gates）和策略（policies）想象成路由和控制器。拦截器（Gates）提供了一种轻便的基于闭包函数的授权方法，像是路由。而策略（policies)，就像是一个控制器，对特定模型或资源，进行分组管理的逻辑规则。 在本文档中，我们将首先探讨拦截器（gates），然后研究策略（policies)。

你在构建应用程序时，不用为是仅仅使用拦截器（gates）或是仅仅使用策略（policies）而担心，并不需要在两者中进行唯一选择。大多数的应用程序都同时包含两个方法，并且同时使用两者，能够更好的进行工作。拦截器（gates），更适用于没有与任何模型或资源有关的授权操作，例如查看管理员仪表盘。与之相反，当你希望为特定的模型或资源进行授权管理时，应该使用策略（policies) 方法。

拦截器 (Gates)

编写拦截器（Gates）

拦截器（Gates）是用来确定用户是否有权执行给定操作的闭包函数。默认条件下，拦截器（Gates）的使用，是在App\Providers\AuthServiceProvider类中的 boot 函数里来规定Gate规则。拦截器（Gates）始终接收用户实例为其第一个参数，并且可以选择性的接收其他参数，例如相关的 Eloquent 模型。

在下面的例子中，我们将定义一个拦截器（Gates)，并通过调用App\Models\Post类，来实现结合用户的 POST 请求，命中给定的规则。拦截器（Gates）将通过比较用户的id，和 POST 请求中的user_id来实现这个目标：

copy
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）的定义：

copy
use App\Policies\PostPolicy; use Illuminate\Support\Facades\Gate; /** * 注册任何需要身份验证、授权服务的行为 */ public function boot(): void { Gate::define('update-post', [PostPolicy::class, 'update']); }

授权动作

如果需要通过拦截器（Gates）来对行为进行授权控制，你可以通过调用Gate中的allows或denies方法。请注意，在使用过程中，你不需要将已经通过身份验证的用户信息传递给这些方法。 Laravel 将会自动把用户信息传递给拦截器（Gates）。以下是一个典型的，在控制器中使用拦截器（Gates）进行行为授权控制的例子：

copy
<?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门面中，使用forUser方法：

copy
if (Gate::forUser($user)->allows('update-post', $post)) { // 这个用户可以提交update... } if (Gate::forUser($user)->denies('update-post', $post)) { // 这个用户不可以提交update... }

你还可以通过any或none方法来一次性授权多个行为:

copy
if (Gate::any(['update-post', 'delete-post'], $post)) { // 用户可以提交update或delete... } if (Gate::none(['update-post', 'delete-post'], $post)) { // 用户不可以提交update和delete... }

Illuminate\Auth\Access\AuthorizationException中准备了 HTTP 的 403 响应。你可以使用Gate门面中的authorize方法，来规定如果用户进行了未授权的行为时，触发AuthorizationException实例 ，该实例会自动转换返回为 HTTP 的 403 响应:

copy
Gate::authorize('update-post', $post); // 行为已获授权...

能够用于拦截器（Gates）的授权方法，(allows，denies，check，any，none， authorize，can，cannot) 和在前端进行的授权方法 Blade 指令 (@can，@cannot，@canany) 在第 2 个参数中，可以接收数组。这些数组元素作为参数传递给拦截器（Gates），在做出授权决策时可用于其他上下文:

copy
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])) { // 用户可以请求create... }

拦截器响应

到目前为止，我们只学习了拦截器（Gates）中返回布尔值的简单操作。但是，有时你需要的返回可能更复杂，比如错误消息。所以，你可以尝试使用Illuminate\Auth\Access\Response来构建你的拦截器（Gates）：

copy
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('You must be an administrator.'); });

你希望从拦截器（Gates）中返回响应时，使用Gate::allows方法，将仅返回一个简单的布尔值；同时，你还可以使用Gate::inspect方法来返回拦截器（Gates）中的所有响应值：

copy
$response = Gate::inspect('edit-settings'); if ($response->allowed()) { // 行为进行授权... } else { echo $response->message(); }

在使用Gate::authorize方法时，如果操作未被授权，仍然会触发AuthorizationException, 用户验证（authorization）响应提供的错误消息，将传递给 HTTP 响应：

copy
Gate::authorize('edit-settings'); // 行为进行授权...

当一个操作通过 Gate 被拒绝时，返回一个403HTTP 响应；然而，有时返回一个可选的HTTP状态代码是有用的。你可以使用Illuminate\Auth\Access\Response类上的denyWithStatus静态构造函数自定义授权检查失败返回的HTTP状态代码：

copy
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方法:

copy
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方法定义一个闭包，在所有其他授权检查之前运行:

copy
use App\Models\User; use Illuminate\Support\Facades\Gate; Gate::before(function (User $user, string $ability) { if ($user->isAdministrator()) { return true; } });

如果before返回的是非 null 结果，则该返回将会被视为最终的检查结果。

你还可以使用after方法，来定义在所有授权拦截规则执行后，再次进行授权拦截规则判定：

copy
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::allowIf和Gate::denyIf方法执行这些类型的「内联」授权检查：

copy
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:policyArtisan 命令生成策略。生成的策略将放置在app/Policies目录中。如果应用程序中不存在此目录，Laravel 将自动创建：

copy
php artisan make:policy PostPolicy

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

copy
php artisan make:policy PostPolicy --model=Post

注册策略

创建了策略类之后，还需要对其进行注册。注册策略是告知 Laravel 在授权针对给定模型类型的操作时使用哪个策略。

新的 Laravel 应用程序中包含的App\Providers\AuthServiceProvider包含一个policies属性，它将 Eloquent 模型映射到其相应的策略。 注册策略将指示 Laravel 在授权针对给定 Eloquent 模型的操作时使用哪个策略：

copy
<?php namespace App\Providers; use App\Models\Post; use App\Policies\PostPolicy; use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider; use Illuminate\Support\Facades\Gate; class AuthServiceProvider extends ServiceProvider { /** * 应用程序的策略映射。 * * @var array */ protected $policies = [ Post::class => PostPolicy::class, ]; /** * 注册任何应用程序身份验证/授权服务。 */ public function boot(): void { // ... } }

只要模型和策略遵循标准的 Laravel 命名约定，Laravel 就可以自动发现策略，而不是手动注册模型策略。具体来说，策略必须位于包含模型的目录或其上方的「Policies」目录中。 因此，例如，模型可以放置在app/Models目录中，而策略可以放置在app/Policies目录中。在这种情况下，Laravel 将检查app/Models/Policies然后app/Policies中的策略。此外，策略名称必须与模型名称匹配并具有「策略」后缀。 因此，User模型将对应于UserPolicy策略类。

如果要自定义策略的发现逻辑，可以使用Gate::guessPolicyNamesUsing方法注册自定义策略发现回调。通常，应该从应用程序的AuthServiceProvider的boot方法调用此方法：

copy
use Illuminate\Support\Facades\Gate; Gate::guessPolicyNamesUsing(function (string $modelClass) { // 返回给定模型的策略类的名称… });

编写策略

策略方法

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

该update方法将接收一个User和一个Post实例作为其参数，并应返回true或false，指示用户是否有权更新给定的Post。因此，在本例中，我们将验证用户的id是否与 Post 上的user_id匹配：

copy
<?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; } }

你可以继续根据需要为策略授权的各种操作定义其他方法。例如，你可以定义view或delete方法来授权各种与Post相关的操作，但请记住，你可以自由地为策略方法命名任何你喜欢的名称。

如果你在 Artisan 控制台生成策略时使用了--model选项，它将包含用于viewAny、view、 create、update、delete、restore和forceDelete操作。

策略响应

到目前为止，我们只检查了返回简单布尔值的策略方法。但是，有时你可能希望返回更详细的响应，包括错误消息。为此，你可以从你的策略方法返回一个Illuminate\Auth\Access\Response实例：

copy
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方法来获取返回的完整授权响应：

copy
use Illuminate\Support\Facades\Gate; $response = Gate::inspect('update', $post); if ($response->allowed()) { // 操作已被授权… } else { echo $response->message(); }

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

copy
Gate::authorize('update', $post); // 该操作已授权通过...

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

copy
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方法:

copy
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 方法做授权。例如，如果你正在创建一个博客，你可能希望确定一个用户是否被授权创建任何文章，在这种情况下，你的策略方法应该只期望接收一个用户实例：

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

Guest 用户

默认情况下，如果传入的 HTTP 请求不是经过身份验证的用户发起的，那么所有的拦截器（gates）和策略（policies）会自动返回false。但是，你可以通过声明一个「optional」类型提示或为用户参数定义提供一个null默认值，从而允许这些授权检查通过你的拦截器（gates）和策略（policies）：

copy
<?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方法将在策略上的所有方法之前执行，这样就使你有机会在实际调用预期的策略方法之前就已经授权了操作。该功能常用于授权应用程序管理员来执行任何操作：

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

如果你想拒绝特定类型用户的所有授权检查，那么你可以从before方法返回false。如果返回null，则授权检查将通过策略方法进行。

使用策略进行授权操作

通过用户模型

Laravel 应用程序中的App\Models\User型提供了两个用于授权操作的方法：can和cannot。can和cannot方法接收你希望授权的操作名称和相关模型。例如，让我们确定一个用户是否被授权更新给定的App\Models\Post模型，这通常在控制器方法中实现：

copy
<?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方法将尝试调用基于 Gate 的闭包，该闭包将匹配给定的操作名称。

请记住，某些操作可能对应着「不需要模型实例」的策略方法，比如create。在这些情况下，你可以将类名传递给can方法，类名将用于确定在授权操作时使用哪个策略：

copy
<?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'); } }

通过控制器辅助函数

除了给App\Models\User模型提供了有用方法，Laravel 还给任何控制器提供了一个有用的 authorize 方法，这些控制器要继承（extends）App\Http\Controllers\Controller基类。

与can方法一样，authorize方法接收你希望授权的操作名称和相关模型，如果该操作未被授权，该方法将抛出Illuminate\Auth\Access\AuthorizationException异常，Laravel 的异常处理程序将自动将该异常转换为一个带有 403 状态码的 HTTP 响应：

copy
<?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 { /** * 更新指定的博客文章 * * @throws \Illuminate\Auth\Access\AuthorizationException */ public function update(Request $request, Post $post): RedirectResponse { $this->authorize('update', $post); // 当前用户可以更新博客文章… return redirect('/posts'); } }

如前所述，一些策略方法 如create不需要模型实例，在这些情况下，你应该给authorize方法传递一个类名，该类名将用来确定在授权操作时使用哪个策略：

copy
use App\Models\Post; use Illuminate\Http\RedirectResponse; use Illuminate\Http\Request; /** * 创建一个新的博客文章。 * * @throws \Illuminate\Auth\Access\AuthorizationException */ public function create(Request $request): RedirectResponse { $this->authorize('create', Post::class); // 当前用户可以创建博客帖子… return redirect('/posts'); }

如果你正在使用资源控制器，你可以在控制器的构造方法中使用authorizeResource方法，该方法将把适当的can中间件定义附加到资源控制器的方法上。

该authorizeResource方法的第一个参数是模型的类名，第二个参数是包含模型 ID 的 路由/请求参数的名称。你应该确保你的资源控制器是使用 --model 标志创建的，这样它才具有所需的方法签名和类型提示。

copy
<?php namespace App\Http\Controllers; use App\Http\Controllers\Controller; use App\Models\Post; use Illuminate\Http\Request; class PostController extends Controller { /** * 创建控制器实例 */ public function __construct() { $this->authorizeResource(Post::class, 'post'); } }

以下控制器方法将映射到其相应的策略方法。当请求被路由到给定的控制器方法时，会在控制器方法执行之前自动调用相应的策略方法：

| 控制器方法 | 策略方法 | | --- | --- | | index | viewAny | | show | view | | create | create | | store | create | | edit | update | | update | update | | destroy | delete |

通过中间件

Laravel 包含一个中间件，可以在传入的请求到达路由或控制器之前对操作进行授权。默认情况下，Illuminate\Auth\Middleware\Authorize中间件会在App\Http\Kernel中的can键中被指定。让我们来看一个使用can中间件授权用户更新博客文章的例子：

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

在这个例子中，我们给can中间件传递了两个参数。第一个是我们希望授权操作的名称，第二个是我们希望传递给策略方法的路由参数。在这个例子中，当我们使用了隐式模型绑定后，一个App\Models\Post模型就将被传递给对应的策略方法。如果用户没有被授权执行给定操作的权限，那么中间件将会返回一个带有 403 状态码的 HTTP 响应。

为了方便起见，你也可以使用can方法将can中间件绑定到你的路由上：

copy
use App\Models\Post; Route::put('/post/{post}', function (Post $post) { // 当前用户可以更新文章... })->can('update', 'post');

同样的，一些策略方法不需要模型实例，比如create。在这些情况下，你可以给中间件传递一个类名。这个类名将用来确定在授权操作时使用哪个策略：

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

在一个中间件中定义整个类名会变得难以维护。因此，你也可以选择使用can方法将can中间件绑定到你的路由上：

copy
use App\Models\Post; Route::post('/post', function () { // 当前用户可以创建文章 })->can('create', Post::class);

通过 Blade 模板

当编写 Blade 模板时，你可能希望只展示给用户有权限操作的数据。例如，你可能希望当用户具有更新文章的权限时才展示更新博客文章的表单。在这种情况下，你可以使用@can和@cannot指令：

copy
@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语句相当于下面的语句：

copy
@if (Auth::user()->can('update', $post)) <!-- 当前用户可更新的文章... --> @endif @unless (Auth::user()->can('update', $post)) <!-- 当前用户不可更新的文章... --> @endunless

你还可以确定一个用户是否被授权从给定的操作数组中执行任何操作，要做到这一点，可以使用@canany指令：

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

像大多数其他授权方法一样，如果操作不需要模型实例，你可以给@can和@cannot指令传递一个类名：

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

提供额外的上下文

在使用策略授权操作时，可以将数组作为第二个参数传递给授权函数和辅助函数。数组中的第一个元素用于确定应该调用哪个策略，其余的数组元素作为参数传递给策略方法，并可在作出授权决策时用于额外的上下文中。例如，考虑下面的 PostPolicy 方法定义，它包含一个额外的 $category 参数：

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

当尝试确认已验证过的用户是否可以更新给定的文章时，我们可以像这样调用此策略方法：