Comparaison des méthodes d'authentification - Laravel Bluesky

Différences, architecture interne et exemples de code entre App Password (LegacyAgent) et OAuth (OAuthAgent) dans Laravel Bluesky.

​

Vue d’ensemble

Laravel Bluesky prend en charge deux méthodes d’authentification. Après authentification, les appels d’API sont identiques dans les deux cas.

Élément	App Password	OAuth
Classes internes	LegacyAgent / LegacySession	OAuthAgent / OAuthSession
Point d’entrée	Bluesky::login()	Bluesky::withToken(OAuthSession)
Clé privée	Non requise	BLUESKY_OAUTH_PRIVATE_KEY obligatoire
Action d’autorisation de l’utilisateur	Non requise	Requise (validation dans le navigateur)
Exécution en arrière-plan	✅ Recommandée	✅ Possible (stockage du refresh_token)
Clés de session	accessJwt / refreshJwt	access_token / refresh_token
Dépréciation prévue	Aucune	—
Usages typiques	Publications automatiques, notifications, traitements batch	Actions au nom de l’utilisateur, intégration Socialite

Le nom LegacyAgent désigne « la méthode d’authentification antérieure à OAuth », mais App Password lui-même n’est pas voué à disparaître. Pour les notifications ou les publications automatiques, sans intervention utilisateur, App Password est plus simple et mieux adapté.

​

Architecture

BlueskyManager est l’implémentation réelle derrière la facade Bluesky. Après avoir configuré l’agent avec login() ou withToken(), les appels d’API utilisent les mêmes méthodes, quelle que soit la méthode d’authentification.

​

App Password (LegacyAgent)

​

Flux d’authentification

​

Bluesky::login()

Il suffit de configurer un App Password dans .env et d’appeler 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');

​

Réutilisation d’une LegacySession

Appeler login() à chaque fois génère une requête API à chaque appel. Il est plus efficace de mettre la session en cache et de la réutiliser.

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

// Première connexion : sauvegarder la session
Bluesky::login(
    identifier: config('bluesky.identifier'),
    password: config('bluesky.password'),
);
cache()->put('bluesky_session', Bluesky::agent()->session()->toArray(), now()->addDay());

// Les fois suivantes, restaurer depuis le cache
$session = LegacySession::create(cache('bluesky_session', []));
Bluesky::withToken($session);

// Renouveler l'access token s'il est expiré
if (! Bluesky::check()) {
    Bluesky::refreshSession();
}

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

​

Principales clés de LegacySession

Clé	Contenu	Méthode
accessJwt	Access token	token()
refreshJwt	Refresh token	refresh()
did	DID Bluesky	did()
handle	Handle	handle()
email	Adresse e-mail	email()
active	Compte actif ou non	active()

​

Cas d’usage adaptés

• Publication automatique via jobs en arrière-plan / files d’attente
• Notifications via un canal Laravel Notification
• Traitements batch, tâches planifiées
• Publication sous le compte de l’application elle-même

​

OAuth (OAuthAgent)

​

Flux d’authentification

​

Bluesky::withToken()

Passez à withToken() l’OAuthSession obtenue via Socialite.

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

// Restauration depuis la session Laravel (requête web)
$session = OAuthSession::create(session('bluesky_session'));
$timeline = Bluesky::withToken($session)->getTimeline();

Dans les jobs en arrière-plan ou en console, l’OAuthSession peut être reconstituée à partir des valeurs stockées en base.

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

$session = OAuthSession::create([
    'did'           => $user->did,
    'refresh_token' => $user->refresh_token,
    // Pour les comptes hors bsky.social, précisez aussi iss
    // 'iss'        => $user->iss,
]);

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

​

Principales clés de OAuthSession

Clé	Contenu	Méthode
access_token	Access token	token()
refresh_token	Refresh token (usage unique)	refresh()
did / sub	DID Bluesky	did()
iss	URL du serveur d’autorisation	issuer()
profile.handle	Handle	handle()
profile.displayName	Nom d’affichage	displayName()

Le refresh_token OAuth n’est utilisable qu’une seule fois. Utilisez l’événement OAuthSessionUpdated et mettez impérativement la base à jour après chaque renouvellement de token. Voir Socialite pour plus de détails.

​

Cas d’usage adaptés

• Connexion utilisateur via Socialite
• Appels d’API au nom de l’utilisateur
• Opérations nécessitant un compte différent par utilisateur

​

Les appels d’API après authentification sont communs

Quelle que soit la méthode d’authentification, une fois withToken() appelé, vous utilisez les mêmes méthodes d’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'));

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

// ↓ Les appels d'API qui suivent sont totalement identiques ↓

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

BlueskyManager sélectionne en interne LegacyAgent ou OAuthAgent, mais cela n’a aucun impact sur le code appelant.

​

Quelle méthode choisir ?

Situation	Recommandation
Publication automatique, notifications, batch	App Password
Fonction de connexion utilisateur	OAuth
Uniquement des jobs en arrière-plan	App Password
Actions au nom de l’utilisateur nécessaires	OAuth
Priorité à la simplicité d’exploitation	App Password
Priorité à la sécurité et au contrôle des permissions	OAuth

En cas de doute, le plus simple est de raisonner par objectif. Si « l’application agit seule », choisissez App Password ; si « l’utilisateur effectue une action », choisissez OAuth. Les deux peuvent être combinés : utiliser App Password pour les notifications et OAuth pour la connexion utilisateur est une configuration courante.

​

Liens utiles

• Basic client — Opérations API après authentification
• Socialite — Détails du flux OAuth
• Canal de notification — Notifications avec App Password / OAuth
• Source : invokable/laravel-bluesky