Socialite - Laravel Bluesky - Knowledge of Laravel

Overzicht

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

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.

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

Installatie en configuratie

Een privésleutel maken

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

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.

BLUESKY_OAUTH_PRIVATE_KEY="..."

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.

Standaard OAuth-scopes

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

Socialite-login — atproto, account:email en include:app.bsky.authViewAll maken gebruikersauthenticatie en toegang tot e-mail mogelijk
Posten — include:app.bsky.authCreatePosts en blob:*/* staan het maken van posts en het uploaden van afbeeldingen en video’s toe
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.

BLUESKY_OAUTH_SCOPE="atproto account:email include:app.bsky.authViewAll"

Zie de AT Protocol Permission Requests-documentatie 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.

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

BLUESKY_REDIRECT=/bluesky/callback

Routeconfiguratie

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

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

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

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.

/** @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.

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

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.

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.

php artisan make:listener OAuthSessionUpdatedListener

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.

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.

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

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

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

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

Source: docs/socialite.md

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter kits

Feeds en RSS

Middleware

Socialite - Laravel Bluesky

Overzicht

Verschillen met gewone OAuth

De authenticatieflow

Installatie en configuratie

Een privésleutel maken

Standaard OAuth-scopes

Lokale ontwikkeling

Productieomgeving

Routeconfiguratie

Callbacks afhandelen bij lokale ontwikkeling

Controller-implementatie

Gebruikersinformatie (OAuthSession)

Databaseconfiguratie

De OAuthSession hergebruiken

Tokens automatisch verversen

De WithBluesky-trait

client-metadata aanpassen

Gedrag bij niet-geauthenticeerde gebruikers

​Overzicht

​Verschillen met gewone OAuth

​De authenticatieflow

​Installatie en configuratie

​Een privésleutel maken

​Standaard OAuth-scopes

​Lokale ontwikkeling

​Productieomgeving

​Routeconfiguratie

​Callbacks afhandelen bij lokale ontwikkeling

​Controller-implementatie

​Gebruikersinformatie (OAuthSession)

​Databaseconfiguratie

​De OAuthSession hergebruiken

​Tokens automatisch verversen

​De WithBluesky-trait

​client-metadata aanpassen

​Gedrag bij niet-geauthenticeerde gebruikers

Overzicht

Verschillen met gewone OAuth

De authenticatieflow

Installatie en configuratie

Een privésleutel maken

Standaard OAuth-scopes

Lokale ontwikkeling

Productieomgeving

Routeconfiguratie

Callbacks afhandelen bij lokale ontwikkeling

Controller-implementatie

Gebruikersinformatie (OAuthSession)

Databaseconfiguratie

De OAuthSession hergebruiken

Tokens automatisch verversen

De WithBluesky-trait

client-metadata aanpassen

Gedrag bij niet-geauthenticeerde gebruikers