Laravel Socialite (sociale authenticatie)

Wat is Laravel Socialite

Laravel Socialite is het officiële pakket waarmee je eenvoudig sociale login via OAuth 2.0 implementeert. Het ondersteunt de belangrijkste providers zoals GitHub, Google, Facebook, X (Twitter) en LinkedIn, zodat een complexe OAuth-implementatie in slechts enkele regels code kan. De ingebouwde ondersteunde providers zijn:

Provider	Sleutelnaam
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`

Installatie

Voeg het pakket toe met Composer.

composer require laravel/socialite

Raadpleeg bij een major-versie-upgrade van Socialite altijd de upgradegids.

Configuratie

config/services.php

Voeg de client-ID, secret en callback-URL van elke provider toe aan 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'),
],

Geef je bij de optie redirect een relatief pad op, dan wordt dit automatisch omgezet naar een volledige URL.

.env

Beheer de credentials via omgevingsvariabelen. Hier GitHub als voorbeeld.

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

Bij GitHub verkrijg je de client-ID en het secret door in de GitHub Developer Settings een OAuth App aan te maken.

Authenticatieflow

Routing

Voor OAuth-authenticatie zijn twee routes nodig: één voor de redirect en één voor de callback.

use Laravel\Socialite\Facades\Socialite;

// De gebruiker doorsturen naar GitHub
Route::get('/auth/github', function () {
    return Socialite::driver('github')->redirect();
});

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

    // Het access token ophalen via $user->token
});

De gebruiker opslaan en inloggen

In de callbackroute haal je de gebruikersgegevens op, sla je ze op in de database en log je vervolgens in.

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

Bij gebruik van updateOrCreate moet de kolom github_id bestaan in de users-tabel. Zie het migratievoorbeeld verderop.

Gebruikersgegevens ophalen

Uit het object dat de user()-methode teruggeeft, haal je de gebruikersgegevens op via de volgende property’s en methoden.

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

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

    // OAuth 1.0-providers (X e.d.)
    $token = $user->token;
    $tokenSecret = $user->tokenSecret;

    // Voor alle providers
    $user->getId();
    $user->getNickname();
    $user->getName();
    $user->getEmail();
    $user->getAvatar();
});

Een gebruiker ophalen via een access token

Wil je gebruikersgegevens ophalen met een bestaand access token, gebruik dan userFromToken().

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

Gebruik je Facebook Limited Login in een iOS-app, dan geeft Facebook een OIDC-token terug in plaats van een access token. Om gebruikersgegevens uit een OIDC-token op te halen, geef je de nonce die bij het starten van de login is gebruikt door aan userFromToken().

$user = Socialite::driver('facebook')->userFromToken($token, $nonce);

Stateless modus

In API’s zonder cookiesessies kun je met de methode stateless() de validatie van de sessiestatus uitschakelen.

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

Databasekoppeling

Migratie

Voeg kolommen voor sociale login toe aan de users-tabel.

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

Meerdere providers ondersteunen met een provider-kolom

Wil je meerdere providers centraal beheren, dan is een opzet met de twee kolommen provider / provider_id gebruikelijk.

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

In de callbackverwerking geef je de providernaam dynamisch door.

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

Koppelen aan een bestaande gebruiker

Wil je een account koppelen aan een bestaande gebruiker met hetzelfde e-mailadres, zoek dan eerst op e-mailadres en werk daarna de kolommen bij.

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

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

if ($user) {
    // GitHub-gegevens koppelen aan de bestaande gebruiker
    $user->update([
        'github_id' => $socialUser->getId(),
        'github_token' => $socialUser->token,
    ]);
} else {
    // Aanmaken als nieuwe gebruiker
    $user = User::create([
        'name' => $socialUser->getName(),
        'email' => $socialUser->getEmail(),
        'github_id' => $socialUser->getId(),
        'github_token' => $socialUser->token,
    ]);
}

Auth::login($user);

Scopes en opties

Scopes toevoegen

Met de methode scopes() geef je extra scopes op.

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

Met de methode setScopes() overschrijf je alle bestaande scopes.

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

Optionele parameters

Met de methode with() neem je extra parameters op in het redirectrequest.

// Een hostbeperking opgeven bij Google
return Socialite::driver('google')
    ->with(['hd' => 'example.com'])
    ->redirect();

// Bij Google elke keer het toestemmingsscherm tonen
return Socialite::driver('google')
    ->with(['prompt' => 'consent'])
    ->redirect();

Let op dat je via de methode with() geen gereserveerde sleutelwoorden zoals state of response_type doorgeeft.

Slack-bottokens

Wil je een Slack-bottoken genereren, gebruik dan asBotUser().

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

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

Testen

Socialite biedt mockfunctionaliteit voor tests. Zo test je de OAuth-flow zonder echte requests naar de provider.

De redirect testen

use Laravel\Socialite\Facades\Socialite;

test('gebruiker wordt doorgestuurd naar GitHub', function () {
    Socialite::fake('github');

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

    $response->assertRedirect();
});

De callback testen

Geef een gebruikersinstantie door aan de methode fake() om de door de provider teruggegeven gebruikersgegevens te mocken. Met User::fake() genereer je een fake-gebruiker.

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

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

Standaard worden er fake OAuth-tokenwaarden ingesteld. Indien nodig kun je die overriden door extra attributen aan fake() door te geven.

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

Wil je een OAuth 1-gebruiker faken, gebruik dan de klasse Laravel\Socialite\One\User.

Een custom provider maken

Wil je een andere provider gebruiken dan de ingebouwde, dan is het registreren van een custom driver via Socialite::extend() de officiële, aanbevolen weg. Omdat SocialiteManager erft van Illuminate\Support\Manager, kun je uitbreiden met hetzelfde mechanisme als bij andere Laravel-driversystemen.

Zie ook de uitleg over de Manager-klasse voor het Manager-patroon en hoe extend() werkt.

1. De providerklasse maken

Erf van Laravel\Socialite\Two\AbstractProvider en implementeer de vier abstracte methoden.

// app/Socialite/ExampleProvider.php

namespace App\Socialite;

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

class ExampleProvider extends AbstractProvider
{
    // Autorisatie-URL (waarheen de gebruiker wordt doorgestuurd)
    public function getAuthUrl($state): string
    {
        return $this->buildAuthUrlFromBase('https://example.com/oauth/authorize', $state);
    }

    // URL voor het ophalen van het access token
    protected function getTokenUrl(): string
    {
        return 'https://example.com/oauth/token';
    }

    // Gebruikersgegevens ophalen met het access 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);
    }

    // De opgehaalde array mappen naar het User-object van 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,
        ]);
    }
}

De rollen van de vier te implementeren methoden:

Methode	Rol
`getAuthUrl($state)`	Geeft de OAuth-autorisatie-URL terug waarheen de gebruiker wordt doorgestuurd
`getTokenUrl()`	Het endpoint dat de autorisatiecode inwisselt voor een access token
`getUserByToken($token)`	Roept met het access token de gebruikers-API aan en geeft een array terug
`mapUserToObject(array $user)`	Zet de opgehaalde array om naar het `User`-object van Socialite

2. Registreren in een service provider

Registreer de driver met Socialite::extend() in de boot()-methode van je 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. Configuratie toevoegen

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

4. Gebruiken zoals gewone Socialite

Na registratie gebruik je hem met exact dezelfde API als de ingebouwde providers.

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

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

Ook het gebruik van third-party pakketten die Socialite op de officiële manier via extend() uitbreiden is een aanrader.

Gerelateerde pakketten

Socialite-uitbreidingspakketten die de eigenaar van deze site heeft gepubliceerd. Ze zijn allemaal geïmplementeerd op de officiële manier via Socialite::extend() en werken door simpelweg de configuratie toe te voegen aan config/services.php.

LINE

LINE SDK voor Laravel. Naast OAuth-login via Socialite ook integratie met de Messaging API.

Bluesky

Integratie met het AT Protocol (Bluesky). Ondersteunt OAuth-authenticatie en het versturen van posts.

​Wat is Laravel Socialite

​De flow van sociale login

​Installatie

​Configuratie

​config/services.php

​.env

​Authenticatieflow

​Routing

​De gebruiker opslaan en inloggen

​Gebruikersgegevens ophalen

​Een gebruiker ophalen via een access token

​Stateless modus

​Databasekoppeling

​Migratie

​Meerdere providers ondersteunen met een provider-kolom

​Koppelen aan een bestaande gebruiker

​Scopes en opties

​Scopes toevoegen

​Optionele parameters

​Slack-bottokens

​Testen

​De redirect testen

​De callback testen

​Een custom provider maken

​1. De providerklasse maken

​2. Registreren in een service provider

​3. Configuratie toevoegen

​4. Gebruiken zoals gewone Socialite

​Gerelateerde pakketten

LINE

Bluesky

Discord

Threads

Amazon

Mastodon

WordPress

Wat is Laravel Socialite

De flow van sociale login

Installatie

Configuratie

config/services.php

.env

Authenticatieflow

Routing

De gebruiker opslaan en inloggen

Gebruikersgegevens ophalen

Een gebruiker ophalen via een access token

Stateless modus

Databasekoppeling

Migratie

Meerdere providers ondersteunen met een provider-kolom

Koppelen aan een bestaande gebruiker

Scopes en opties

Scopes toevoegen

Optionele parameters

Slack-bottokens

Testen

De redirect testen

De callback testen

Een custom provider maken

1. De providerklasse maken

2. Registreren in een service provider

3. Configuratie toevoegen

4. Gebruiken zoals gewone Socialite

Gerelateerde pakketten