Confronto tra metodi di autenticazione - Laravel Bluesky

Spiega le differenze tra App Password (LegacyAgent) e OAuth (OAuthAgent) in Laravel Bluesky, l’architettura interna e mostra esempi di codice.

​

Panoramica

Laravel Bluesky supporta due metodi di autenticazione. Dopo l’autenticazione, le chiamate API sono comuni a entrambi i metodi.

Elemento	App Password	OAuth
Classi interne	LegacyAgent / LegacySession	OAuthAgent / OAuthSession
Entry point	Bluesky::login()	Bluesky::withToken(OAuthSession)
Chiave privata	Non necessaria	Serve BLUESKY_OAUTH_PRIVATE_KEY
Azione di autorizzazione dell’utente	Non necessaria	Necessaria (approvazione nel browser)
Esecuzione in background	✅ Ideale	✅ Possibile (salvando refresh_token)
Chiavi di sessione	accessJwt / refreshJwt	access_token / refresh_token
Deprecato	No	—
Usi principali	Post automatici, notifiche, batch processing	Operazioni per conto dell’utente, integrazione Socialite

Il nome LegacyAgent significa “metodo di autenticazione precedente a OAuth”, ma App Password in sé non è deprecato. Per notifiche e post automatici, quando non c’è interazione utente, App Password è più semplice e adatto.

​

Architettura

BlueskyManager è l’implementazione dietro alla Facade Bluesky. Configuri l’agente con login() o withToken() e da quel momento le chiamate API usano gli stessi metodi indipendentemente dal metodo di autenticazione.

​

App Password (LegacyAgent)

​

Flusso di autenticazione

​

Bluesky::login()

Basta impostare l’App Password in .env e chiamare login().

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

​

Riutilizzo di LegacySession

Chiamare login() ogni volta genera una richiesta API a ogni chiamata. Mettere in cache la sessione e riutilizzarla è più efficiente.

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

// Primo login e salvataggio della sessione
Bluesky::login(
    identifier: config('bluesky.identifier'),
    password: config('bluesky.password'),
);
cache()->put('bluesky_session', Bluesky::agent()->session()->toArray(), now()->addDay());

// Nelle esecuzioni successive, ripristina dalla cache
$session = LegacySession::create(cache('bluesky_session', []));
Bluesky::withToken($session);

// Se l'access token è scaduto, aggiornalo
if (! Bluesky::check()) {
    Bluesky::refreshSession();
}

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

​

Chiavi principali di LegacySession

Chiave	Contenuto	Metodo
accessJwt	Access token	token()
refreshJwt	Refresh token	refresh()
did	DID Bluesky	did()
handle	Handle	handle()
email	Indirizzo email	email()
active	Se l’account è attivo	active()

​

Casi d’uso adatti

• Post automatici in background job e job in coda
• Notifiche tramite un canale Laravel Notification
• Batch processing e schedulazione
• Quando si pubblica con l’account dell’applicazione stessa

​

OAuth (OAuthAgent)

​

Flusso di autenticazione

​

Bluesky::withToken()

Passa a withToken() la OAuthSession ottenuta tramite Socialite.

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

// Ripristino dalla sessione Laravel (richiesta web)
$session = OAuthSession::create(session('bluesky_session'));
$timeline = Bluesky::withToken($session)->getTimeline();

Anche in background job e da Console puoi ricostruire una OAuthSession a partire dai valori salvati in DB.

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

$session = OAuthSession::create([
    'did'           => $user->did,
    'refresh_token' => $user->refresh_token,
    // Per gli account non su bsky.social, specifica anche iss
    // 'iss'        => $user->iss,
]);

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

​

Chiavi principali di OAuthSession

Chiave	Contenuto	Metodo
access_token	Access token	token()
refresh_token	Refresh token (utilizzabile una sola volta)	refresh()
did / sub	DID Bluesky	did()
iss	URL del server di autorizzazione	issuer()
profile.handle	Handle	handle()
profile.displayName	Nome visualizzato	displayName()

Il refresh_token OAuth può essere usato una sola volta. Usa l’evento OAuthSessionUpdated e assicurati di aggiornare il DB dopo ogni refresh del token. Per i dettagli consulta Socialite.

​

Casi d’uso adatti

• Login utente con Socialite
• Chiamate API per conto dell’utente
• Quando è necessario operare con account diversi a seconda dell’utente

​

Le chiamate API dopo l’autenticazione sono comuni

Con entrambi i metodi di autenticazione, dopo withToken() si usano gli stessi metodi API.

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

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

// ↓ Da qui in poi le chiamate API sono completamente comuni ↓

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

BlueskyManager internamente sceglie tra LegacyAgent o OAuthAgent, ma il codice chiamante non ne risente.

​

Quale scegliere

Situazione	Consigliato
Post automatici, notifiche, batch	App Password
Funzione di login utente	OAuth
Solo background job	App Password
Serve operare per conto dell’utente	OAuth
Priorità alla semplicità operativa	App Password
Priorità a sicurezza e controllo dei permessi	OAuth

Se sei indeciso, il criterio più semplice è dividere in base all’obiettivo. Se “è l’app che agisce da sola” → App Password; se “è l’utente che opera” → OAuth. È anche possibile combinare i due: ad esempio usare App Password per le notifiche e OAuth per il login utente è una configurazione molto comune.

​

Link di riferimento

• Basic client — operazioni API dopo l’autenticazione
• Socialite — dettagli sul flusso OAuth
• Canale di notifica — notifiche con App Password / OAuth
• Source: invokable/laravel-bluesky