> ## 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 (sociale authenticatie)

> Uitleg over hoe je met Laravel Socialite eenvoudig sociale login via OAuth 2.0 implementeert (GitHub, Google, Facebook enz.).

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

### De flow van sociale login

```mermaid theme={null}
sequenceDiagram
    participant User as Gebruiker
    participant App as Laravel-app
    participant OAuth as GitHub (OAuth)
    participant DB as Database

    User->>App: Klikt op de loginknop
    App->>OAuth: Redirect (Socialite::driver('github')->redirect())
    OAuth->>User: Authenticatie- en toestemmingsscherm
    User->>OAuth: Goedkeuring
    OAuth->>App: Callback (met code-parameter)
    App->>OAuth: Access token ophalen
    OAuth-->>App: Gebruikersgegevens teruggeven
    App->>DB: Gebruiker registreren / bijwerken (updateOrCreate)
    DB-->>App: Gebruikersrecord
    App->>User: Ingelogd, redirect naar het dashboard
```

***

## Installatie

Voeg het pakket toe met Composer.

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

<Info>
  Raadpleeg bij een major-versie-upgrade van Socialite altijd de [upgradegids](https://github.com/laravel/socialite/blob/master/UPGRADE.md).
</Info>

***

## Configuratie

### config/services.php

Voeg de client-ID, secret en callback-URL van elke provider toe aan `config/services.php`.

```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>
  Geef je bij de optie `redirect` een relatief pad op, dan wordt dit automatisch omgezet naar een volledige URL.
</Info>

### .env

Beheer de credentials via omgevingsvariabelen. Hier GitHub als voorbeeld.

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

***

## Authenticatieflow

### Routing

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

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

```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>
  Bij gebruik van `updateOrCreate` moet de kolom `github_id` bestaan in de `users`-tabel. Zie het migratievoorbeeld verderop.
</Warning>

***

## Gebruikersgegevens ophalen

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

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

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

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

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

***

## Databasekoppeling

### Migratie

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

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

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

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

In de callbackverwerking geef je de providernaam dynamisch door.

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

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

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

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

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

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

### Optionele parameters

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

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

<Warning>
  Let op dat je via de methode `with()` geen gereserveerde sleutelwoorden zoals `state` of `response_type` doorgeeft.
</Warning>

### Slack-bottokens

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

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

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

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

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

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

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.

<Info>
  Zie ook de [uitleg over de Manager-klasse](/nl/advanced/manager) voor het Manager-patroon en hoe `extend()` werkt.
</Info>

### 1. De providerklasse maken

Erf van `Laravel\Socialite\Two\AbstractProvider` en implementeer de vier abstracte 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
{
    // 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`.

```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. Configuratie toevoegen

```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. Gebruiken zoals gewone Socialite

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

```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>
  Ook het gebruik van third-party pakketten die Socialite op de officiële manier via `extend()` uitbreiden is een aanrader.
</Tip>

***

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

<CardGroup cols={2}>
  <Card title="LINE" icon="comment" href="https://github.com/invokable/laravel-line-sdk">
    LINE SDK voor Laravel. Naast OAuth-login via Socialite ook integratie met de Messaging API.
  </Card>

  <Card title="Bluesky" icon="cloud" href="https://github.com/invokable/laravel-bluesky">
    Integratie met het AT Protocol (Bluesky). Ondersteunt OAuth-authenticatie en het versturen van posts.
  </Card>

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

  <Card title="Threads" icon="instagram" href="https://github.com/invokable/laravel-threads">
    Integratie met Meta Threads. Ondersteunt OAuth-authenticatie en de post-API.
  </Card>

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

  <Card title="Mastodon" icon="mastodon" href="https://github.com/invokable/socialite-mastodon">
    OAuth-login op Mastodon-instances.
  </Card>

  <Card title="WordPress" icon="wordpress" href="https://github.com/invokable/socialite-wordpress">
    OAuth-login op WordPress.com en self-hosted WordPress.
  </Card>
</CardGroup>


## Related topics

- [Socialite for Discord](/nl/packages/socialite-discord.md)
- [Socialite - Laravel Bluesky](/nl/packages/laravel-bluesky/socialite.md)
- [Starter kits](/nl/starter-kits.md)
- [Socialite (LINE Login) - LINE SDK for Laravel](/nl/packages/laravel-line-sdk/socialite.md)
- [OAuth 2.0-authenticatie - Google Sheets API for Laravel](/nl/packages/laravel-google-sheets/oauth.md)