Laravel Socialite (Social Authentication)

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`

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

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

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

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

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.

Laravel Socialite (Social Authentication)

Was ist Laravel Socialite

Installation

Konfiguration

config/services.php

.env

Authentifizierungsablauf

Routing

Benutzer speichern und anmelden

Benutzerinformationen abrufen

Benutzer über ein Access Token abrufen

Stateless-Modus

Datenbank-Anbindung

Migration

Mehrere Provider über eine `provider`-Spalte

Verknüpfung mit bestehenden Benutzern

Scopes und Optionen

Scopes hinzufügen

Optionale Parameter

Slack-Bot-Token

Testing

Redirect testen

Callback testen

Eigene Provider erstellen

1. Provider-Klasse erstellen

2. Im Service-Provider registrieren

3. Konfiguration hinzufügen

4. Wie üblich verwenden

Verwandte Pakete

LINE

Bluesky

Discord

Threads

Amazon

Mastodon

WordPress

​Was ist Laravel Socialite

​Ablauf eines Social Logins

​Installation

​Konfiguration

​config/services.php

​.env

​Authentifizierungsablauf

​Routing

​Benutzer speichern und anmelden

​Benutzerinformationen abrufen

​Benutzer über ein Access Token abrufen

​Stateless-Modus

​Datenbank-Anbindung

​Migration

​Mehrere Provider über eine provider-Spalte

​Verknüpfung mit bestehenden Benutzern

​Scopes und Optionen

​Scopes hinzufügen

​Optionale Parameter

​Slack-Bot-Token

​Testing

​Redirect testen

​Callback testen

​Eigene Provider erstellen

​1. Provider-Klasse erstellen

​2. Im Service-Provider registrieren

​3. Konfiguration hinzufügen

​4. Wie üblich verwenden

​Verwandte Pakete

LINE

Bluesky

Discord

Threads

Amazon

Mastodon

WordPress

Was ist Laravel Socialite

Ablauf eines Social Logins

Installation

Konfiguration

config/services.php

.env

Authentifizierungsablauf

Routing

Benutzer speichern und anmelden

Benutzerinformationen abrufen

Benutzer über ein Access Token abrufen

Stateless-Modus

Datenbank-Anbindung

Migration

Mehrere Provider über eine `provider`-Spalte

Verknüpfung mit bestehenden Benutzern

Scopes und Optionen

Scopes hinzufügen

Optionale Parameter

Slack-Bot-Token

Testing

Redirect testen

Callback testen

Eigene Provider erstellen

1. Provider-Klasse erstellen

2. Im Service-Provider registrieren

3. Konfiguration hinzufügen

4. Wie üblich verwenden

Verwandte Pakete