Авторизация

Есть два основных способа авторизации действий: шлюзы и политики.

Шлюзы и политики похожи на маршруты и контроллеры. Шлюзы обеспечивают простой подход к авторизации на основе замыканий, а политики, подобно контроллерам, группируют свою логику вокруг конкретной модели или ресурса. Сначала мы рассмотрим шлюзы, а затем политики.

При создании приложения вам не надо выбирать только что-то одно: либо шлюзы, либо политики. В большинстве приложений будет использоваться смесь из шлюзов и политик, и это очень здорово! Шлюзы больше подходят для действий, не связанных с моделями и ресурсами, такими как просмотр панели управления администратора. А политики надо использовать для авторизации действий для конкретных моделей или ресурсов.

Шлюзы

Написание шлюзов

Шлюзы — это замыкания, определяющие, авторизован ли пользователь на выполнение данного действия. Обычно они определяются в классе App\Providers\AuthServiceProvider с помощью фасада Gate. Шлюзы всегда получают объект пользователя первым аргументом и могут получать дополнительные аргументы, такие как соответствующая Eloquent-модель:

/**
 * Регистрация всех сервисов аутентификации / авторизации.
 *
 * @return void
 */
public function boot()
{
  $this->registerPolicies();

  Gate::define('update-post', function ($user, $post) {
    return $user->id == $post->user_id;
  });
}

Авторизация действий

Для авторизации действий с помощью шлюзов используйте методы PHPallows() и PHPdenies(). Помните, вам не надо передавать текущего аутентифицированного пользователя в эти методы. Laravel автоматически позаботится о передаче пользователя в замыкание шлюза:

if (Gate::allows('update-post', $post)) {
  // Текущий пользователь может редактировать статью...
}

if (Gate::denies('update-post', $post)) {
  // Текущий пользователь не может редактировать статью...
}

Для определения, авторизован ли конкретный пользователь на выполнение действия, используйте метод PHPforUser() фасада Gate:

if (Gate::forUser($user)->allows('update-post', $post)) {
  // Пользователь может редактировать статью...
}

if (Gate::forUser($user)->denies('update-post', $post)) {
  // Пользователь не может редактировать статью...
}

Создание политик

Генерирование политик

Политики — это классы, организующие логику авторизации вокруг конкретной модели или ресурса. Например, если ваше приложение — блог, у вас может быть модель Post и соответствующая PostPolicy для авторизации действий пользователя, таких как создание или редактирование статьи.

Вы можете сгенерировать политику с помощью artisan-команды shmake:policy. Сгенерированная политика будет помещена в каталог app/Policies. Если такого каталога нет в вашем приложении, Laravel создаст его:

shphp artisan make:policy PostPolicy

Команда shmake:policy сгенерирует пустой класс политики. Если вы хотите создать класс уже с базовыми CRUD методами политики, укажите sh--model при выполнении команды:

shphp artisan make:policy PostPolicy --model=Post

Все политики извлекаются через сервис-контейнер Laravel, позволяя вам указывать типы любых необходимых зависимостей в конструкторе политики, и они будут внедрены автоматически.

Регистрация политик

Когда политика создана, её надо зарегистрировать. В Laravel-приложении по умолчанию есть AuthServiceProvider, имеющий свойство policies, которое связывает ваши Eloquent-модели с соответствующими им политиками. Регистрация политики позволит Laravel использовать необходимую политику для авторизации действия над данной моделью:

<?php

namespace App\Providers;

use App\Post;
use App\Policies\PostPolicy;
use Illuminate\Support\Facades\Gate;
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;

class AuthServiceProvider extends ServiceProvider
{
  /**
   * Привязка политик для приложения.
   *
   * @var array
   */
  protected $policies = [
    Post::class => PostPolicy::class,
  ];

  /**
   * Регистрация всех сервисов аутентификации / авторизации приложения.
   *
   * @return void
   */
  public function boot()
  {
    $this->registerPolicies();

    //
  }
}

Написание политик

Методы политик

После регистрации политики вы можете добавить методы для каждого действия, которое она авторизует. Например, давайте определим метод PHPupdate() в нашей PostPolicy, который будет определять, может ли данный User редактировать данный объект Post.

Метод PHPupdate() получит в качестве аргументов методы PHPUser() и PHPPost() и должен вернуть PHPtrue или PHPfalse, сообщая, авторизован ли пользователь для редактирования данной статьи. В этом примере давайте проверим, совпадает ли id пользователя с user_id статьи:

<?php

namespace App\Policies;

use App\User;
use App\Post;

class PostPolicy
{
  /**
   * Определение, может ли данная статья редактироваться пользователем.
   *
   * @param  \App\User  $user
   * @param  \App\Post  $post
   * @return bool
   */
  public function update(User $user, Post $post)
  {
    return $user->id === $post->user_id;
  }
}

При необходимости вы можете определить дополнительные методы политики для различных действий, которые она авторизует. Например, вы можете определить метод PHPview() или PHPdelete() для авторизации различных действий со статьёй, и помните, что вы можете называть методы политики как угодно.

Если вы использовали параметр sh--model при генерировании вашей политики через консоль Artisan, она уже будет содержать методы для действий view, create, update и delete.

Методы без моделей

Некоторые методы политик принимают только текущего аутентифицированного пользователя без экземпляра модели, для которой они авторизуют. Такие ситуации наиболее распространены при авторизации действий create. Например, если вы создаёте блог, вы можете проверять, авторизован ли пользователь создавать статьи в принципе.

При определении методов политик, которые не будут получать экземпляр модели, таких как метод PHPcreate(), они не будут получать экземпляр модели. Вместо этого вам надо определить метод, ожидающий только аутентифицированного пользователя:

/**
 * Определение, может ли данный пользователь создавать статьи.
 *
 * @param  \App\User  $user
 * @return bool
 */
public function create(User $user)
{
  //
}

Фильтры политик

Для некоторых пользователей вы можете авторизовывать все действия определённой политики. Для этого определите в политике метод PHPbefore(). Этот метод будет выполнятся перед всеми остальными методами политики, давая вам возможность авторизовать действие до того, как будет вызван соответствующий метод. Эта возможность наиболее часто используется для авторизации администраторов приложения на выполнение каких-либо действий:

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

Если вы хотите запретить всю авторизацию для пользователя, вам надо вернуть PHPfalse из метода PHPbefore(). Если вернётся PHPnull, авторизация перейдёт к методу политики.

Авторизация действий с помощью политик

Через модель User

Модель User, встроенная в Laravel, содержит два полезных метода для авторизации действий: PHPcan() и PHPcant(). Метод PHPcan() получает действие для авторизации и соответствующую модель. Например, давайте определим, авторизован ли пользователь на редактирование данной модели Post:

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

Если политика зарегистрирована для данной модели, метод PHPcan() автоматически вызовет соответствующую политику и вернет логический результат. Если для модели не зарегистрировано ни одной политики, метод PHPcan() попытается вызвать шлюз на основе замыкания, совпадающий с именем данного действия.

Действия, не требующие моделей

Помните, что некоторые действия, такие как create, не требуют экземпляр модели. В таких ситуациях вы можете передать имя класса в метод PHPcan(). Имя класса будет использовано для определения того, какая политика авторизует действие:

use App\Post;

if ($user->can('create', Post::class)) {
  // Выполняется метод "create" соответствующей политики...
}

Через посредника

Laravel содержит посредника, который может авторизовать действия даже до того, как входящий запрос достигнет ваших маршрутов или контроллеров. По умолчанию посреднику Illuminate\Auth\Middleware\Authorize назначен ключ can в вашем классе App\Http\Kernel. Давайте рассмотрим пример использования посредника can для авторизации пользователя на редактирование статьи блога:

use App\Post;

Route::put('/post/{post}', function (Post $post) {
  // Текущий пользователь может редактировать статью...
})->middleware('can:update,post');

В этом примере мы передаём посреднику can два аргумента. Первый — имя действия для авторизации, а второе — параметр маршрута для передачи в метод политики. В данном случае, поскольку мы используем неявную привязку модели, модель Post будет передана в метод политики. Если пользователь не авторизован на выполнение данного действия, посредник сгенерирует HTTP-отклик с кодом состояния 403.

Действия, не требующие моделей

И снова, некоторые действия, такие как create, не требуют экземпляр модели. В таких ситуациях вы можете передать имя класса в посредник. Имя класса будет использовано для определения того, какая политика авторизует действие:

Route::post('/post', function () {
  // Текущий пользователь может создавать статьи...
})->middleware('can:create,App\Post');

Через вспомогательные методы контроллера

В дополнение к полезным методам модели User Laravel предоставляет полезный метод PHPauthorize() для всех ваших контроллеров, наследующих базовый класс App\Http\Controllers\Controller. Подобно методу PHPcan(), этот метод принимает имя действия для авторизации и соответствующую модель. Если действие не авторизовано, метод PHPauthorize() выбросит исключение Illuminate\Auth\Access\AuthorizationException, которое будет конвертировано стандартным обработчиком исключений Laravel в HTTP-отклик с кодом состояния 403:

<?php

namespace App\Http\Controllers;

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

class PostController extends Controller
{
  /**
   * Редактировать данную статью.
   *
   * @param  Request  $request
   * @param  Post  $post
   * @return Response
   */
  public function update(Request $request, Post $post)
  {
    $this->authorize('update', $post);

    // Текущий пользователь может редактировать статью...
  }
}

Действия, не требующие моделей

Как было сказано ранее, некоторые действия, такие как create, не требуют экземпляр модели. В таких ситуациях вы можете передать имя класса в метод PHPauthorize(). Имя класса будет использовано для определения того, какая политика авторизует действие:

/**
 * Create a new blog post.
 *
 * @param  Request  $request
 * @return Response
 */
public function create(Request $request)
{
  $this->authorize('create', Post::class);

  // The current user can create blog posts...
}

Через шаблоны Blade

При написании шаблонов Blade вы можете выводить часть страницы, только если пользователь авторизован на выполнение данного действия. Например, можно показывать форму редактирования статьи, только если пользователь может редактировать статью. В данной ситуации вы можете использовать семейство директив PHP@can и PHP@cannot:

@can('update', $post)
  <!-- Текущий Пользователь Может Редактировать Статью -->
@elsecan('create', $post)
  <!-- Текущий Пользователь Может Создать Новую Статью -->
@endcan

@cannot('update', $post)
  <!-- Текущий Пользователь Не Может Редактировать Статью -->
@elsecannot('create', $post)
  <!-- Текущий Пользователь Не Может Создать Новую Статью -->
@endcannot

Эти директивы — удобный короткий вариант для написания операторов PHP@if и PHP@unless. Операторы PHP@can и PHP@cannot из приведённого примера можно перевести соответственно в следующие операторы:

@if (Auth::user()->can('update', $post))
  <!-- Текущий Пользователь Может Редактировать Статью -->
@endif

@unless (Auth::user()->can('update', $post))
  <!-- Текущий Пользователь Не Может Редактировать Статью -->
@endunless

Действия, не требующие моделей

Как и большинство других методов авторизации вы можете передать в директивы PHP@can и PHP@cannot имя класса, если действие не требует экземпляра модели:

@can('create', Post::class)
  <!-- Текущий Пользователь Может Создавать Статьи -->
@endcan

@cannot('create', Post::class)
  <!-- Текущий Пользователь Не Может Создавать Статьи -->
@endcannot

Определение прав

Простейший способ определить наличие у пользователя прав на выполнение конкретного действия — задать «право» при помощи класса Illuminate\Auth\Access\Gate. Поставляемый с Laravel AuthServiceProvider служит удобным местом для определения всех прав для вашего приложения. Например, давайте определим право update-post, которое получает текущего User и модель Post. Внутри нашего права мы будем проверять совпадает ли id пользователя с user_id статьи:

<?php

namespace App\Providers;

use Illuminate\Contracts\Auth\Access\Gate as GateContract;
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;

class AuthServiceProvider extends ServiceProvider
{
  /**
   * Регистрация любых сервисов аутентификации/авторизации для приложения.
   *
   * @param  \Illuminate\Contracts\Auth\Access\Gate  $gate
   * @return void
   */
  public function boot(GateContract $gate)
  {
    $this->registerPolicies($gate);

    $gate->define('update-post', function ($user, $post) {
      return $user->id == $post->user_id;
    });
  }
}

До версии 5.2 в этом примере для сравнения использовался оператор тождественного равенства PHPreturn $user->id === $post->user_id; — прим. пер.

Заметьте, мы не проверили данного $user на NULL. Gate автоматически вернёт значение false для всех прав, когда нет аутентифицированного пользователя, или конкретный пользователь не был указан с помощью метода PHPforUser().

Права на основе класса

В добавление к регистрации замыканий Closures в качестве обратных вызовов авторизации, вы можете регистрировать методы класса, передавая строку с именем класса и метода. Когда понадобится, класс будет извлечён при помощи сервис-контейнера:

$gate->define('update-post', 'Class@method');

Перехват проверок авторизации

Иногда необходимо предоставить полные права конкретному пользователю. Для таких случаев используйте метод PHPbefore(), чтобы задать обратный вызов, который будет выполняться до всех остальных проверок авторизации:

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

Если обратный вызов PHPbefore() возвращает не пустой результат, то этот результат будет считаться результатом проверки.

Вы можете использовать метод PHPafter() для задания обратного вызова, который будет выполняться после каждой проверки авторизации. Но из этого метода нельзя изменить результат проверки авторизации:

$gate->after(function ($user, $ability, $result, $arguments) {
  //
});

Проверка прав

С помощью фасада Gate

Когда право задано, мы можем «проверить» его разными способами. Во-первых, мы можем использовать методы фасада Gate — PHPcheck(), PHPallows() и PHPdenies(). Все они получают имя права и аргументы, которые необходимо передать в обратный вызов права. Вам не надо передавать текущего пользователя в эти методы, поскольку Gate автоматически подставит его перед аргументами, передаваемыми в обратный вызов. Поэтому при проверке права update-post, которое мы определили ранее, нам надо передать только экземпляр Post в метод PHPdenies():

<?php

namespace App\Http\Controllers;

use Gate;
use App\User;
use App\Post;
use App\Http\Controllers\Controller;

class PostController extends Controller
{
  /**
   * Обновление данной статьи.
   *
   * @param  int  $id
   * @return Response
   */
  public function update($id)
  {
    $post = Post::findOrFail($id);

    if (Gate::denies('update-post', $post)) {
      abort(403);
    }

    // Обновление статьи...
  }
}

Метод PHPallows() обратен методу PHPdenies() и возвращает true, если действие авторизовано. Метод PHPcheck() — псевдоним метода PHPallows().

Проверка прав конкретного пользователя

Если вы хотите использовать фасад Gate для проверки наличия определённого права у пользователя, отличного от текущего аутентифицированного пользователя, то можете использовать метод PHPforUser():

if (Gate::forUser($user)->allows('update-post', $post)) {
  //
}

Передача нескольких аргументов

Конечно, обратные вызовы прав могут принимать несколько аргументов:

Gate::define('delete-comment', function ($user, $post, $comment) {
  //
});

Если вашему праву необходимо несколько аргументов, просто передайте массив аргументов в методы Gate:

if (Gate::allows('delete-comment', [$post, $comment])) {
    //
}

С помощью модели User

Альтернативный способ проверки прав — с помощью экземпляра модели User. По умолчанию в Laravel модель App\User использует типаж Authorizable, который предоставляет два метода: PHPcan() и PHPcannot(). Эти методы могут быть использованы так же, как методы PHPallows() и PHPdenies() фасада Gate. Тогда, используя наш предыдущий пример, мы можем изменить код вот так:

<?php

namespace App\Http\Controllers;

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

class PostController extends Controller
{
  /**
   * Обновление данной статьи.
   *
   * @param  \Illuminate\Http\Request  $request
   * @param  int  $id
   * @return Response
   */
  public function update(Request $request, $id)
  {
    $post = Post::findOrFail($id);

    if ($request->user()->cannot('update-post', $post)) {
      abort(403);
    }

    // Обновление статьи...
  }
}

Метод PHPcan() обратен методу PHPcannot():

if ($request->user()->can('update-post', $post)) {
  // Обновление статьи...
}

В шаблонах Blade

Для удобства Laravel предоставляет Blade-директиву @can для быстрой проверки наличия данного права у текущего аутентифицированного пользователя. Например:

<a href="/post/{{ $post->id }}">View Post</a>

@can('update-post', $post)
    <a href="/post/{{ $post->id }}/edit">Edit Post</a>
@endcan

Также вы можете комбинировать директиву @can с директивой @else:

@can('update-post', $post)
    <!-- The Current User Can Update The Post -->
@else
    <!-- The Current User Can't Update The Post -->
@endcan

В запросах форм

Также вы можете использовать определёные в Gate права в методе PHPauthorize() запроса формы. Например:

/**
 * Определение авторизации пользователя для выполнения этого запроса.
 *
 * @return bool
 */
public function authorize()
{
  $postId = $this->route('post');

  return Gate::allows('update', Post::findOrFail($postId));
}

Политики

Создание политик

В больших приложениях определение всей логики авторизации в AuthServiceProvider может стать громоздким, поэтому Laravel позволяет вам разделять вашу логику авторизации на классы «Политики». Политики — простые PHP-классы, которые группируют логику авторизации на основе авторизуемых ресурсов.

Сначала давайте сгенерируем политику для управления авторизацией для нашей модели Post. Вы можете сгенерировать политику используя artisan-команду shmake:policy. Сгенерированная политика будет помещена в папку app/Policies:

shphp artisan make:policy PostPolicy

Регистрация политик

Когда мы создали политику, нам надо зарегистрировать её классом Gate. AuthServiceProvider содержит свойство policies, которое сопоставляет различные сущности с управляющими ими политиками. Поэтому мы укажем, что политика модели Post — это класс PostPolicy:

<?php

namespace App\Providers;

use App\Post;
use App\Policies\PostPolicy;
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;

class AuthServiceProvider extends ServiceProvider
{
  /**
   * Сопоставление политик для приложения.
   *
   * @var array
   */
  protected $policies = [
    Post::class => PostPolicy::class,
  ];

  /**
   * Регистрация любых сервисов аутентификации/авторизации для приложения.
   *
   * @param  \Illuminate\Contracts\Auth\Access\Gate  $gate
   * @return void
   */
  public function boot(GateContract $gate)
  {
    $this->registerPolicies($gate);
  }
}

Написание политик

Когда политика сгенерирована и зарегистрирована, мы можем добавлять методы для каждого права, за которое она отвечает. Например, определим метод PHPupdate() в нашем PostPolicy, который будет проверять может ли данный User «обновлять» Post:

<?php

namespace App\Policies;

use App\User;
use App\Post;

class PostPolicy
{
  /**
   * Проверка может ли данный пост быть обновлён пользователем.
   *
   * @param  \App\User  $user
   * @param  \App\Post  $post
   * @return bool
   */
  public function update(User $user, Post $post)
  {
    return $user->id === $post->user_id;
  }
}

При необходимости вы можете продолжить определять дополнительные методы для политики для различных прав, за которые она отвечает. Например, вы можете определить методы PHPshow(), PHPdestroy() и PHPaddComment() для авторизации различных действий с Post.

Все политики подключаются через сервис-контейнер Laravel, а значит, вы можете указать типы любых необходимых зависимостей в конструкторе политики, и они будут внедрены автоматически.

Перехват всех проверок

Если вам необходимо предоставить конкретному пользователю все права политики, определите в этой политике метод PHPbefore(). Этот метод будет выполняться до всех остальных проверок авторизации этой политики:

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

Если метод PHPbefore() возвращает не пустой результат, то этот результат будет считаться результатом проверки.

Проверка политик

Методы политик вызываются точно так же, как обратные вызовы авторизации на основе замыканий Closure. Вы можете использовать фасад Gate, модель User, Blade-директиву @can, или вспомогательную функцию PHPpolicy().

С помощью фасада Gate

Gate автоматически определяет какую политику использовать, исходя из классов аргументов, передаваемых в его методы. Если мы передаём экземпляр Post в метод denies, то Gate будет использовать соответствующий PostPolicy для авторизации действий:

<?php

namespace App\Http\Controllers;

use Gate;
use App\User;
use App\Post;
use App\Http\Controllers\Controller;

class PostController extends Controller
{
  /**
   * Обновление данной статьи.
   *
   * @param  int  $id
   * @return Response
   */
  public function update($id)
  {
    $post = Post::findOrFail($id);

    if (Gate::denies('update', $post)) {
      abort(403);
    }

    // Обновление статьи...
  }
}

С помощью модели User

Методы PHPcan() и PHPcannot() модели User будут так же автоматически использовать политики, когда они доступны для данных аргументов. Эти методы предоставляют удобный способ для авторизации действий для любого экземпляра User, получаемого вашим приложением:

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

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

В шаблонах Blade

Точно так же Blade-директива @can будет использовать политики, когда они доступны для данных аргументов:

@can('update', $post)
  <!-- Текущий Пользователь Может Обновлять Статью -->
@endcan

С помощью вспомогательной функции Policy

Глобальная вспомогательная функция PHPpolicy() может использоваться для получения класса Policy для данного экземпляра класса. Например, мы можем передать экземпляр Post в функцию PHPpolicy() для получения экземпляра соответствующего класса PostPolicy:

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

Авторизация контроллера

Базовый класс Laravel App\Http\Controllers\Controller по умолчанию использует типаж AuthorizesRequests. Этот типаж предоставляет метод PHPauthorize(), который может быть использован для быстрой авторизации данного действия или выброса AuthorizationException (HttpException для версии 5.1 и ранее — прим. пер.), если действие не авторизовано.

Метод PHPauthorize() разделяет ту же подпись, что и различные другие методы авторизации, такие как PHPGate::allows и PHP$user->can(). Давайте используем метод PHPauthorize() для быстрой авторизации запроса на обновление Post:

<?php

namespace App\Http\Controllers;

use App\Post;
use App\Http\Controllers\Controller;

class PostController extends Controller
{
  /**
   * Обновление данной статьи.
   *
   * @param  int  $id
   * @return Response
   */
  public function update($id)
  {
    $post = Post::findOrFail($id);

    $this->authorize('update', $post);

    // Обновление статьи...
  }
}

Если действие авторизовано, контроллер продолжит нормально выполняться; но если метод PHPauthorize() определит, что действие не авторизовано, будет автоматически выброшено AuthorizationException (HttpException для версии 5.1 и ранее — прим. пер.), которое сгенерирует HTTP-ответ с кодом состояния 403 Not Authorized. Как видите, метод PHPauthorize() — удобный и быстрый способ авторизации действия или выброса исключения одной строчкой кода.

Типаж AuthorizesRequests также предоставляет метод PHPauthorizeForUser() для авторизации действия для пользователя, который не является текущим аутентифицированным пользователем:

$this->authorizeForUser($user, 'update', $post);

Автоматическое определение методов политики

Часто методы политики будут соответствовать методам контроллера. Например, в приведённом выше методе PHPupdate() у метода контроллера и метода политики одинаковое название PHPupdate().

Поэтому Laravel позволяет просто передать аргументы экземпляра в метод PHPauthorize(), и авторизуемое действие будет автоматически определено на основе имени вызываемой функции. В этом примере, поскольку PHPauthorize() вызывается из метода контроллера PHPupdate(), то и в политике будет вызван метод PHPupdate():

/**
 * Обновление данной статьи.
 *
 * @param  int  $id
 * @return Response
 */
public function update($id)
{
    $post = Post::findOrFail($id);

    $this->authorize($post);

    // Обновление статьи...
}