Laravel Socialite

• Введение
• Установка
• Обновление Socialite
• Настройка
• Аутентификация
  • Маршрутизация
  • Аутентификация и хранение
  • Области доступа
  • Области доступа Slack Bot
  • Необязательные параметры
• Получение данных пользователя

#Введение

Помимо стандартной аутентификации на основе форм, Laravel предоставляет простой и удобный способ аутентификации через OAuth-провайдеров с помощью Laravel Socialite. Socialite в настоящее время поддерживает аутентификацию через Facebook, Twitter, LinkedIn, Google, GitHub, GitLab, Bitbucket и Slack.

#Установка

Чтобы начать работу с Socialite, используйте менеджер пакетов Composer для добавления пакета в зависимости вашего проекта:

composer require laravel/socialite

#Обновление Socialite

При обновлении до новой мажорной версии Socialite важно внимательно ознакомиться с руководством по обновлению.

#Настройка

Перед использованием Socialite необходимо добавить учетные данные для OAuth-провайдеров, которые использует ваше приложение. Обычно эти данные можно получить, создав «приложение разработчика» в панели управления сервиса, с которым будет происходить аутентификация.

Эти учетные данные следует разместить в конфигурационном файле вашего приложения config/services.php и использовать ключи facebook, twitter (OAuth 1.0), twitter-oauth-2 (OAuth 2.0), linkedin-openid, google, github, gitlab, bitbucket или slack в зависимости от провайдеров, необходимых вашему приложению:

'github' => [
    'client_id' => env('GITHUB_CLIENT_ID'),
    'client_secret' => env('GITHUB_CLIENT_SECRET'),
    'redirect' => 'http://example.com/callback-url',
],

#Аутентификация

#Маршрутизация

Для аутентификации пользователей через OAuth-провайдера вам понадобятся два маршрута: один для перенаправления пользователя к провайдеру, и другой для получения обратного вызова от провайдера после аутентификации. Пример маршрутов ниже демонстрирует реализацию обоих:

use Laravel\Socialite\Facades\Socialite;

Route::get('/auth/redirect', function () {
    return Socialite::driver('github')->redirect();
});

Route::get('/auth/callback', function () {
    $user = Socialite::driver('github')->user();

    // $user->token
});

Метод redirect, предоставляемый фасадом Socialite, отвечает за перенаправление пользователя к OAuth-провайдеру, а метод user анализирует входящий запрос и получает информацию о пользователе от провайдера после того, как пользователь одобрил запрос на аутентификацию.

#Аутентификация и хранение

После получения пользователя от OAuth-провайдера вы можете проверить, существует ли пользователь в базе данных вашего приложения, и аутентифицировать пользователя. Если пользователь не существует, обычно создается новая запись в базе данных для представления этого пользователя:

use App\Models\User;
use Illuminate\Support\Facades\Auth;
use Laravel\Socialite\Facades\Socialite;

Route::get('/auth/callback', function () {
    $githubUser = Socialite::driver('github')->user();

    $user = User::updateOrCreate([
        'github_id' => $githubUser->id,
    ], [
        'name' => $githubUser->name,
        'email' => $githubUser->email,
        'github_token' => $githubUser->token,
        'github_refresh_token' => $githubUser->refreshToken,
    ]);

    Auth::login($user);

    return redirect('/dashboard');
});

#Области доступа

Перед перенаправлением пользователя вы можете использовать метод scopes, чтобы указать «области доступа», которые должны быть включены в запрос аутентификации. Этот метод объединит все ранее указанные области с новыми:

use Laravel\Socialite\Facades\Socialite;

return Socialite::driver('github')
    ->scopes(['read:user', 'public_repo'])
    ->redirect();

Вы можете полностью заменить все существующие области в запросе аутентификации с помощью метода setScopes:

return Socialite::driver('github')
    ->setScopes(['read:user', 'public_repo'])
    ->redirect();

#Области доступа Slack Bot

API Slack предоставляет различные типы токенов доступа, каждый со своим набором областей разрешений. Socialite совместим с двумя следующими типами токенов Slack:

По умолчанию драйвер slack генерирует токен типа user, и вызов метода user драйвера возвращает данные пользователя.

Токены бота полезны, если ваше приложение будет отправлять уведомления во внешние рабочие пространства Slack, принадлежащие пользователям вашего приложения. Чтобы сгенерировать токен бота, вызовите метод asBotUser перед перенаправлением пользователя на Slack для аутентификации:

return Socialite::driver('slack')
    ->asBotUser()
    ->setScopes(['chat:write', 'chat:write.public', 'chat:write.customize'])
    ->redirect();

Кроме того, необходимо вызвать метод asBotUser перед вызовом метода user после того, как Slack перенаправит пользователя обратно в ваше приложение после аутентификации:

$user = Socialite::driver('slack')->asBotUser()->user();

При генерации токена бота метод user по-прежнему возвращает экземпляр Laravel\Socialite\Two\User, однако будет заполнено только свойство token. Этот токен можно сохранить для отправки уведомлений в рабочие пространства Slack аутентифицированного пользователя.

#Необязательные параметры

Некоторые OAuth-провайдеры поддерживают дополнительные необязательные параметры в запросе перенаправления. Чтобы включить такие параметры, вызовите метод with с ассоциативным массивом:

use Laravel\Socialite\Facades\Socialite;

return Socialite::driver('google')
    ->with(['hd' => 'example.com'])
    ->redirect();

#Получение данных пользователя

После того как пользователь будет перенаправлен обратно на маршрут обратного вызова аутентификации вашего приложения, вы можете получить данные пользователя с помощью метода user Socialite. Объект пользователя, возвращаемый методом user, содержит различные свойства и методы, которые можно использовать для сохранения информации о пользователе в вашей базе данных.

Доступные свойства и методы могут отличаться в зависимости от того, поддерживает ли OAuth-провайдер OAuth 1.0 или OAuth 2.0:

use Laravel\Socialite\Facades\Socialite;

Route::get('/auth/callback', function () {
    $user = Socialite::driver('github')->user();

    // Провайдеры OAuth 2.0...
    $token = $user->token;
    $refreshToken = $user->refreshToken;
    $expiresIn = $user->expiresIn;

    // Провайдеры OAuth 1.0...
    $token = $user->token;
    $tokenSecret = $user->tokenSecret;

    // Все провайдеры...
    $user->getId();
    $user->getNickname();
    $user->getName();
    $user->getEmail();
    $user->getAvatar();
});

#Получение данных пользователя по токену (OAuth2)

Если у вас уже есть действительный токен доступа пользователя, вы можете получить его данные с помощью метода userFromToken Socialite:

use Laravel\Socialite\Facades\Socialite;

$user = Socialite::driver('github')->userFromToken($token);

#Получение данных пользователя по токену и секрету (OAuth1)

Если у вас уже есть действительный токен и секрет пользователя, вы можете получить его данные с помощью метода userFromTokenAndSecret Socialite:

use Laravel\Socialite\Facades\Socialite;

$user = Socialite::driver('twitter')->userFromTokenAndSecret($token, $secret);

#Аутентификация без состояния (stateless)

Метод stateless можно использовать для отключения проверки состояния сессии. Это полезно при добавлении социальной аутентификации в stateless API, которое не использует сессии на основе cookie:

use Laravel\Socialite\Facades\Socialite;

return Socialite::driver('google')->stateless()->user();