Laravel Socialite

• Introducción
• Instalación
• Actualización de Socialite
• Configuración
• Autenticación
  • Enrutamiento
  • Autenticación y almacenamiento
  • Ámbitos de acceso
  • Ámbitos de bot de Slack
  • Parámetros opcionales
• Recuperación de detalles del usuario

Introducción

Además de la autenticación típica basada en formularios, Laravel también proporciona una forma simple y conveniente de autenticarse con proveedores de OAuth utilizando Laravel Socialite. Socialite admite actualmente la autenticación a través de Facebook, Twitter, LinkedIn, Google, GitHub, GitLab, Bitbucket y Slack.

Nota Adaptadores para otras plataformas están disponibles a través del sitio web impulsado por la comunidad Socialite Providers.

Instalación

Para comenzar con Socialite, use el administrador de paquetes Composer para agregar el paquete a las dependencias de su proyecto:

composer require laravel/socialite

Actualización de Socialite

Al actualizar a una nueva versión principal de Socialite, es importante revisar cuidadosamente la guía de actualización.

Configuración

Antes de usar Socialite, deberá agregar credenciales para los proveedores de OAuth que utilice su aplicación. Normalmente, estas credenciales se pueden recuperar creando una "aplicación para desarrolladores" dentro del panel del servicio con el que autenticará.

Estas credenciales deben colocarse en el archivo de configuración config/services.php de su aplicación y deben usar la clave facebook, twitter (OAuth 1.0), twitter-oauth-2 (OAuth 2.0), linkedin-openid, google, github, gitlab, bitbucket o slack, según los proveedores que su aplicación requiera:

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

Nota Si la opción redirect contiene una ruta relativa, se resolverá automáticamente a una URL completamente cualificada.

Autenticación

Enrutamiento

Para autenticar usuarios mediante un proveedor de OAuth, necesitará dos rutas: una para redirigir al usuario al proveedor de OAuth y otra para recibir la devolución de llamada del proveedor después de la autenticación. Las rutas de ejemplo a continuación demuestran la implementación de ambas rutas:

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
});

El método redirect proporcionado por la fachada Socialite se encarga de redirigir al usuario al proveedor de OAuth, mientras que el método user examinará la solicitud entrante y recuperará la información del usuario desde el proveedor después de que hayan aprobado la solicitud de autenticación.

Autenticación y almacenamiento

Una vez que se ha recuperado al usuario del proveedor de OAuth, puede determinar si el usuario existe en la base de datos de su aplicación y autenticar al usuario. Si el usuario no existe en la base de datos de su aplicación, generalmente creará un nuevo registro en su base de datos para representar al usuario:

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

Nota Para obtener más información sobre la información del usuario disponible desde proveedores específicos de OAuth, consulte la documentación sobre cómo recuperar detalles del usuario.

Ámbitos de acceso

Antes de redirigir al usuario, puede usar el método scopes para especificar los "ámbitos" que deben incluirse en la solicitud de autenticación. Este método fusionará todos los ámbitos especificados previamente con los ámbitos que especifique:

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

Puede sobrescribir todos los ámbitos existentes en la solicitud de autenticación mediante el método setScopes:

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

Ámbitos de bot de Slack

La API de Slack proporciona diferentes tipos de tokens de acceso, cada uno con su propio conjunto de ámbitos de permisos. Socialite es compatible con ambos tipos de tokens de acceso de Slack siguientes:

De forma predeterminada, el controlador slack generará un token user e invocar el método user devolverá los detalles del usuario.

Los tokens de bot son principalmente útiles si su aplicación enviará notificaciones a espacios de trabajo de Slack externos que son propiedad de los usuarios de su aplicación. Para generar un token de bot, invoque el método asBotUser antes de redirigir al usuario a Slack para la autenticación:

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

Además, debe invocar el método asBotUser antes de invocar el método user después de que Slack redirige al usuario de vuelta a su aplicación después de la autenticación:

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

Al generar un token de bot, el método user seguirá devolviendo una instancia de Laravel\Socialite\Two\User; sin embargo, solo la propiedad token estará poblada. Este token se puede almacenar para enviar notificaciones a los espacios de trabajo de Slack autenticados.

Parámetros opcionales

Varios proveedores de OAuth admiten otros parámetros opcionales en la solicitud de redireccionamiento. Para incluir cualquier parámetro opcional en la solicitud, llame al método with con un array asociativo:

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

Advertencia Al usar el método with, tenga cuidado de no pasar palabras clave reservadas como state o response_type.

Recuperación de detalles del usuario

Después de que el usuario sea redirigido de vuelta a la ruta de devolución de llamada de autenticación de su aplicación, puede recuperar los detalles del usuario usando el método user de Socialite. El objeto de usuario devuelto por el método user proporciona una variedad de propiedades y métodos que puede usar para almacenar información sobre el usuario en su propia base de datos.

Propiedades y métodos diferentes pueden estar disponibles en este objeto según si el proveedor de OAuth con el que está autenticando admite OAuth 1.0 o OAuth 2.0:

use Laravel\Socialite\Facades\Socialite;
 
Route::get('/auth/callback', function () {
    $user = Socialite::driver('github')->user();
 
    // Proveedores de OAuth 2.0...
    $token = $user->token;
    $refreshToken = $user->refreshToken;
    $expiresIn = $user->expiresIn;
 
    // Proveedores de OAuth 1.0...
    $token = $user->token;
    $tokenSecret = $user->tokenSecret;
 
    // Todos los proveedores...
    $user->getId();
    $user->getNickname();
    $user->getName();
    $user->getEmail();
    $user->getAvatar();
});

Recuperación de detalles del usuario a partir de un token (OAuth2)

Si ya tiene un token de acceso válido para un usuario, puede recuperar los detalles del usuario utilizando el método userFromToken de Socialite:

use Laravel\Socialite\Facades\Socialite;
 
$user = Socialite::driver('github')->userFromToken($token);

Recuperación de detalles del usuario a partir de un token y un secreto (OAuth1)

Si ya tiene un token y un secreto válidos para un usuario, puede recuperar los detalles del usuario utilizando el método userFromTokenAndSecret de Socialite:

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

Autenticación sin estado

El método stateless se puede usar para deshabilitar la verificación del estado de la sesión. Esto es útil al agregar la autenticación social a una API sin estado que no utiliza sesiones basadas en cookies:

use Laravel\Socialite\Facades\Socialite;
 
return Socialite::driver('google')->stateless()->user();

Advertencia La autenticación sin estado no está disponible para el controlador de Twitter OAuth 1.0.