Laravel Socialite (autenticación social)

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`

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' => '[email protected]',
    ]));

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

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

    $this->assertDatabaseHas('users', [
        'name' => 'Jane Doe',
        'email' => '[email protected]',
        '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' => '[email protected]',
    '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

Threads

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

​Qué es Laravel Socialite

​Flujo del login social

​Instalación

​Configuración

​config/services.php

​.env

​Flujo de autenticación

​Rutas

​Guardar el usuario e iniciar sesión

​Información del usuario

​Obtener el usuario a partir de un access token

​Modo stateless

​Integración con la base de datos

​Migración

​Soportar múltiples proveedores con una columna provider

​Vincular con usuarios existentes

​Scopes y opciones

​Añadir scopes

​Parámetros adicionales

​Tokens de bot de Slack

​Pruebas

​Test de la redirección

​Test del callback

​Cómo crear un proveedor personalizado

​1. Crear la clase del proveedor

​2. Registrarlo en un service provider

​3. Añadir la configuración

​4. Usarlo como cualquier otro proveedor

​Paquetes relacionados

LINE

Bluesky

Discord

Threads

Amazon

Mastodon

WordPress

Qué es Laravel Socialite

Flujo del login social

Instalación

Configuración

`config/services.php`

`.env`

Flujo de autenticación

Rutas

Guardar el usuario e iniciar sesión

Información del usuario

Obtener el usuario a partir de un access token

Modo stateless

Integración con la base de datos

Migración

Soportar múltiples proveedores con una columna `provider`

Vincular con usuarios existentes

Scopes y opciones

Añadir scopes

Parámetros adicionales

Tokens de bot de Slack

Pruebas

Test de la redirección

Test del callback

Cómo crear un proveedor personalizado

1. Crear la clase del proveedor

2. Registrarlo en un service provider

3. Añadir la configuración

4. Usarlo como cualquier otro proveedor

Paquetes relacionados