> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```mermaid theme={null}
sequenceDiagram
    participant User as Benutzer
    participant App as Laravel-App
    participant OAuth as GitHub (OAuth)
    participant DB as Datenbank

    User->>App: Klick auf Login-Button
    App->>OAuth: Redirect (Socialite::driver('github')->redirect())
    OAuth->>User: Anmelde- und Berechtigungsdialog
    User->>OAuth: Zustimmen
    OAuth->>App: Callback (mit code-Parameter)
    App->>OAuth: Access Token anfordern
    OAuth-->>App: Benutzerinformationen zurückgeben
    App->>DB: Benutzer anlegen / aktualisieren (updateOrCreate)
    DB-->>App: Benutzerdatensatz
    App->>User: Login abgeschlossen, Weiterleitung zum Dashboard
```

***

## Installation

Fügen Sie das Paket mit Composer hinzu:

```shell theme={null}
composer require laravel/socialite
```

<Info>
  Prüfen Sie beim Upgrade auf eine neue Major-Version von Socialite stets den [Upgrade Guide](https://github.com/laravel/socialite/blob/master/UPGRADE.md).
</Info>

***

## Konfiguration

### config/services.php

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

```php theme={null}
// 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'),
],
```

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

### .env

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

```ini theme={null}
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](https://github.com/settings/developers) 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.

```php theme={null}
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.

```php theme={null}
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');
});
```

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

***

## Benutzerinformationen abrufen

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

```php theme={null}
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()`:

```php theme={null}
$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:

```php theme={null}
return Socialite::driver('google')->stateless()->user();
```

***

## Datenbank-Anbindung

### Migration

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

```php theme={null}
// 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.

```php theme={null}
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:

```php theme={null}
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.

```php theme={null}
$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:

```php theme={null}
return Socialite::driver('github')
    ->scopes(['read:user', 'public_repo'])
    ->redirect();
```

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

```php theme={null}
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:

```php theme={null}
// 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();
```

<Warning>
  Übergeben Sie an `with()` keine reservierten Schlüssel wie `state` oder `response_type`.
</Warning>

### Slack-Bot-Token

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

```php theme={null}
// 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

```php theme={null}
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.

```php theme={null}
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' => 'jane@example.com',
    ]));

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

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

    $this->assertDatabaseHas('users', [
        'name' => 'Jane Doe',
        'email' => 'jane@example.com',
        '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:

```php theme={null}
$fakeUser = User::fake([
    'id' => 'github-123',
    'name' => 'Jane Doe',
    'email' => 'jane@example.com',
    '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.

<Info>
  Näheres zum Manager-Pattern und zum Mechanismus von `extend()` finden Sie unter [Erläuterung der Manager-Klasse](/de/advanced/manager).
</Info>

### 1. Provider-Klasse erstellen

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

```php theme={null}
// 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()`.

```php theme={null}
// 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

```php theme={null}
// 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.

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

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

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

***

## 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.

<CardGroup cols={2}>
  <Card title="LINE" icon="comment" href="https://github.com/invokable/laravel-line-sdk">
    LINE SDK für Laravel. Neben dem OAuth-Login über Socialite ist auch die Messaging API integriert.
  </Card>

  <Card title="Bluesky" icon="cloud" href="https://github.com/invokable/laravel-bluesky">
    Anbindung an das AT Protocol (Bluesky). Unterstützt OAuth-Authentifizierung und das Absetzen von Posts.
  </Card>

  <Card title="Discord" icon="discord" href="https://github.com/invokable/socialite-discord">
    OAuth2-Login mit Discord.
  </Card>

  <Card title="Threads" icon="instagram" href="https://github.com/invokable/laravel-threads">
    Anbindung an Meta Threads. Unterstützt OAuth-Authentifizierung und die Posting-API.
  </Card>

  <Card title="Amazon" icon="amazon" href="https://github.com/invokable/socialite-amazon">
    OAuth-Login über Login with Amazon.
  </Card>

  <Card title="Mastodon" icon="mastodon" href="https://github.com/invokable/socialite-mastodon">
    OAuth-Login gegen Mastodon-Instanzen.
  </Card>

  <Card title="WordPress" icon="wordpress" href="https://github.com/invokable/socialite-wordpress">
    OAuth-Login für WordPress.com und selbst gehostete WordPress-Instanzen.
  </Card>
</CardGroup>


## Related topics

- [Socialite - Laravel Bluesky](/de/packages/laravel-bluesky/socialite.md)
- [Socialite für Discord](/de/packages/socialite-discord.md)
- [Socialite (LINE Login) - LINE SDK für Laravel](/de/packages/laravel-line-sdk/socialite.md)
- [Laravel Fortify und Starter-Kits](/de/advanced/fortify.md)
- [Bot-Tutorial - Laravel Bluesky](/de/packages/laravel-bluesky/bot-tutorial.md)