Laravel Socialite (Social Authentication)

Erfahren Sie, wie Sie Social Logins über OAuth 2.0 (GitHub, Google, Facebook usw.) mit Laravel Socialite unkompliziert umsetzen.

​

Was ist Laravel Socialite

Laravel Socialite ist ein offizielles Paket, mit dem Sie Social Logins auf Basis von OAuth 2.0 unkompliziert implementieren können. Es unterstützt zahlreiche gängige Provider wie GitHub, Google, Facebook, X (Twitter), LinkedIn und mehr; komplexe OAuth-Abläufe lassen sich damit in wenigen Codezeilen umsetzen.

Folgende Provider werden von Haus aus unterstützt:

Provider	Schlüsselname
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

​

Ablauf eines Social Logins

---

​

Installation

Fügen Sie das Paket mit Composer hinzu:

composer require laravel/socialite

Prüfen Sie beim Upgrade auf eine neue Major-Version von Socialite stets den Upgrade Guide.

---

​

Konfiguration

​

config/services.php

Fügen Sie Client-ID, Client-Secret und Callback-URL des jeweiligen Providers in config/services.php ein.

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

Wenn Sie in der Option redirect einen relativen Pfad angeben, wird dieser automatisch zu einer vollständigen URL aufgelöst.

​

.env

Verwalten Sie die Anmeldedaten über Umgebungsvariablen. Am Beispiel von GitHub:

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

Bei GitHub erhalten Sie Client-ID und Secret, indem Sie unter GitHub Developer Settings eine OAuth-App anlegen.

---

​

Authentifizierungsablauf

​

Routing

Für die OAuth-Authentifizierung sind zwei Routen erforderlich: eine für den Redirect und eine für den Callback.

use Laravel\Socialite\Facades\Socialite;

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

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

    // Access Token via $user->token abrufen
});

​

Benutzer speichern und anmelden

Im Callback rufen Sie die Benutzerinformationen ab, speichern sie in der Datenbank und melden den Benutzer dann an.

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

Damit updateOrCreate funktioniert, muss die Spalte github_id in der Tabelle users vorhanden sein. Sehen Sie sich das weiter unten aufgeführte Migrationsbeispiel an.

---

​

Benutzerinformationen abrufen

Vom Objekt, das die Methode user() zurückgibt, können Sie über die folgenden Eigenschaften und Methoden auf die Benutzerdaten zugreifen:

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

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

    // OAuth-1.0-Provider (z. B. X)
    $token = $user->token;
    $tokenSecret = $user->tokenSecret;

    // Für alle Provider
    $user->getId();
    $user->getNickname();
    $user->getName();
    $user->getEmail();
    $user->getAvatar();
});

​

Benutzer über ein Access Token abrufen

Wenn Sie einen Benutzer über ein bereits vorhandenes Access Token abrufen möchten, verwenden Sie userFromToken():

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

​

Stateless-Modus

In APIs, die keine Cookie-basierte Session verwenden, können Sie die Session-State-Prüfung mit der Methode stateless() deaktivieren:

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

---

​

Datenbank-Anbindung

​

Migration

Fügen Sie der Tabelle users Spalten für den Social Login hinzu:

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

​

Mehrere Provider über eine provider-Spalte

Wenn Sie mehrere Provider gemeinsam verwalten möchten, ist ein Aufbau mit zwei Spalten – provider und provider_id – üblich.

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

Übergeben Sie den Providernamen im Callback dynamisch:

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

​

Verknüpfung mit bestehenden Benutzern

Wenn Sie das Konto mit einem bestehenden Benutzer verknüpfen möchten, der dieselbe E-Mail-Adresse verwendet, suchen Sie nach der E-Mail-Adresse und aktualisieren dann die Spalten.

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

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

if ($user) {
    // GitHub-Daten mit bestehendem Benutzer verknüpfen
    $user->update([
        'github_id' => $socialUser->getId(),
        'github_token' => $socialUser->token,
    ]);
} else {
    // Neuen Benutzer anlegen
    $user = User::create([
        'name' => $socialUser->getName(),
        'email' => $socialUser->getEmail(),
        'github_id' => $socialUser->getId(),
        'github_token' => $socialUser->token,
    ]);
}

Auth::login($user);

---

​

Scopes und Optionen

​

Scopes hinzufügen

Mit der Methode scopes() können Sie zusätzliche Scopes angeben:

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

Die Methode setScopes() überschreibt sämtliche bereits gesetzten Scopes:

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

​

Optionale Parameter

Mit der Methode with() können Sie zusätzliche Parameter in den Redirect-Request aufnehmen:

// Bei Google eine Hosted-Domain-Beschränkung angeben
return Socialite::driver('google')
    ->with(['hd' => 'example.com'])
    ->redirect();

// Bei Google jedes Mal den Zustimmungsdialog anzeigen
return Socialite::driver('google')
    ->with(['prompt' => 'consent'])
    ->redirect();

Übergeben Sie an with() keine reservierten Schlüssel wie state oder response_type.

​

Slack-Bot-Token

Um einen Slack-Bot-Token zu erzeugen, verwenden Sie asBotUser():

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

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

---

​

Testing

Socialite bietet Mock-Funktionen für Tests. So können Sie den OAuth-Ablauf testen, ohne echte Anfragen an die Provider zu stellen.

​

Redirect testen

use Laravel\Socialite\Facades\Socialite;

test('Benutzer wird zu GitHub weitergeleitet', function () {
    Socialite::fake('github');

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

    $response->assertRedirect();
});

​

Callback testen

Übergeben Sie der Methode fake() eine User-Instanz, um die vom Provider zurückgegebenen Benutzerinformationen zu mocken. Mit User::fake() erzeugen Sie einen Fake-User.

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

test('Anmeldung über GitHub funktioniert', 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',
    ]);
});

Standardmäßig werden Fake-Werte für die OAuth-Token gesetzt. Bei Bedarf können Sie diese über zusätzliche Attribute in fake() überschreiben:

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

Wenn Sie einen OAuth-1-Benutzer faken möchten, verwenden Sie die Klasse Laravel\Socialite\One\User.

---

​

Eigene Provider erstellen

Falls Sie einen anderen als die eingebauten Provider verwenden möchten, ist die offizielle und empfohlene Vorgehensweise, mit Socialite::extend() einen eigenen Driver zu registrieren. Da der SocialiteManager von Illuminate\Support\Manager erbt, lässt er sich nach demselben Muster wie andere Laravel-Driver-Systeme erweitern.

Näheres zum Manager-Pattern und zum Mechanismus von extend() finden Sie unter Erläuterung der Manager-Klasse.

​

1. Provider-Klasse erstellen

Erweitern Sie Laravel\Socialite\Two\AbstractProvider und implementieren Sie die vier abstrakten Methoden.

// app/Socialite/ExampleProvider.php

namespace App\Socialite;

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

class ExampleProvider extends AbstractProvider
{
    // Autorisierungs-URL (Ziel des Redirects)
    public function getAuthUrl($state): string
    {
        return $this->buildAuthUrlFromBase('https://example.com/oauth/authorize', $state);
    }

    // URL zum Beziehen des Access Tokens
    protected function getTokenUrl(): string
    {
        return 'https://example.com/oauth/token';
    }

    // Benutzerinformationen mit dem Access Token abrufen
    protected function getUserByToken($token): array
    {
        $response = $this->getHttpClient()->get('https://example.com/api/user', [
            'headers' => ['Authorization' => 'Bearer '.$token],
        ]);

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

    // Das erhaltene Array in ein Socialite-User-Objekt überführen
    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,
        ]);
    }
}

Die Aufgaben der vier zu implementierenden Methoden im Überblick:

Methode	Aufgabe
getAuthUrl($state)	Liefert die OAuth-Autorisierungs-URL, zu der der Benutzer weitergeleitet wird
getTokenUrl()	Endpoint zum Umtauschen des Authorization Codes gegen ein Access Token
getUserByToken($token)	Ruft die User-API mit dem Access Token auf und gibt das Ergebnis als Array zurück
mapUserToObject(array $user)	Konvertiert das erhaltene Array in ein Socialite-User-Objekt

​

2. Im Service-Provider registrieren

Registrieren Sie den Driver in der boot()-Methode des AppServiceProvider über 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. Konfiguration hinzufügen

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

​

4. Wie üblich verwenden

Nach der Registrierung nutzen Sie den Driver mit exakt derselben API wie die eingebauten Provider.

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

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

Empfehlenswert ist auch, Drittanbieter-Pakete zu nutzen, die Socialite auf offizielle Weise über extend() erweitern.

---

​

Verwandte Pakete

Nachfolgend Socialite-Erweiterungen, die vom Betreiber dieser Website veröffentlicht wurden. Alle sind auf offizielle Weise über Socialite::extend() implementiert und können nach einem Eintrag in config/services.php direkt verwendet werden.

LINE

LINE SDK für Laravel. Neben dem OAuth-Login über Socialite ist auch die Messaging API integriert.

Bluesky

Anbindung an das AT Protocol (Bluesky). Unterstützt OAuth-Authentifizierung und das Absetzen von Posts.

Discord

OAuth2-Login mit Discord.

Threads

Anbindung an Meta Threads. Unterstützt OAuth-Authentifizierung und die Posting-API.

Amazon

OAuth-Login über Login with Amazon.

Mastodon

OAuth-Login gegen Mastodon-Instanzen.

WordPress

OAuth-Login für WordPress.com und selbst gehostete WordPress-Instanzen.