> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

## Architecture

```mermaid theme={null}
classDiagram
    class BlueskyManager {
        +login(identifier, password) Factory
        +withToken(session) Factory
        +agent() Agent
        +check() bool
        +refreshSession() Factory
    }
    class LegacyAgent {
        +session LegacySession
        +http() PendingRequest
        +refreshSession() self
    }
    class OAuthAgent {
        +session OAuthSession
        +http() PendingRequest
        +refreshSession() self
    }
    class LegacySession {
        +accessJwt
        +refreshJwt
        +did
        +handle
        +token() string
        +refresh() string
    }
    class OAuthSession {
        +access_token
        +refresh_token
        +did
        +iss
        +token() string
        +refresh() string
        +issuer() string
    }

    BlueskyManager --> LegacyAgent : login()
    BlueskyManager --> OAuthAgent : withToken(OAuthSession)
    BlueskyManager --> LegacyAgent : withToken(LegacySession)
    LegacyAgent --> LegacySession : holds
    OAuthAgent --> OAuthSession : holds
```

`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

```mermaid theme={null}
sequenceDiagram
    participant App as Application Laravel
    participant Bluesky as Serveur Bluesky

    App->>Bluesky: createSession(identifier, password)
    Bluesky-->>App: LegacySession (accessJwt + refreshJwt)
    App->>App: LegacyAgent::create(session)
    App->>Bluesky: Appel API (Bearer accessJwt)
    Bluesky-->>App: Réponse
    Note over App: Lorsque accessJwt est expiré
    App->>Bluesky: refreshSession (refreshJwt)
    Bluesky-->>App: Nouveaux accessJwt + refreshJwt
```

### Bluesky::login()

Il suffit de configurer un App Password dans `.env` et d'appeler `login()`.

```dotenv theme={null}
BLUESKY_IDENTIFIER=your-handle.bsky.social
BLUESKY_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx
```

```php theme={null}
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.

```php theme={null}
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

```mermaid theme={null}
sequenceDiagram
    participant User as Utilisateur
    participant App as Application Laravel
    participant Bluesky as Serveur Bluesky

    User->>App: Envoi du formulaire de connexion (saisie du handle)
    App->>Bluesky: Requête PAR (avec login_hint)
    Bluesky-->>App: request_uri
    App->>Bluesky: Redirection vers l'endpoint d'autorisation
    User->>Bluesky: Autorisation dans Bluesky
    Bluesky-->>App: Callback (code + iss)
    App->>Bluesky: Échange de tokens avec DPoP
    Bluesky-->>App: OAuthSession (access_token + refresh_token)
    App->>User: Connexion terminée
    App->>Bluesky: Appel API (DPoP access_token)
    Bluesky-->>App: Réponse
```

### Bluesky::withToken()

Passez à `withToken()` l'`OAuthSession` obtenue via Socialite.

```php theme={null}
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.

```php theme={null}
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()` |

<Warning>
  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](/fr/packages/laravel-bluesky/socialite) pour plus de détails.
</Warning>

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

```php theme={null}
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 ?

```mermaid theme={null}
flowchart TD
    A["Quelle méthode d'authentification utiliser ?"] --> B{"L'utilisateur doit-il<br>se connecter avec son compte Bluesky ?"}
    B -->|"Oui"| C["OAuth (OAuthAgent)<br>Intégration Socialite"]
    B -->|"Non"| D{"L'application opère-t-elle<br>avec son propre compte ?"}
    D -->|"Oui"| E["App Password (LegacyAgent)<br>Simple et facile à exploiter"]
    D -->|"Actions au nom de plusieurs utilisateurs"| C
```

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

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

## Liens utiles

* [Basic client](/fr/packages/laravel-bluesky/basic-client) — Opérations API après authentification
* [Socialite](/fr/packages/laravel-bluesky/socialite) — Détails du flux OAuth
* [Canal de notification](/fr/packages/laravel-bluesky/notification) — Notifications avec App Password / OAuth
* Source : [invokable/laravel-bluesky](https://github.com/invokable/laravel-bluesky)


## Related topics

- [BlueskyManager et HasShortHand](/fr/packages/laravel-bluesky/bluesky-manager.md)
- [Laravel Sentinel — analyse du middleware de protection des routes](/fr/blog/sentinel-introduction.md)
- [Canal de notification - Laravel Bluesky](/fr/packages/laravel-bluesky/notification.md)
- [Laravel Socialite (authentification sociale)](/fr/socialite.md)
- [Client de base - Laravel Bluesky](/fr/packages/laravel-bluesky/basic-client.md)