Laravel Socialite (authentification sociale)

Qu’est-ce que Laravel Socialite

Laravel Socialite est le package officiel qui simplifie le login social via OAuth 2.0. Il prend en charge les principaux providers (GitHub, Google, Facebook, X (Twitter), LinkedIn…) et remplace une implémentation OAuth complexe par quelques lignes. Providers intégrés :

Provider	Clé
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`

Flux

Installation

composer require laravel/socialite

Consultez le guide de mise à jour lors d’une montée de version majeure.

Configuration

`config/services.php`

Ajoutez client ID, secret et URL de callback par provider.

// 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'),
],

Un chemin relatif dans redirect est automatiquement résolu en URL complète.

`.env`

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

Créez une OAuth App dans GitHub Developer Settings pour obtenir vos identifiants.

Flux d’authentification

Routing

Deux routes : redirection et callback.

use Laravel\Socialite\Facades\Socialite;

// Rediriger vers GitHub
Route::get('/auth/github', function () {
    return Socialite::driver('github')->redirect();
});

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

    // $user->token pour l'access token
});

Dans le callback, enregistrez l’utilisateur puis connectez-le.

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

updateOrCreate nécessite la colonne github_id sur la table users. Voir la migration ci-après.

Récupérer les informations utilisateur

Sur l’objet retourné par user() :

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

    // OAuth 2
    $token = $user->token;
    $refreshToken = $user->refreshToken;
    $expiresIn = $user->expiresIn;

    // OAuth 1 (X…)
    $token = $user->token;
    $tokenSecret = $user->tokenSecret;

    // Commun
    $user->getId();
    $user->getNickname();
    $user->getName();
    $user->getEmail();
    $user->getAvatar();
});

Depuis un access token existant

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

Mode stateless

Pour une API sans cookies de session, stateless() désactive la vérification d’état.

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

Intégration DB

Migration

Ajoutez les colonnes de login social.

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

Colonnes `provider` pour plusieurs providers

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

Callback dynamique :

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

Rattachement à un utilisateur existant

Cherchez par e-mail avant de créer.

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

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

if ($user) {
    $user->update([
        'github_id' => $socialUser->getId(),
        'github_token' => $socialUser->token,
    ]);
} else {
    $user = User::create([
        'name' => $socialUser->getName(),
        'email' => $socialUser->getEmail(),
        'github_id' => $socialUser->getId(),
        'github_token' => $socialUser->token,
    ]);
}

Auth::login($user);

Scopes et options

Scopes

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

setScopes() remplace complètement les scopes.

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

Paramètres optionnels

with() ajoute des paramètres à la redirection.

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

// Afficher systématiquement l'écran de consentement
return Socialite::driver('google')
    ->with(['prompt' => 'consent'])
    ->redirect();

N’utilisez pas with() pour des mots-clés réservés comme state ou response_type.

Token bot Slack

Pour un token bot Slack, asBotUser().

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

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

Tests

Socialite propose un moteur de mock.

Redirection

use Laravel\Socialite\Facades\Socialite;

test('redirige vers GitHub', function () {
    Socialite::fake('github');

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

    $response->assertRedirect();
});

Callback

User::fake() crée un utilisateur factice.

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

test('login via 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',
    ]);
});

Par défaut, un token factice est fourni. Vous pouvez surcharger.

$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'],
]);

Pour OAuth 1, utilisez Laravel\Socialite\One\User.

Provider personnalisé

Utilisez Socialite::extend() pour ajouter un driver. SocialiteManager hérite de Illuminate\Support\Manager, comme les autres systèmes de driver Laravel.

Voir aussi Classe Manager pour le pattern et extend().

1. Classe du provider

Héritez de Laravel\Socialite\Two\AbstractProvider et implémentez 4 méthodes.

// app/Socialite/ExampleProvider.php

namespace App\Socialite;

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

class ExampleProvider extends AbstractProvider
{
    // URL d'autorisation (où rediriger l'utilisateur)
    public function getAuthUrl($state): string
    {
        return $this->buildAuthUrlFromBase('https://example.com/oauth/authorize', $state);
    }

    // URL pour obtenir le token
    protected function getTokenUrl(): string
    {
        return 'https://example.com/oauth/token';
    }

    // Récupérer l'utilisateur via le 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);
    }

    // Mapper le tableau vers un User 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,
        ]);
    }
}

Rôle des 4 méthodes :

Méthode	Rôle
`getAuthUrl($state)`	URL de redirection OAuth
`getTokenUrl()`	Endpoint d’échange code → token
`getUserByToken($token)`	Récupère les infos utilisateur en tableau
`mapUserToObject(array $user)`	Convertit en `User` Socialite

2. Enregistrement dans le service provider

Dans boot() de AppServiceProvider.

// 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. Ajouter la configuration

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

4. Utilisation standard

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

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

Vous pouvez également utiliser des packages tiers qui étendent Socialite de manière propre via extend().

Packages associés

Extensions Socialite publiées par le propriétaire de ce site, implémentées correctement via Socialite::extend().

LINE

SDK LINE : Socialite + Messaging API.

Bluesky

Intégration AT Protocol : OAuth + publication.

Discord

OAuth2 Discord.

Threads

OAuth + API de publication Meta Threads.

Amazon

Mastodon

OAuth vers une instance Mastodon.

WordPress

WordPress.com et WordPress auto-hébergé.

​Qu’est-ce que Laravel Socialite

​Flux

​Installation

​Configuration

​config/services.php

​.env

​Flux d’authentification

​Routing

​Enregistrement + login

​Récupérer les informations utilisateur

​Depuis un access token existant

​Mode stateless

​Intégration DB

​Migration

​Colonnes provider pour plusieurs providers

​Rattachement à un utilisateur existant

​Scopes et options

​Scopes

​Paramètres optionnels

​Token bot Slack

​Tests

​Redirection

​Callback

​Provider personnalisé

​1. Classe du provider

​2. Enregistrement dans le service provider

​3. Ajouter la configuration

​4. Utilisation standard

​Packages associés

LINE

Bluesky

Discord

Threads

Amazon

Mastodon

WordPress

Qu’est-ce que Laravel Socialite

Flux

Installation

Configuration

`config/services.php`

`.env`

Flux d’authentification

Routing

Enregistrement + login

Récupérer les informations utilisateur

Depuis un access token existant

Mode stateless

Intégration DB

Migration

Colonnes `provider` pour plusieurs providers

Rattachement à un utilisateur existant

Scopes et options

Scopes

Paramètres optionnels

Token bot Slack

Tests

Redirection

Callback

Provider personnalisé

1. Classe du provider

2. Enregistrement dans le service provider

3. Ajouter la configuration

4. Utilisation standard

Packages associés