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