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

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

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

## Architettura

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

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

    App->>Bluesky: createSession(identifier, password)
    Bluesky-->>App: LegacySession (accessJwt + refreshJwt)
    App->>App: LegacyAgent::create(session)
    App->>Bluesky: Chiamata API (Bearer accessJwt)
    Bluesky-->>App: Risposta
    Note over App: Se accessJwt è scaduto
    App->>Bluesky: refreshSession (refreshJwt)
    Bluesky-->>App: Nuovi accessJwt + refreshJwt
```

### Bluesky::login()

Basta impostare l'App Password in `.env` e chiamare `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');
```

### Riutilizzo di LegacySession

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

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

```mermaid theme={null}
sequenceDiagram
    participant User as Utente
    participant App as App Laravel
    participant Bluesky as Server Bluesky

    User->>App: Invia form di login (inserisce l'handle)
    App->>Bluesky: Richiesta PAR (include login_hint)
    Bluesky-->>App: request_uri
    App->>Bluesky: Redirect all'endpoint di autorizzazione
    User->>Bluesky: Approva il login su Bluesky
    Bluesky-->>App: Callback (code + iss)
    App->>Bluesky: Scambio del token usando DPoP
    Bluesky-->>App: OAuthSession (access_token + refresh_token)
    App->>User: Login completato
    App->>Bluesky: Chiamata API (DPoP access_token)
    Bluesky-->>App: Risposta
```

### Bluesky::withToken()

Passa a `withToken()` la `OAuthSession` ottenuta tramite Socialite.

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

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

<Warning>
  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](/it/packages/laravel-bluesky/socialite).
</Warning>

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

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

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

```mermaid theme={null}
flowchart TD
    A["Quale metodo di autenticazione usare?"] --> B{"L'utente deve accedere<br>con un account Bluesky?"}
    B -->|"Sì"| C["OAuth (OAuthAgent)<br>Integrazione con Socialite"]
    B -->|"No"| D{"Operi con l'account<br>dell'applicazione stessa?"}
    D -->|"Sì"| E["App Password (LegacyAgent)<br>Semplice e facile da gestire"]
    D -->|"Operazioni per più utenti"| C
```

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

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

## Link di riferimento

* [Basic client](/it/packages/laravel-bluesky/basic-client) — operazioni API dopo l'autenticazione
* [Socialite](/it/packages/laravel-bluesky/socialite) — dettagli sul flusso OAuth
* [Canale di notifica](/it/packages/laravel-bluesky/notification) — notifiche con App Password / OAuth
* Source: [invokable/laravel-bluesky](https://github.com/invokable/laravel-bluesky)


## Related topics

- [BlueskyManager e HasShortHand](/it/packages/laravel-bluesky/bluesky-manager.md)
- [Laravel Sentinel — indagine sul middleware di protezione delle rotte](/it/blog/sentinel-introduction.md)
- [Trait ForwardsCalls](/it/advanced/forwards-calls.md)
- [Implementare un guard di autenticazione personalizzato](/it/advanced/custom-auth-guard.md)
- [Frontend](/it/frontend.md)