Socialite

• Introduzione
• Installazione
• Aggiornare Socialite
• Configurazione
• Autenticazione
• Recupero dei Dettagli Utente

Introduzione

Oltre all’autenticazione tipica basata su form, Laravel offre anche un modo semplice e comodo per autenticarsi con provider OAuth usando Laravel Socialite. Attualmente, Socialite supporta l’autenticazione tramite Facebook, X, LinkedIn, Google, GitHub, GitLab, Bitbucket e Slack.

Sono disponibili adattatori per altre piattaforme tramite il sito web Socialite Providers gestito dalla community.

Installazione

Per iniziare con Socialite, usa il gestore di pacchetti Composer per aggiungere il pacchetto alle dipendenze del tuo progetto:

composer require laravel/socialite

Aggiornare Socialite

Quando aggiorni a una nuova versione principale di Socialite, è importante che tu riveda attentamente la guida all’aggiornamento.

Configurazione

Prima di utilizzare Socialite, devi aggiungere le credenziali per i provider OAuth che la tua applicazione utilizza. Di solito, queste credenziali possono essere ottenute creando un "developer application" nel dashboard del servizio con cui effettuerai l’autenticazione.

Queste credenziali dovrebbero essere inserite nel file di configurazione config/services.php della tua applicazione e dovrebbero usare la chiave facebook, x, linkedin-openid, google, github, gitlab, bitbucket, slack, o slack-openid, a seconda dei provider richiesti dalla tua applicazione:

    'github' => [
        'client_id' => env('GITHUB_CLIENT_ID'),
        'client_secret' => env('GITHUB_CLIENT_SECRET'),
        'redirect' => 'http://example.com/callback-url',
    ],

Se l’opzione redirect contiene un percorso relativo, verrà automaticamente risolta in un URL completamente qualificato.

Autenticazione

Routing

Per autenticare gli utenti utilizzando un provider OAuth, avrai bisogno di due route: una per reindirizzare l’utente al provider OAuth e un’altra per ricevere il callback dal provider dopo l’autenticazione. Le route di esempio di seguito mostrano come implementare entrambe le route:

use Laravel\Socialite\Facades\Socialite;

Route::get('/auth/redirect', function () {
    return Socialite::driver('github')->redirect();
});

Route::get('/auth/callback', function () {
    $user = Socialite::driver('github')->user();

    // $user->token
});

Il metodo redirect fornito dalla facade Socialite si occupa di reindirizzare l’utente al provider OAuth, mentre il metodo user esamina la richiesta in arrivo e recupera le informazioni dell’utente dal provider dopo che ha approvato la richiesta di autenticazione.

Autenticazione e Archiviazione

Una volta ottenuto l’utente dal provider OAuth, puoi verificare se l’utente esiste nel database della tua applicazione e autenticare l’utente. Se l’utente non esiste nel database della tua applicazione, solitamente creerai un nuovo record nel database per rappresentarlo:

use App\Models\User;
use Illuminate\Support\Facades\Auth;
use Laravel\Socialite\Facades\Socialite;

Route::get('/auth/callback', function () {
    $githubUser = Socialite::driver('github')->user();

    $user = User::updateOrCreate([
        'github_id' => $githubUser->id,
    ], [
        'name' => $githubUser->name,
        'email' => $githubUser->email,
        'github_token' => $githubUser->token,
        'github_refresh_token' => $githubUser->refreshToken,
    ]);

    Auth::login($user);

    return redirect('/dashboard');
});

Per ulteriori informazioni su quali informazioni dell’utente sono disponibili dai specifici provider OAuth, consulta la documentazione su recuperare i dettagli dell’utente.

Access Scope

Prima di reindirizzare l’utente, puoi usare il metodo scopes per specificare gli "scopes" che devono essere inclusi nella richiesta di autenticazione. Questo metodo unirà tutti gli scopes precedentemente specificati con quelli che specifichi:

use Laravel\Socialite\Facades\Socialite;

return Socialite::driver('github')
    ->scopes(['read:user', 'public_repo'])
    ->redirect();

Puoi sovrascrivere tutti gli scopes esistenti nella richiesta di autenticazione usando il metodo setScopes:

return Socialite::driver('github')
    ->setScopes(['read:user', 'public_repo'])
    ->redirect();

Ambiti del Bot di Slack

L’API di Slack fornisce diversi tipi di access token, ognuno con il proprio insieme di scope di autorizzazione. Socialite è compatibile con entrambi i seguenti tipi di access token di Slack:

• Bot (prefissato con xoxb-)
• User (prefissato con xoxp-)

Per impostazione predefinita, il driver slack genererà un token user e invocare il metodo user del driver restituirà i dettagli dell’utente.

I token Bot sono principalmente utili se la tua applicazione invierà notifiche a workspaces Slack esterni di proprietà degli utenti della tua applicazione. Per generare un token Bot, invoca il metodo asBotUser prima di reindirizzare l’utente a Slack per l’autenticazione:

    return Socialite::driver('slack')
        ->asBotUser()
        ->setScopes(['chat:write', 'chat:write.public', 'chat:write.customize'])
        ->redirect();

Inoltre, devi invocare il metodo asBotUser prima di invocare il metodo user dopo che Slack reindirizza l’utente alla tua applicazione dopo l’autenticazione:

    $user = Socialite::driver('slack')->asBotUser()->user();

Quando si genera un token Bot, il metodo user restituirà comunque un’istanza di Laravel\Socialite\Two\User; tuttavia, solo la proprietà token sarà valorizzata. Questo token può essere memorizzato per inviare notifiche ai workspaces Slack autenticati dell’utente.

Parametri Opzionali

Molti provider OAuth supportano altri parametri opzionali nella richiesta di reindirizzamento. Per includere parametri opzionali nella richiesta, chiama il metodo with con un array associativo:

    use Laravel\Socialite\Facades\Socialite;

    return Socialite::driver('google')
        ->with(['hd' => 'example.com'])
        ->redirect();

Quando usi il metodo with, fai attenzione a non passare parole chiave riservate come state o response_type.

Recupero dei Dettagli Utente

Dopo che l’utente viene reindirizzato alla route di callback per l’autenticazione della tua applicazione, puoi recuperare i dettagli dell’utente utilizzando il metodo user di Socialite. L’oggetto utente restituito dal metodo user fornisce una varietà di proprietà e metodi che puoi usare per memorizzare le informazioni sull’utente nel tuo database.

Le proprietà e i metodi disponibili su questo oggetto possono variare a seconda che il provider OAuth con cui stai autenticando supporti OAuth 1.0 o OAuth 2.0:

    use Laravel\Socialite\Facades\Socialite;

    Route::get('/auth/callback', function () {
        $user = Socialite::driver('github')->user();

        // Provider OAuth 2.0...
        $token = $user->token;
        $refreshToken = $user->refreshToken;
        $expiresIn = $user->expiresIn;

        // Provider OAuth 1.0...
        $token = $user->token;
        $tokenSecret = $user->tokenSecret;

        // Tutti i provider...
        $user->getId();
        $user->getNickname();
        $user->getName();
        $user->getEmail();
        $user->getAvatar();
    });
```php

<a name="recuperare-i-dettagli-dellutente-da-un-token"></a>
#### Recuperare i Dettagli dell'Utente da un Token

Se hai già un token di accesso valido per un utente, puoi recuperare i suoi dettagli utilizzando il metodo `userFromToken` di Socialite:

```php
use Laravel\Socialite\Facades\Socialite;

$user = Socialite::driver('github')->userFromToken($token);

Se stai utilizzando il Login Limitato di Facebook tramite un’applicazione iOS, Facebook restituirà un token OIDC invece di un token di accesso. Come un token di accesso, anche il token OIDC può essere fornito al metodo userFromToken per ottenere i dettagli dell’utente.

Autenticazione Stateless

Il metodo stateless può essere utilizzato per disabilitare la verifica dello stato della sessione. Questo è utile quando si aggiunge l’autenticazione social a un’API stateless che non utilizza sessioni basate su cookie:

use Laravel\Socialite\Facades\Socialite;

return Socialite::driver('google')->stateless()->user();