Laravel Socialite

• Introducción
• Instalación
• Actualización de Socialite
• Configuración
• Autenticación
  • Rutas
  • Autenticación y almacenamiento
  • Scopes de acceso
  • Scopes para bots de Slack
  • Parámetros opcionales
• Recuperar detalles del usuario

#Introducción

Además de la autenticación típica basada en formularios, Laravel también ofrece una forma sencilla y conveniente de autenticarse con proveedores OAuth usando Laravel Socialite. Socialite actualmente soporta autenticación vía Facebook, Twitter, LinkedIn, Google, GitHub, GitLab, Bitbucket y Slack.

#Instalación

Para comenzar con Socialite, use el gestor 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 mayor de Socialite, es importante que revise cuidadosamente la guía de actualización.

#Configuración

Antes de usar Socialite, deberá agregar las credenciales para los proveedores OAuth que su aplicación utilice. Normalmente, estas credenciales se obtienen creando una "aplicación de desarrollador" dentro del panel de control del servicio con el que se 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',
],

#Autenticación

#Rutas

Para autenticar usuarios usando un proveedor OAuth, necesitará dos rutas: una para redirigir al usuario al proveedor OAuth, y otra para recibir el callback del proveedor después de la autenticación. Las rutas de ejemplo a continuación muestran 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 el facade Socialite se encarga de redirigir al usuario al proveedor OAuth, mientras que el método user examina la solicitud entrante y recupera la información del usuario desde el proveedor después de que haya aprobado la solicitud de autenticación.

#Autenticación y almacenamiento

Una vez que se ha recuperado el usuario del proveedor 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, normalmente creará un nuevo registro para representarlo:

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 de acceso

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

use Laravel\Socialite\Facades\Socialite;

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

Puede sobrescribir todos los scopes existentes en la solicitud de autenticación usando el método setScopes:

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

#Scopes para bots de Slack

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

Por defecto, el driver slack generará un token de tipo user y al invocar el método user del driver se devolverán los detalles del usuario.

Los tokens de bot son especialmente útiles si su aplicación enviará notificaciones a espacios de trabajo 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 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 llamar al método user después de que Slack redirija al usuario de vuelta a su aplicación tras 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 puede almacenarse para enviar notificaciones a los espacios de trabajo Slack autenticados del usuario.

#Parámetros opcionales

Varios proveedores OAuth soportan otros parámetros opcionales en la solicitud de redirección. Para incluir parámetros opcionales 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();

#Recuperar detalles del usuario

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

Las propiedades y métodos disponibles pueden variar dependiendo de si el proveedor OAuth con el que se autentica soporta OAuth 1.0 o OAuth 2.0:

use Laravel\Socialite\Facades\Socialite;

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

    // Proveedores OAuth 2.0...
    $token = $user->token;
    $refreshToken = $user->refreshToken;
    $expiresIn = $user->expiresIn;

    // Proveedores OAuth 1.0...
    $token = $user->token;
    $tokenSecret = $user->tokenSecret;

    // Todos los proveedores...
    $user->getId();
    $user->getNickname();
    $user->getName();
    $user->getEmail();
    $user->getAvatar();
});

#Recuperar detalles del usuario desde un token (OAuth2)

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

use Laravel\Socialite\Facades\Socialite;

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

#Recuperar detalles del usuario desde un token y secreto (OAuth1)

Si ya tiene un token y secreto válidos para un usuario, puede recuperar sus detalles usando 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 puede usarse para deshabilitar la verificación del estado de la sesión. Esto es útil al agregar 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();