Vergleich der Authentifizierungsmethoden - Laravel Bluesky

Erläutert die Unterschiede zwischen App Password (LegacyAgent) und OAuth (OAuthAgent) in Laravel Bluesky, ihre interne Architektur und Codebeispiele.

​

Überblick

Laravel Bluesky unterstützt zwei Authentifizierungsmethoden. Die API-Aufrufe nach der Authentifizierung sind bei beiden Methoden identisch.

Punkt	App Password	OAuth
Interne Klassen	LegacyAgent / LegacySession	OAuthAgent / OAuthSession
Einstiegspunkt	Bluesky::login()	Bluesky::withToken(OAuthSession)
Privater Schlüssel	Nicht erforderlich	BLUESKY_OAUTH_PRIVATE_KEY erforderlich
Nutzer-Autorisierung	Nicht erforderlich	Erforderlich (Bestätigung im Browser)
Ausführung im Hintergrund	✅ Gut geeignet	✅ Möglich (refresh_token speichern)
Session-Schlüssel	accessJwt / refreshJwt	access_token / refresh_token
Abkündigung geplant	Nein	—
Hauptanwendung	Auto-Posts, Benachrichtigungen, Batch-Verarbeitung	Aktionen im Namen von Nutzern, Socialite-Anbindung

Der Name LegacyAgent bedeutet „Authentifizierungsmethode vor OAuth”, App Password selbst ist jedoch nicht als deprecated markiert. In Szenarien ohne Nutzerinteraktion, wie Benachrichtigungen und automatisierten Posts, ist App Password einfacher und passender.

​

Architektur

BlueskyManager ist die Implementierung hinter der Facade Bluesky. Mit login() oder withToken() konfigurieren Sie den Agent, danach nutzen die API-Aufrufe unabhängig von der Authentifizierungsmethode dieselben Methoden.

​

App Password (LegacyAgent)

​

Authentifizierungsfluss

​

Bluesky::login()

Setzen Sie das App Password in .env und rufen Sie login() auf.

BLUESKY_IDENTIFIER=your-handle.bsky.social
BLUESKY_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx

use Revolution\Bluesky\Facades\Bluesky;

$response = Bluesky::login(
    identifier: config('bluesky.identifier'),
    password: config('bluesky.password'),
)->post('Hello Bluesky');

​

Wiederverwendung der LegacySession

Wenn Sie jedes Mal login() aufrufen, entsteht jedes Mal eine API-Anfrage. Es ist effizienter, die Session zu cachen und wiederzuverwenden.

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Session\LegacySession;

// Erstes Login und Session speichern
Bluesky::login(
    identifier: config('bluesky.identifier'),
    password: config('bluesky.password'),
);
cache()->put('bluesky_session', Bluesky::agent()->session()->toArray(), now()->addDay());

// Beim nächsten Mal aus dem Cache wiederherstellen
$session = LegacySession::create(cache('bluesky_session', []));
Bluesky::withToken($session);

// Access Token bei Ablauf aktualisieren
if (! Bluesky::check()) {
    Bluesky::refreshSession();
}

$response = Bluesky::post('Hello from cached session');

​

Wichtige Schlüssel der LegacySession

Schlüssel	Inhalt	Methode
accessJwt	Access Token	token()
refreshJwt	Refresh Token	refresh()
did	Bluesky-DID	did()
handle	Handle	handle()
email	E-Mail-Adresse	email()
active	Ob das Konto aktiv ist	active()

​

Geeignete Anwendungsfälle

• Auto-Posts in Background-Jobs / Queues
• Benachrichtigungen über einen Laravel-Notification-Kanal
• Batch-Verarbeitung und Scheduling
• Posten unter dem eigenen Konto der Anwendung

​

OAuth (OAuthAgent)

​

Authentifizierungsfluss

​

Bluesky::withToken()

Übergeben Sie die per Socialite erhaltene OAuthSession an withToken().

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Session\OAuthSession;

// Aus Laravel-Session wiederherstellen (Web-Request)
$session = OAuthSession::create(session('bluesky_session'));
$timeline = Bluesky::withToken($session)->getTimeline();

Auch in Background-Jobs oder in der Konsole können Sie die OAuthSession aus in der DB gespeicherten Werten zusammenbauen.

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Session\OAuthSession;

$session = OAuthSession::create([
    'did'           => $user->did,
    'refresh_token' => $user->refresh_token,
    // Für Konten außerhalb von bsky.social auch iss angeben
    // 'iss'        => $user->iss,
]);

$response = Bluesky::withToken($session)
                   ->refreshSession()
                   ->post('Hello from OAuth');

​

Wichtige Schlüssel der OAuthSession

Schlüssel	Inhalt	Methode
access_token	Access Token	token()
refresh_token	Refresh Token (nur einmal verwendbar)	refresh()
did / sub	Bluesky-DID	did()
iss	URL des Authorization Servers	issuer()
profile.handle	Handle	handle()
profile.displayName	Anzeigename	displayName()

Der OAuth-refresh_token kann nur einmal verwendet werden. Aktualisieren Sie mithilfe des Events OAuthSessionUpdated nach jedem Token-Refresh unbedingt die DB. Details siehe Socialite.

​

Geeignete Anwendungsfälle

• Nutzer-Login mittels Socialite
• API-Operationen im Namen des Nutzers
• Wenn Operationen mit unterschiedlichen Konten pro Nutzer erforderlich sind

​

API-Aufrufe nach der Authentifizierung sind gemeinsam

Nach withToken() verwenden Sie unabhängig von der Authentifizierungsmethode dieselben API-Methoden.

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Session\LegacySession;
use Revolution\Bluesky\Session\OAuthSession;

// App Password
Bluesky::login(config('bluesky.identifier'), config('bluesky.password'));

// oder OAuth
$session = OAuthSession::create(session('bluesky_session'));
Bluesky::withToken($session);

// ↓ Die nachfolgenden API-Aufrufe sind vollständig gleich ↓

Bluesky::post('Hello Bluesky');
Bluesky::getTimeline();
Bluesky::getProfile();
Bluesky::searchPosts(q: '#laravel');

BlueskyManager verwendet intern je nach Bedarf LegacyAgent oder OAuthAgent, für den aufrufenden Code macht das keinen Unterschied.

​

Welche Methode wählen?

Situation	Empfehlung
Auto-Posts, Benachrichtigungen, Batch	App Password
Login-Funktion für Nutzer	OAuth
Nur Background-Jobs	App Password
Aktionen im Namen von Nutzern nötig	OAuth
Einfachen Betrieb priorisieren	App Password
Fokus auf Sicherheit und Berechtigungssteuerung	OAuth

Bei Unsicherheit ist die Aufteilung nach Zweck am einfachsten: „Die App agiert selbst” → App Password, „Der Nutzer bedient sie” → OAuth. Beide lassen sich auch kombinieren – ein gängiger Aufbau ist App Password für Benachrichtigungen und OAuth für Nutzer-Login.

​

Weiterführende Links

• Basic client – API-Operationen nach der Authentifizierung
• Socialite – Details zum OAuth-Ablauf
• Notification-Kanal – Benachrichtigungen über App Password / OAuth
• Source: invokable/laravel-bluesky