Laravel Socialite (autenticación social)

Aprende a implementar de forma sencilla el inicio de sesión social (GitHub, Google, Facebook, etc.) con OAuth 2.0 mediante Laravel Socialite.

​

Qué es Laravel Socialite

Laravel Socialite es el paquete oficial para implementar de forma sencilla el login social con OAuth 2.0. Soporta los principales proveedores (GitHub, Google, Facebook, X (Twitter), LinkedIn…) y reduce a unas pocas líneas la implementación de un flujo OAuth complejo.

Proveedores soportados de fábrica:

Proveedor	Clave
Bitbucket	bitbucket
Facebook	facebook
GitHub	github
GitLab	gitlab
Google	google
LinkedIn (OpenID)	linkedin-openid
Slack	slack / slack-openid
Spotify	spotify
Twitch	twitch
X (Twitter)	x

​

Flujo del login social

---

​

Instalación

Añade el paquete con Composer.

composer require laravel/socialite

Al actualizar Socialite a una versión mayor, consulta siempre la guía de actualización.

---

​

Configuración

​

config/services.php

Añade el client ID, el secret y la URL de callback de cada proveedor en config/services.php.

// config/services.php

'github' => [
    'client_id' => env('GITHUB_CLIENT_ID'),
    'client_secret' => env('GITHUB_CLIENT_SECRET'),
    'redirect' => env('GITHUB_REDIRECT_URI'),
],

'google' => [
    'client_id' => env('GOOGLE_CLIENT_ID'),
    'client_secret' => env('GOOGLE_CLIENT_SECRET'),
    'redirect' => env('GOOGLE_REDIRECT_URI'),
],

'facebook' => [
    'client_id' => env('FACEBOOK_CLIENT_ID'),
    'client_secret' => env('FACEBOOK_CLIENT_SECRET'),
    'redirect' => env('FACEBOOK_REDIRECT_URI'),
],

Si redirect es una ruta relativa, se resolverá automáticamente a una URL completa.

​

.env

Gestiona las credenciales mediante variables de entorno. Ejemplo con GitHub:

GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret
GITHUB_REDIRECT_URI=https://example.com/auth/github/callback

En el caso de GitHub, crea una OAuth App en GitHub Developer Settings para obtener el client ID y el secret.

---

​

Flujo de autenticación

​

Rutas

Se necesitan dos rutas: una para redirigir y otra para el callback.

use Laravel\Socialite\Facades\Socialite;

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

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

    // $user->token contiene el access token
});

​

Guardar el usuario e iniciar sesión

En el callback, recupera la información del usuario, guárdala y autentica.

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

Route::get('/auth/github/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');
});

Para usar updateOrCreate así, la tabla users debe tener la columna github_id. Consulta el ejemplo de migración más abajo.

---

​

Información del usuario

El objeto devuelto por user() expone la información con estas propiedades y métodos.

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

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

    // Proveedores OAuth 1.0 (X, etc.)
    $token = $user->token;
    $tokenSecret = $user->tokenSecret;

    // Común a todos
    $user->getId();
    $user->getNickname();
    $user->getName();
    $user->getEmail();
    $user->getAvatar();
});

​

Obtener el usuario a partir de un access token

Si ya tienes el token, obtén el usuario con userFromToken().

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

​

Modo stateless

Para APIs sin cookies de sesión, desactiva la verificación de estado con stateless().

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

---

​

Integración con la base de datos

​

Migración

Añade columnas de login social a la tabla users.

// database/migrations/xxxx_xx_xx_add_github_columns_to_users_table.php

return new class extends Migration
{
    public function up(): void
    {
        Schema::table('users', function (Blueprint $table) {
            $table->string('github_id')->nullable()->unique()->after('id');
            $table->string('github_token')->nullable()->after('github_id');
            $table->string('github_refresh_token')->nullable()->after('github_token');
        });
    }

    public function down(): void
    {
        Schema::table('users', function (Blueprint $table) {
            $table->dropColumn(['github_id', 'github_token', 'github_refresh_token']);
        });
    }
};

​

Soportar múltiples proveedores con una columna provider

Para gestionar varios proveedores en la misma tabla, se suele usar el patrón provider + provider_id.

Schema::table('users', function (Blueprint $table) {
    $table->string('provider')->nullable()->after('id');
    $table->string('provider_id')->nullable()->after('provider');
    $table->string('provider_token')->nullable()->after('provider_id');

    $table->unique(['provider', 'provider_id']);
});

Pasa el nombre del proveedor dinámicamente en el callback.

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

    $user = User::updateOrCreate(
        [
            'provider' => $provider,
            'provider_id' => $socialUser->getId(),
        ],
        [
            'name' => $socialUser->getName(),
            'email' => $socialUser->getEmail(),
            'provider_token' => $socialUser->token,
        ]
    );

    Auth::login($user);

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

​

Vincular con usuarios existentes

Si quieres asociar la cuenta social con un usuario ya registrado con el mismo email, búscalo por correo y actualiza los datos.

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

$user = User::where('email', $socialUser->getEmail())->first();

if ($user) {
    // Vincula la info de GitHub al usuario existente
    $user->update([
        'github_id' => $socialUser->getId(),
        'github_token' => $socialUser->token,
    ]);
} else {
    // Crea un nuevo usuario
    $user = User::create([
        'name' => $socialUser->getName(),
        'email' => $socialUser->getEmail(),
        'github_id' => $socialUser->getId(),
        'github_token' => $socialUser->token,
    ]);
}

Auth::login($user);

---

​

Scopes y opciones

​

Añadir scopes

Con scopes() añades scopes adicionales.

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

Con setScopes() reemplazas por completo los scopes existentes.

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

​

Parámetros adicionales

Con with() añades parámetros a la petición de redirección.

// Restricción de dominio en Google
return Socialite::driver('google')
    ->with(['hd' => 'example.com'])
    ->redirect();

// Fuerza la pantalla de consentimiento en Google
return Socialite::driver('google')
    ->with(['prompt' => 'consent'])
    ->redirect();

No pases palabras clave reservadas como state o response_type mediante with().

​

Tokens de bot de Slack

Para generar tokens de bot de Slack, usa asBotUser().

// En la redirección
return Socialite::driver('slack')
    ->asBotUser()
    ->setScopes(['chat:write', 'chat:write.public', 'chat:write.customize'])
    ->redirect();

// En el callback
$user = Socialite::driver('slack')->asBotUser()->user();

---

​

Pruebas

Socialite proporciona utilidades de mock para probar el flujo OAuth sin peticiones reales al proveedor.

​

Test de la redirección

use Laravel\Socialite\Facades\Socialite;

test('el usuario se redirige a GitHub', function () {
    Socialite::fake('github');

    $response = $this->get('/auth/github');

    $response->assertRedirect();
});

​

Test del callback

Pásale a fake() un usuario para mockear la respuesta del proveedor. Crea el usuario falso con User::fake().

use Laravel\Socialite\Facades\Socialite;
use Laravel\Socialite\Two\User;

test('se puede iniciar sesión con GitHub', function () {
    Socialite::fake('github', User::fake([
        'id' => 'github-123',
        'name' => 'Jane Doe',
        'email' => '[e-mail]',
    ]));

    $response = $this->get('/auth/github/callback');

    $response->assertRedirect('/dashboard');

    $this->assertDatabaseHas('users', [
        'name' => 'Jane Doe',
        'email' => '[e-mail]',
        'github_id' => 'github-123',
    ]);
});

Por defecto se establecen valores falsos de token OAuth. Puedes sobrescribirlos pasando atributos extra a fake().

$fakeUser = User::fake([
    'id' => 'github-123',
    'name' => 'Jane Doe',
    'email' => '[e-mail]',
    'token' => 'fake-token',
    'refreshToken' => 'fake-refresh-token',
    'expiresIn' => 3600,
    'approvedScopes' => ['read:user', 'public_repo'],
]);

Para OAuth 1, usa la clase Laravel\Socialite\One\User en el fake.

---

​

Cómo crear un proveedor personalizado

Si necesitas un proveedor que no está entre los integrados, la forma oficial es registrar un driver personalizado con Socialite::extend(). SocialiteManager hereda de Illuminate\Support\Manager, así que se extiende con el mismo mecanismo que otros drivers de Laravel.

Para más detalle sobre el patrón Manager y extend(), consulta la explicación de la clase Manager.

​

1. Crear la clase del proveedor

Extiende Laravel\Socialite\Two\AbstractProvider e implementa los cuatro métodos abstractos.

// app/Socialite/ExampleProvider.php

namespace App\Socialite;

use Laravel\Socialite\Two\AbstractProvider;
use Laravel\Socialite\Two\User;

class ExampleProvider extends AbstractProvider
{
    // URL de autorización (adonde se redirige al usuario)
    public function getAuthUrl($state): string
    {
        return $this->buildAuthUrlFromBase('https://example.com/oauth/authorize', $state);
    }

    // URL para obtener el access token
    protected function getTokenUrl(): string
    {
        return 'https://example.com/oauth/token';
    }

    // Obtiene la info del usuario a partir del token
    protected function getUserByToken($token): array
    {
        $response = $this->getHttpClient()->get('https://example.com/api/user', [
            'headers' => ['Authorization' => 'Bearer '.$token],
        ]);

        return json_decode($response->getBody(), true);
    }

    // Convierte el array obtenido en un objeto User de Socialite
    protected function mapUserToObject(array $user): User
    {
        return (new User)->setRaw($user)->map([
            'id'       => $user['id'],
            'nickname' => $user['login'] ?? null,
            'name'     => $user['name'],
            'email'    => $user['email'],
            'avatar'   => $user['avatar_url'] ?? null,
        ]);
    }
}

Rol de cada método:

Método	Función
getAuthUrl($state)	Devuelve la URL de autorización OAuth a la que redirigir
getTokenUrl()	Endpoint para intercambiar el código por un access token
getUserByToken($token)	Llama a la API del proveedor con el token y devuelve un array
mapUserToObject(array $user)	Convierte ese array en un User de Socialite

​

2. Registrarlo en un service provider

En el boot() de AppServiceProvider, registra el driver con Socialite::extend().

// app/Providers/AppServiceProvider.php

use App\Socialite\ExampleProvider;
use Laravel\Socialite\Facades\Socialite;

public function boot(): void
{
    Socialite::extend('example', function ($app) {
        $config = $app['config']['services.example'];

        return Socialite::buildProvider(ExampleProvider::class, $config);
    });
}

​

3. Añadir la configuración

// config/services.php
'example' => [
    'client_id'     => env('EXAMPLE_CLIENT_ID'),
    'client_secret' => env('EXAMPLE_CLIENT_SECRET'),
    'redirect'      => env('EXAMPLE_REDIRECT_URI'),
],

​

4. Usarlo como cualquier otro proveedor

Ya se usa con la misma API que los proveedores integrados.

// Redirección
Route::get('/auth/example', function () {
    return Socialite::driver('example')->redirect();
});

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

Considera también los paquetes de terceros que extienden Socialite de esta manera oficial mediante extend().

---

​

Paquetes relacionados

Extensiones de Socialite publicadas por los mantenedores de este sitio. Todas siguen la forma oficial usando Socialite::extend(), así que basta con añadir la configuración a config/services.php.

LINE

LINE SDK para Laravel. Login OAuth con Socialite y también integración con Messaging API.

Bluesky

Integración con AT Protocol (Bluesky). Soporta autenticación OAuth y publicación de posts.

Discord

Login con Discord OAuth2.

Threads

Integración con Meta Threads. Soporta autenticación OAuth y la API de publicación.

Amazon

Login con Amazon vía OAuth.

Mastodon

Login OAuth con instancias de Mastodon.

WordPress

Login OAuth con WordPress.com y WordPress autoalojado.