用户授权

由学院君创建于4年前, 最后更新于 4年前版本号 #5 6047 views 2 likes 0 collects

简介

除了提供开箱即用的认证服务之外，Laravel 还提供了一个简单的方式来管理授权逻辑以便控制对资源的访问权限。和认证一样，在 Laravel 中实现授权很简单，主要有两种方式：Gate 和 Policy。

可以将 Gate 和 Policy 分别看作路由和控制器，Gate 提供了简单的基于闭包的方式进行授权，而 Policy 和控制器一样，对特定模型或资源上的复杂授权逻辑进行分组，本着由简入繁的思路，我们首先来看 Gate，然后再看 Policy。

不要将 Gate 和 Policy 看作互斥的东西，实际上，在大多数应用中我们会混合使用它们，这很有必要，因为 Gate 通常用于与模型或资源无关的权限，比如访问管理后台，与之相反，Policy 则用于对指定模型或资源的动作进行授权。

Gate

编写 Gate

Gate 是用于判断用户是否有权进行某项操作的闭包，通常使用 Gate 门面定义在 App\Providers\AuthServiceProvider 类中。Gate 总是接收用户实例作为第一个参数，还可以接收相关的 Eloquent 模型实例作为额外参数：

/**
 * 注册任意认证/授权服务.
 *
 * @return void
 */
public function boot()
{
    $this->registerPolicies();
    
    Gate::define('edit-settings', function ($user) {
        return $user->isAdmin;
    });
    
    Gate::define('update-post', function ($user, $post) {
        return $user->id === $post->user_id;
    });
}

Gate 还可以通过使用 Class@method 风格的回调字符串定义，和控制器一样：

use App\Policies\PostPolicy;

/**
 * Register any authentication / authorization services.
 *
 * @return void
 */
public function boot()
{
    $this->registerPolicies();

    Gate::define('update-post', [PostPolicy::class, 'update']);
}

授权动作

要使用 Gate 授权某个动作，可以使用 allows 或 denies 方法，需要注意的是你可以不传用户实例到这些方法，Laravel 会自动将用户实例（当前用户）传递到 Gate 闭包：

if (Gate::allows('edit-settings')) {
    // The current user can edit settings
}
    
if (Gate::allows('update-post', $post)) {
    // 当前用户可以更新文章...
}
    
if (Gate::denies('update-post', $post)) {
    // 当前用户不能更新文章...
}

注：这种情况下，对于未登录用户所有权限校验都会返回 false。

如果你想要判断指定用户（非当前用户）是否有权进行某项操作，可以使用 Gate 门面上的 forUser 方法：

if (Gate::forUser($user)->allows('update-post', $post)) {
    // 当前用户可以更新文章...
}
    
if (Gate::forUser($user)->denies('update-post', $post)) {
    // 当前用户不能更新文章...
}

你可以通过 any 或者 none 方法一次授权多个动作：

if (Gate::any(['update-post', 'delete-post'], $post)) {
    // The user can update or delete the post
}
    
if (Gate::none(['update-post', 'delete-post'], $post)) {
    // The user cannot update or delete the post
}

授权还是抛出异常

如果你想要尝试授权一个动作并且在用户不允许执行给定动作时抛出一个 Illuminate\Auth\Access\AuthorizationException 异常，可以使用 Gate::authorize 方法。AuthorizationException 会被自动转化为 403 HTTP 响应：

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

// The action is authorized...

提供附加上下文

用于授权的 Gate 方法（allows、denies、check、any、none、authorize、can、cannot）和 Blade 授权指令（@can、@cannot、@canany）可以接收一个数组作为第二个参数，这些数组元素会以参数形式传递给 Gate，用于在做授权决定时作为附加的上下文信息：

Gate::define('create-post', function ($user, $category, $extraFlag) {
    return $category->group > 3 && $extraFlag === true;
});
    
if (Gate::check('create-post', [$category, $extraFlag])) {
    // The user can create the post...
}

Gate 响应

到目前为止，我们只检查了返回简单布尔值的 Gate，有时候你可能希望返回一个更加具体的响应，比如包含错误信息，要实现这个功能，可以从 Gate 中返回 Illuminate\Auth\Access\Response：

use Illuminate\Support\Facades\Gate;
use Illuminate\Auth\Access\Response;
    
Gate::define('edit-settings', function ($user) {
    return $user->isAdmin
                ? Response::allow()
                : Response::deny('You must be a super administrator.');
});

当我们从 Gate 中返回授权响应时，Gate::allows 方法仍然返回的是布尔值，只不过你还可以使用 Gate::inspect 方法获取从 Gate 返回的完整授权响应：

$response = Gate::inspect('edit-settings', $post);
    
if ($response->allowed()) {
    // The action is authorized...
} else {
    echo $response->message();
}

当然，使用 Gate::authorize 方法在授权失败抛出 AuthorizationException 异常时，授权响应提供的错误信息将会被转化为 HTTP 响应：

Gate::authorize('edit-settings', $post);
    
// The action is authorized...

拦截 Gate 检查

有时候，你可能想要分配所有权限给指定用户，这可以通过在 before 方法中定义一个回调来实现，该回调会在所有授权检查之前调用：

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

如果 before 回调返回一个非 null 结果，该结果将作为检查结果返回，不再执行后续检查。

你还可以使用 after 方法定义一个回调在所有授权检查之后执行：

Gate::after(function ($user, $ability, $result, $arguments) {
    if ($user->isSuperAdmin()) {
        return true;
    }
});

和 before 检查类似，如果 after 回调返回的是非 null 结果，该结果将作为检查结果返回。

创建 Policy

生成 Policy 类

Policy（策略）是用于组织基于特定模型或资源的授权逻辑类，例如，如果你开发的是一个博客应用，可以有一个 Post 模型和与之对应的 PostPolicy 来授权用户创建或更新博客的动作。

我们使用 Artisan 命令 make:policy 来生成一个 Policy 类，生成的 Policy 类位于 app/Policies 目录下，如果这个目录之前不存在，Laravel 会自动为我们创建：

php artisan make:policy PostPolicy

make:policy 命令会生成一个空的 Policy 类，如果你想要生成一个包含基本 CRUD 策略方法的 Policy 类，在执行该命令的时候可以通过 --model 指定相应模型：

php artisan make:policy PostPolicy --model=Post

注：所有策略类都通过服务容器进行解析，这样在策略类的构造函数中就可以通过类型提示进行依赖注入。

注册 Policy 类

Policy 类创建之后，需要注册到容器。Laravel 自带的 AuthServiceProvider 包含了一个 policies 属性来映射 Eloquent 模型及与之对应的 Policy 类。注册 Policy 将会告知 Laravel 在授权给定模型动作时使用哪一个策略类：

<?php
    
namespace App\Providers;
    
use App\Models\Post;
use App\Policies\PostPolicy;
use Illuminate\Support\Facades\Gate;
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;
    
class AuthServiceProvider extends ServiceProvider
{
    /**
     * 应用的策略映射.
     *
     * @var array
     * @translator xueyuanjun.com
     */
    protected $policies = [
        Post::class => PostPolicy::class,
    ];
    
    /**
     * 注册任意认证/授权服务.
     *
     * @return void
     */
    public function boot()
    {
        $this->registerPolicies();
    
        //
    }
}

策略类自动发现

除了手动注册模型与对应策略类映射关系之外，Laravel 还可以自动发现策略类，只要模型类和策略类遵循标准的 Laravel 命名约定（包含命名空间）。也就是说，策略类必须存放在 Policies 目录下，同时对应模型类必须存放在包含 Policies 的父目录下。举个例子，如果模型类位于 app/Models 目录下，则对应策略类必须位于 app/Policies 或者 app/Models/Policies 目录下。此外，策略名必须和模型名匹配然后加上一个 Policy 后缀。因此，User 模型对应的策略类是 UserPolicy 类。

如果你想要提供自定义的策略类自动发现逻辑，可以使用 Gate::guessPolicyNamesUsing 方法注册一个自定义的回调，通常，我们在 AuthServiceProvider 的 boot 方法中调用该方法：

use Illuminate\Support\Facades\Gate;
    
Gate::guessPolicyNamesUsing(function ($modelClass) {
    // 返回策略类名...
});

注：任何在 AuthServiceProvider 中显式映射的策略类优先级要高于那些潜在自动发现的策略类。

编写 Policy

Policy 方法

Policy 类被注册后，还要为每个授权动作添加方法，例如，我们为用户更新 Post 实例这一动作在 PostPolicy 中定义一个 update 方法。

update 方法会接收一个 User 实例和一个 Post 实例作为参数，并且返回 true 或 false 以表明该用户是否有权限对给定 Post 进行更新。因此，在这个例子中，我们验证用户的 id 和文章对应的 user_id 是否匹配：

<?php
    
namespace App\Policies;
    
use App\Models\Post;
use App\Models\User;
    
class PostPolicy
{
    /**
     * 判断给定文章是否可以被用户更新.
     *
     * @param  User  $user
     * @param  Post  $post
     * @return bool
     * @translator xueyuanjun.com
     */
    public function update(User $user, Post $post)
    {
        return $user->id === $post->user_id;
    }
}

你可以继续在 Policy 类中为授权的权限定义更多需要的方法，例如，你可以定义 view 或者 delete 等方法来授权多个 Post 动作，方法名不限。

注：如果你在使用 Artisan 命令生成策略类的时候使用了 --model 选项，那么策略类中就会包含了 view、create、update、delete、restore 和 forceDelete 授权动作方法。

Policy 响应

到目前为止，我们只检查了返回简单布尔值的 Policy，和 Gate 一样，有时候你可能也希望可以返回包含错误信息的、更加具体的响应，要实现这个功能，同样可以从 Policy 方法中返回一个 Illuminate\Auth\Access\Response：

use Illuminate\Auth\Access\Response;

use App\Models\User;
use App\Models\Post;
    
/**
 * Determine if the given post can be updated by the user.
 *
 * @param  User  $user
 * @param  Post  $post
 * @return bool
 */
public function update(User $user, Post $post)
{
    return $user->id === $post->user_id
                ? Response::allow()
                : Response::deny('You do not own this post.');
}

从 Policy 中返回授权响应时，Gate::allows 方法仍然返回的是简单的布尔值，只不过你可以使用 Gate::inspect 方法获取从 Gate 中返回的授权响应：

$response = Gate::inspect('update', $post);
    
if ($response->allowed()) {
    // The action is authorized...
} else {
    echo $response->message();
}

当然，使用 Gate::authorize 方法在授权失败抛出 AuthorizationException 异常时，授权响应提供的错误信息会被自动转化为 HTTP 响应：

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

// The action is authorized...

不带模型的方法

有些策略方法只接收当前认证的用户，并不接收授权的模型实例作为参数，这种用法在授权 create 动作的时候很常见。例如，创建一篇博客的时候，你可能想要检查检查当前用户是否有权创建新博客。

当定义不接收模型实例的策略方法时，例如 create 方法，可以这么做：

/**
 * 判断当前用户是否可以创建文章.
 *
 * @param  \App\Models\User  $user
 * @return bool
 */
public function create(User $user)
{
    //
}

访客用户

默认情况下，如果传入的 HTTP 请求由访客用户（未登录）发起，所有 Gate 和 Policy 检查都会返回 false，不过，你可以通过声明认证用户参数「可选」或者默认值为 null 来允许访客用户请求通过授权检查：

<?php
    
namespace App\Policies;
    
use App\Models\Post;
use App\Models\User;
    
class PostPolicy
{
    /**
     * Determine if the given post can be updated by the user.
     *
     * @param  User  $user
     * @param  Post  $post
     * @return bool
     */
    public function update(?User $user, Post $post)
    {
        return $user->id === $post->user_id;
    }
}

策略过滤器

对特定用户，你可能想要在一个策略方法中对其授权所有权限，比如后台管理员。要实现这个功能，需要在 Policy 类中定义一个 before 方法，before 方法会在 Policy 类的所有其他方法执行前执行，从而确保在其他策略方法调用前执行其中的逻辑：

public function before($user, $ability)
{
    if ($user->isSuperAdmin()) {
        return true;
    }
}

如果你想要禁止所有授权，可以在 before 方法中返回 false。如果返回 null，该授权会落入策略方法。

注：如果 Policy 类没有包含与待检查权限名称相匹配的授权方法时，该 Policy 类的 before 方法将不会被调用。

使用 Policy 授权动作

通过 User 模型

Laravel 自带的 User 模型提供了两个方法用于授权动作：can 和 cant。can 方法接收你想要授权的动作和对应的模型作为参数。例如，下面的例子我们判断用户是否被授权更新给定的 Post 模型：

if ($user->can('update', $post)) {
    //
}

如果给定模型对应的策略已经注册，则 can 方法会自动调用相应的策略并返回布尔结果。如果给定模型没有任何策略被注册，can 方法将会尝试调用与动作名称相匹配的 Gate 闭包。

不依赖模型的动作

有些动作比如 create 并不需要依赖给定模型实例，在这些场景中，可以传递一个类名到 can 方法，这个类名会在进行授权的时候用于判断使用哪一个策略：

use App\Models\Post;

if ($user->can('create', Post::class)) {
    // Executes the "create" method on the relevant policy...
}

通过中间件

Laravel 提供了一个可以在请求到达路由或控制器之前进行授权的中间件 —— Illuminate\Auth\Middleware\Authorize ，默认情况下，这个中间件在 App\Http\Kernel 类中被分配了一个 can 别名，下面我们来探究如何使用 can 中间件授权用户更新博客文章动作：

use App\Models\Post;

Route::put('/post/{post}', function (Post $post) {
    // The current user may update the post...
})->middleware('can:update,post');

在这个例子中，我们传递了两个参数给 can 中间件，第一个是我们想要授权的动作名称，第二个是我们想要传递给策略方法的路由参数。在这个例子中，由于我们使用了隐式模型绑定， Post 模型将会被传递给策略方法，如果没有对用户进行给定动作的授权，中间件将会生成并返回一个状态码为 403 的 HTTP 响应。

不依赖模型的动作

同样，对那些不需要传入模型实例的动作如 create，需要传递类名到中间件，类名将会在授权动作的时候用于判断使用哪个策略：

Route::post('/post', function () {
    // The current user may create posts...
})->middleware('can:create,App\Models\Post');

通过控制器辅助函数

除了提供给 User 模型的辅助函数，Laravel 还为继承自 App\Http\Controllers\Controller 基类的所有控制器提供了 authorize 方法，和 can 方法类似，该方法接收你想要授权的动作名称以及相应模型实例作为参数，如果动作没有被授权， authorize 方法将会抛出 Illuminate\Auth\Access\AuthorizationException ，Laravel 默认异常处理器将会将其转化为状态码为 403 的 HTTP 响应：

<?php
    
namespace App\Http\Controllers;
    
use App\Models\Post;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
    
class PostController extends Controller
{
    /**
     * 更新给定博客文章.
     *
     * @param  Request  $request
     * @param  Post  $post
     * @return Response
     * @translator laravelacademy.org
     */
    public function update(Request $request, Post $post)
    {
        $this->authorize('update', $post);
    
        // The current user can update the blog post...
    }
}

不依赖模型的动作

和之前讨论的一样，类似 create 这样的动作不需要传入模型实例参数，在这些场景中，可以传递类名给 authorize 方法，该类名将会在授权动作时判断使用哪个策略：

/**
 * 创建一篇新的博客文章.
 *
 * @param  Request  $request
 * @return Response
 */
public function create(Request $request)
{
    $this->authorize('create', Post::class);
    
    // The current user can create blog posts...
}

授权资源控制器

如果你在使用资源控制器，可以利用控制器构造函数中的 authorizeResource 方法，该方法会添加相应的 can 中间件定义到资源控制器方法。

authorizeResource 方法接收模型类名作为第一个参数，以及包含模型 ID 的路由/请求参数名作为第二个参数。你需要确保资源控制器创建的时候使用了 --model 选项，这样才会在相应的方法签名中包含对应的类型提示：

<?php
    
namespace App\Http\Controllers;
    
use App\Models\Post;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
    
class PostController extends Controller
{
    public function __construct()
    {
        $this->authorizeResource(Post::class, 'post');
    }
}

下面的控制器方法会被映射到对应的 Policy 方法：

控制器方法	Policy 方法
index	viewAny
show	view
create	create
store	create
edit	update
update	update
destroy	delete

注：你可以使用带有 --model 选项的 make:policy 命令来快速生成给定模型类对应的策略类：php artisan make:policy PostPolicy --model=Post。

通过 Blade 模板

编写 Blade 模板的时候，你可能想要在用户被授权特定动作的情况下才显示对应的视图模板部分，例如，你可能想要在用户被授权更新权限的情况下才显示更新表单。在这种情况下，你可以使用 @can 和 @cannot 指令：

@can('update', $post)
    <!-- 当前用户可以更新文章 -->
@elsecan('create', App\Models\Post::class)
    <!-- 当前用户可以创建新文章 -->
@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)
    // The current user can update, view, or delete the post
@elsecanany(['create'], \App\Models\Post::class)
    // The current user can create a post
@endcanany

不依赖模型的动作

和其它授权方法一样，如果授权动作不需要传入模型实例的情况下可以传递类名给 @can 和 @cannot 指令：

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

提供附加上下文

当使用 Policy 授权动作时，可以传递一个数组作为授权方法和辅助函数的第二个参数，数组中的第一个元素会被用于判断调用哪个 Policy，其它元素会以参数形式传递给 Policy 方法，并且在做授权决定时作为附加的上下文信息。例如，下面这个 PostPolicy 方法定义包含了一个附加的 $category 参数：

/**
 * Determine if the given post can be updated by the user.
 *
 * @param  \App\Models\User  $user
 * @param  \App\Models\Post  $post
 * @param  int  $category
 * @return bool
 */
public function update(User $user, Post $post, int $category)
{
    return $user->id === $post->user_id && 
           $category > 3;
}

当试图判断某个认证用户是否可以更新给定文章时，可以这样调用这个 Policy 方法：

/**
 * Update the given blog post.
 *
 * @param  Request  $request
 * @param  \App\Models\Post  $post
 * @return Response
 * @throws \Illuminate\Auth\Access\AuthorizationException
 */
public function update(Request $request, Post $post)
{
    $this->authorize('update', [$post, $request->input('category')]);
    
    // The current user can update the blog post...
}

扩展阅读

点赞取消点赞

收藏取消收藏

赞赏

新版特性

升级指南

贡献指南

安装

配置

目录结构

入门套件

部署应用到生产环境

一次请求的生命周期

服务容器

服务提供者

门面

路由

中间件

CSRF 防护

控制器

请求

响应

视图

Blade 模板引擎

URL 生成

Session

验证

错误处理

日志

用户认证

用户授权

邮箱验证

加密

哈希

重置密码

Artisan 控制台

广播

缓存

集合

通过 Mix 编译前端资源

契约

事件

文件存储

辅助函数

HTTP 客户端

本地化

邮件

通知

扩展包开发

队列

任务调度

数据库入门

查询构建器

分页

迁移

数据填充

Redis

Eloquent 模型入门

关联关系

Eloquent 集合

访问器和修改器

API 资源类

序列化

测试入门

HTTP 测试

控制台测试

基于 Laravel Dusk 进行浏览器测试

数据库测试

模拟

基于 Laravel Cashier 提供订阅支付解决方案

基于 Laravel Envoy 提供远程部署解决方案

基于 Laravel Fortify 提供纯后端用户认证解决方案

基于 Laravel Horizon 提供队列系统解决方案

基于 Laravel Homestead 搭建虚拟化本地集成开发环境

基于 Laravel Passport 提供 OAuth2 认证解决方案

基于 Laravel Sail 搭建 Docker 本地集成开发环境

基于 Laravel Sanctum 提供 SPA 认证解决方案

基于 Laravel Scout 提供全文搜索解决方案

基于 Laravel Socialite 提供第三方登录解决方案

基于 Laravel Telescope 提供本地调试解决方案

基于 Laravel Valet 在 Mac 系统搭建轻量级本地集成开发环境

用户授权

简介

Gate