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

# Socialite - Laravel Bluesky

> OAuth-authenticatie voor Laravel Bluesky. Configuratie en gebruik van Socialite met de AT Protocol-specifieke DPoP- en PAR-endpoints.

## Overzicht

OAuth bij Bluesky is gebaseerd op het AT Protocol en verschilt sterk van gewone Socialite-providers zoals GitHub en Google.

<Warning>
  De OAuth van Bluesky is fundamenteel anders geïmplementeerd dan andere Socialite-providers. Er wordt gebruikgemaakt van DPoP (Demonstrated Proof of Possession) en PAR (Pushed Authorization Requests)-endpoints. Een `client_secret` is niet nodig; in plaats daarvan gebruik je een privésleutel.
</Warning>

### Verschillen met gewone OAuth

| Onderdeel            | Gewone Socialite              | Bluesky Socialite                             |
| -------------------- | ----------------------------- | --------------------------------------------- |
| Authenticatiemethode | OAuth 2.0                     | AT Protocol OAuth (DPoP)                      |
| Clientidentificatie  | `client_id` + `client_secret` | Privésleutel + URL van `client-metadata.json` |
| `client_id`          | Geregistreerde vaste string   | De URL van `client-metadata.json`             |
| Gebruikersidentifier | E-mailadres e.d.              | DID (`did:plc:...`) of handle                 |
| Login hint           | Niet nodig                    | Je kunt een handle / DID / PDS-URL doorgeven  |

### De authenticatieflow

```mermaid theme={null}
sequenceDiagram
    participant User as Gebruiker
    participant App as Laravel<br>app
    participant Bluesky as Bluesky<br>server

    User->>App: Loginformulier versturen (handle invoeren)
    App->>Bluesky: PAR-request (inclusief login_hint)
    Bluesky-->>App: request_uri
    App->>Bluesky: Redirect naar het autorisatie-endpoint
    User->>Bluesky: Login goedkeuren op Bluesky
    Bluesky-->>App: Callback (code + iss)
    App->>Bluesky: Tokenuitwisseling met DPoP
    Bluesky-->>App: Accesstoken + OAuthSession
    App->>User: Login voltooid
```

## Installatie en configuratie

### Een privésleutel maken

Genereer eerst een privésleutel. Dit kan zonder registratie bij Bluesky.

```bash theme={null}
php artisan bluesky:new-private-key
```

```
Please set this private key in .env

BLUESKY_OAUTH_PRIVATE_KEY="...url-safe base64 encoded key..."
```

Kopieer de uitgevoerde waarde naar `.env`.

```dotenv theme={null}
BLUESKY_OAUTH_PRIVATE_KEY="..."
```

<Info>
  Bij Bluesky is het registreren van een `client_id` of `client_secret` niet nodig. Alleen het instellen van de privésleutel is genoeg om OAuth-authenticatie te gebruiken.
</Info>

### Standaard OAuth-scopes

Het pakket is geconfigureerd met standaard OAuth-scopes die drie belangrijke use-cases ondersteunen.

1. **Socialite-login** — `atproto`, `account:email` en `include:app.bsky.authViewAll` maken gebruikersauthenticatie en toegang tot e-mail mogelijk
2. **Posten** — `include:app.bsky.authCreatePosts` en `blob:*/*` staan het maken van posts en het uploaden van afbeeldingen en video's toe
3. **DM-notificaties** — `rpc:chat.bsky.convo.sendMessage` en `rpc:chat.bsky.convo.getConvoForMembers` maken het versturen van directe berichten voor notificaties mogelijk

Je kunt de scopes aanpassen door de omgevingsvariabele `BLUESKY_OAUTH_SCOPE` in te stellen.

```dotenv theme={null}
BLUESKY_OAUTH_SCOPE="atproto account:email include:app.bsky.authViewAll"
```

Zie de [AT Protocol Permission Requests-documentatie](https://atproto.com/guides/permission-requests) voor details over de beschikbare scopes.

### Lokale ontwikkeling

Standaard zijn `http://localhost` en `http://127.0.0.1:8000/` geconfigureerd, dus voor lokale ontwikkeling is geen extra configuratie nodig.

```dotenv theme={null}
# Alleen instellen als je de poort hebt gewijzigd
BLUESKY_CLIENT_ID=
BLUESKY_REDIRECT=http://127.0.0.1:8080/
```

### Productieomgeving

Als de routenaam `bluesky.oauth.redirect` bestaat, is configuratie in `.env` niet nodig. Stel deze in als je de standaardroutenaam hebt gewijzigd.

```dotenv theme={null}
BLUESKY_REDIRECT=/bluesky/callback
```

## Routeconfiguratie

Als routenaam voor de callbackroute wordt `bluesky.oauth.redirect` aanbevolen. Het pakket gebruikt deze naam intern.

```php theme={null}
// routes/web.php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\SocialiteController;

Route::get('login', [SocialiteController::class, 'login'])->name('login');
Route::match(['get', 'post'], 'redirect', [SocialiteController::class, 'redirect']);
Route::get('bluesky/callback', [SocialiteController::class, 'callback'])
     ->name('bluesky.oauth.redirect');
```

### Callbacks afhandelen bij lokale ontwikkeling

Tijdens lokale ontwikkeling staat de callback-URL van Bluesky vast op `http://127.0.0.1:8000/`. Het is handig om dit op routeniveau door te sturen.

```php theme={null}
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::get('/', function (Request $request) {
    if (app()->isLocal() && $request->has('iss')) {
        return to_route('bluesky.oauth.redirect', $request->query());
    }

    // ...
});
```

## Controller-implementatie

```php theme={null}
<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Laravel\Socialite\Facades\Socialite;
use Revolution\Bluesky\Session\OAuthSession;

class SocialiteController extends Controller
{
    public function login(Request $request)
    {
        // Formulierpagina om de login hint in te voeren
        return view('login');
    }

    public function redirect(Request $request)
    {
        // Je kunt een handle, DID of PDS-URL doorgeven als login_hint (optioneel)
        $hint = $request->input('login_hint');
        $request->session()->put('hint', $hint);

        return Socialite::driver('bluesky')
                        ->hint($hint)
                        ->redirect();
    }

    public function callback(Request $request)
    {
        if ($request->missing('code')) {
            // Voor debuggen tijdens ontwikkeling. Vervang dit in productie door correcte foutafhandeling
            dd($request);
        }

        $hint = $request->session()->pull('hint');

        /** @var \Laravel\Socialite\Two\User $user */
        $user = Socialite::driver('bluesky')
                         ->hint($hint)
                         ->user();

        /** @var OAuthSession $session */
        $session = $user->session;

        // De OAuthSession opslaan in de Laravel-sessie
        $request->session()->put('bluesky_session', $session->toArray());

        $loginUser = User::updateOrCreate([
            'did' => $session->did(),
        ], [
            'iss'           => $session->issuer(),
            'handle'        => $session->handle(),
            'name'          => $session->displayName(),
            'avatar'        => $session->avatar(),
            'access_token'  => $session->token(),
            'refresh_token' => $session->refresh(),
        ]);

        auth()->login($loginUser, true);

        return to_route('bluesky.dashboard');
    }
}
```

## Gebruikersinformatie (OAuthSession)

De belangrijkste methods van de `OAuthSession` die je via `$user->session` krijgt.

| Method          | Beschrijving   | Voorbeeld             |
| --------------- | -------------- | --------------------- |
| `did()`         | Bluesky-DID    | `did:plc:xxxxxx`      |
| `handle()`      | Bluesky-handle | `alice.bsky.social`   |
| `displayName()` | Weergavenaam   | `Alice`               |
| `avatar()`      | Avatar-URL     | `https://...`         |
| `issuer()`      | URL van de PDS | `https://bsky.social` |
| `token()`       | Accesstoken    |                       |
| `refresh()`     | Refresh-token  |                       |

Gebruik `toArray()` om alle properties te bekijken.

```php theme={null}
/** @var OAuthSession $session */
dump($session->toArray());
```

## Databaseconfiguratie

Voeg Bluesky-specifieke kolommen toe aan de `users`-tabel. De DID is de unieke identifier van een Bluesky-gebruiker.

```php theme={null}
// database/migrations/xxxx_add_bluesky_columns_to_users_table.php

Schema::table('users', function (Blueprint $table) {
    $table->string('did')->nullable()->unique();
    $table->string('iss')->nullable();
    $table->string('handle')->nullable();
    $table->string('avatar')->nullable();
    $table->text('access_token')->nullable();
    $table->text('refresh_token')->nullable();
});
```

## De OAuthSession hergebruiken

Je kunt de API aanroepen met een OAuthSession die je in de sessie hebt opgeslagen.

```php theme={null}
use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Session\OAuthSession;

$session = OAuthSession::create(session('bluesky_session'));

$timeline = Bluesky::withToken($session)->getTimeline();
```

In jobs, de console en andere plekken waar de Laravel-sessie niet beschikbaar is, bouw je de OAuthSession op met data uit de database.

```php theme={null}
use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Session\OAuthSession;

$session = OAuthSession::create([
    'did'           => $user->did,
    'refresh_token' => $user->refresh_token,
    // Geef voor accounts buiten bsky.social ook iss op
    // 'iss'        => $user->iss,
]);

$timeline = Bluesky::withToken($session)
                   ->refreshSession()
                   ->getTimeline();
```

## Tokens automatisch verversen

Omdat een refresh-token maar één keer bruikbaar is, moet je het na het verversen altijd opnieuw in de database opslaan. Gebruik hiervoor het `OAuthSessionUpdated`-event.

```bash theme={null}
php artisan make:listener OAuthSessionUpdatedListener
```

```php theme={null}
namespace App\Listeners;

use App\Models\User;
use Revolution\Bluesky\Events\OAuthSessionUpdated;

class OAuthSessionUpdatedListener
{
    public function handle(OAuthSessionUpdated $event): void
    {
        if (empty($event->session->did())) {
            return;
        }

        session()->put('bluesky_session', $event->session->toArray());

        User::firstWhere('did', $event->session->did())
            ->fill([
                'iss'           => $event->session->issuer(),
                'handle'        => $event->session->handle(),
                'name'          => $event->session->displayName(),
                'avatar'        => $event->session->avatar(),
                'access_token'  => $event->session->token(),
                'refresh_token' => $event->session->refresh(),
            ])->save();
    }
}
```

Bij het starten van een refresh wordt ook het `OAuthSessionRefreshing`-event uitgestuurd. Op dat moment wordt het `refresh_token` ongeldig, dus het is veilig om het uit de database te verwijderen.

```php theme={null}
use Revolution\Bluesky\Events\OAuthSessionRefreshing;

public function handle(OAuthSessionRefreshing $event): void
{
    if (empty($event->session->did())) {
        return;
    }

    User::firstWhere('did', $event->session->did())
        ->fill(['refresh_token' => ''])
        ->save();
}
```

## De WithBluesky-trait

Voeg de `WithBluesky`-trait toe aan het User-model en implementeer `tokenForBluesky()`; daarna krijg je met `$user->bluesky()` een geauthenticeerde client.

```php theme={null}
namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Revolution\Bluesky\Session\OAuthSession;
use Revolution\Bluesky\Traits\WithBluesky;

class User extends Authenticatable
{
    use WithBluesky;

    protected function tokenForBluesky(): OAuthSession
    {
        return OAuthSession::create([
            'did'           => $this->did,
            'refresh_token' => $this->refresh_token,
            'iss'           => $this->iss,
        ]);
    }
}
```

```php theme={null}
$profile = auth()->user()
                 ->bluesky()
                 ->refreshSession()
                 ->getProfile();
```

## client-metadata aanpassen

Het pakket definieert automatisch de routes `bluesky.oauth.client-metadata` en `bluesky.oauth.jwks`. Normaal hoef je niets te wijzigen, maar je kunt aanpassingen doen met `OAuthConfig`.

```php theme={null}
// AppServiceProvider

use Revolution\Bluesky\Socialite\OAuthConfig;

public function boot(): void
{
    OAuthConfig::clientMetadataUsing(function () {
        return collect(config('bluesky.oauth.metadata'))
            ->merge([
                'client_id'    => route('bluesky.oauth.client-metadata'),
                'jwks_uri'     => route('bluesky.oauth.jwks'),
                'redirect_uris' => [url('bluesky/callback')],
            ])
            ->reject(fn ($item) => is_null($item))
            ->toArray();
    });
}
```

## Gedrag bij niet-geauthenticeerde gebruikers

Als de `OAuthSession` null is of er geen refresh-token is, wordt een `Unauthenticated`-exception gegooid en word je doorgestuurd naar de `login`-route.

```php theme={null}
// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->redirectGuestsTo('/bluesky/login');
})
```

<Info>
  Source: [docs/socialite.md](https://github.com/invokable/laravel-bluesky/blob/main/docs/socialite.md)
</Info>


## Related topics

- [Laravel Bluesky](/nl/packages/laravel-bluesky/index.md)
- [Bottutorial - Laravel Bluesky](/nl/packages/laravel-bluesky/bot-tutorial.md)
- [Laravel Socialite (sociale authenticatie)](/nl/socialite.md)
- [Basic client - Laravel Bluesky](/nl/packages/laravel-bluesky/basic-client.md)
- [Vergelijking van authenticatiemethodes - Laravel Bluesky](/nl/packages/laravel-bluesky/authentication.md)