# Laravel Socialite

# Introducción

Además de la típica, autenticación basada en formularios, Laravel también proporciona una sencilla y conveniente forma de autenticar con proveedores OAuth usando Laravel Socialite. Actualmente Socialite soporta autenticación con Facebook, Twitter, LinkedIn, Google, Github, GitLab y Bitbucket.

TIP

Los adaptadores para otras plataformas son listados en el sitio web de Proveedores de Socialite manejado por la comunidad.

# Actualizando Socialite

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

# Instalación

Para empezar con Socialite, usa Composer para agregar el paquete a las dependencias de tu proyecto:

composer require laravel/socialite

# Configuración

Antes de usar Socialite, también necesitaras agregar las credenciales para los servicios OAuth que tu aplicación utiliza. Estas credenciales deberían estar colocadas en tu archivo de configuración config/services.php, y debería usar la clave facebook, twitter, linkedin, google, github, gitlab o bitbucket dependiendo del proveedor que tu aplicación requiera. Por ejemplo:

'github' => [
    'client_id' => env('GITHUB_CLIENT_ID'),         // Your GitHub Client ID
    'client_secret' => env('GITHUB_CLIENT_SECRET'), // Your GitHub Client Secret
    'redirect' => 'http://your-callback-url',
],

TIP

Si la opción redirect contiene una ruta relativa, será resuelta automáticamente a una URL completamente calificada.

# Enrutamiento

A continuación, ¡estás listo para autenticar usuarios! Necesitarás dos rutas: una para redireccionar el usuario al proveedor OAuth y otra para recibir la función de retorno del proveedor después de la autenticación. Accederemos a Socialite usando la clase facade Socialite:

<?php

namespace App\Http\Controllers\Auth;

use Socialite;

class LoginController extends Controller
{
    /**
    * Redirect the user to the GitHub authentication page.
    *
    * @return \Illuminate\Http\Response
    */
    public function redirectToProvider()
    {
        return Socialite::driver('github')->redirect();
    }

    /**
    * Obtain the user information from GitHub.
    *
    * @return \Illuminate\Http\Response
    */
    public function handleProviderCallback()
    {
        $user = Socialite::driver('github')->user();

        // $user->token;
    }
}

El método redirect se toma la tarea de enviar el usuario al proveedor OAuth, mientras que el método user leerá la solicitud entrante y obtendrá lá información del usuario desde el proveedor.

Necesitarás definir las rutas para tus métodos de controlador:

Route::get('login/github', 'Auth\LoginController@redirectToProvider');
Route::get('login/github/callback', 'Auth\LoginController@handleProviderCallback');

# Parámetros opcionales

Un número de proveedores OAuth soportan parámetros opcionales en la solicitud de redirección. Para incluir algunos de los parámetros opcionales en la solicitud, llama el método with con un arreglo asociativo:

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

Nota

Al momento de usar el método with, procura no pasar algunas palabras reservadas tales como state or response_type.

# Alcances de acceso

Antes de redirecionar al usuario, también puedes agregar "alcances (scopes)" adicionales en la solicitud usando el método scopes. Este método mezclará todos los alcances existentes con los que suministras:

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

Puedes sobrescribir todos los alcances existentes usando el método setScopes:

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

# Autenticación sin estado

El método stateless puede ser usado para deshabilitar la verificación de estado de sesión. Esto es útil al momento de agregar la autenticación de una red social a una API.

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

# Obteniendo detalles de usuario

Una vez que tengas una instancia de usuario, puedes aprovechar de obtener algunos detalles del usuario:

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

// OAuth Two Providers
$token = $user->token;
$refreshToken = $user->refreshToken; // not always provided
$expiresIn = $user->expiresIn;

// OAuth One Providers
$token = $user->token;
$tokenSecret = $user->tokenSecret;

// All Providers
$user->getId();
$user->getNickname();
$user->getName();
$user->getEmail();
$user->getAvatar();

# Obteniendo Los detalles de usuario desde un token (OAuth2)

Si ya tienes un token de acceso válido de un usuario, puedes obtener sus detalles usando el método userFromToken:

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

# Obteniendo los detalles de usuario desde un token y secreto (OAuth1)

Si ya tienes un par válido de token / secreto de un usuario, puedes obtener sus detalles usando el método userFromTokenAndSecret:

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