Come generare un nuovo token Laravel Sanctum

Laravel Sanctum offre un sistema semplice per autenticare API e applicazioni tramite token personali. Se un token viene perso, compromesso o deve essere sostituito, non è possibile recuperarlo dalla tabella personal_access_tokens: occorre revocare quello precedente e generarne uno nuovo.

In questo articolo vediamo la procedura completa, usando Laravel Tinker e, in alternativa, un comando Artisan personalizzato.

Come funziona un token Sanctum

Quando viene creato un token con:

$token = $user->createToken('api-token')->plainTextToken;

Sanctum restituisce il token in chiaro una sola volta. Un token può avere un formato simile:

t12|mVx2...token-segreto...

La parte iniziale identifica il record nella tabella personal_access_tokens, mentre il segreto viene utilizzato per autenticare le richieste.

Per motivi di sicurezza, Sanctum salva nel database soltanto l’hash del token. Di conseguenza, il valore originale non può essere ricostruito successivamente interrogando la tabella.

Prerequisiti

Il modello User deve utilizzare il trait HasApiTokens:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens;
}

Le rotte protette devono invece utilizzare il middleware auth:sanctum:

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::middleware('auth:sanctum')
    ->get('/profile', function (Request $request) {
        return $request->user();
    });

Generare un token con Tinker

Il metodo più rapido consiste nell’utilizzare Laravel Tinker.

Aprire una shell nel progetto Laravel:

php artisan tinker

Individuare l’utente per il quale generare il nuovo token:

$user = App\Models\User::findOrFail(123);

Sostituire 123 con l’ID reale dell’utente.

A questo punto è possibile generare il nuovo token:

$newToken = $user->createToken('api-token')->plainTextToken;

Per visualizzarlo:

$newToken;

Il risultato sarà simile a:

12|mVx2...token-segreto...

È importante copiare e salvare immediatamente questo valore. Dopo la creazione, il token in chiaro non sarà più disponibile.

Revocare un token specifico

Se si conosce l’ID del vecchio token nella tabella personal_access_tokens, è possibile revocarlo prima di crearne uno nuovo:

$user->tokens()
    ->where('id', 456)
    ->delete();

In questo esempio:

• 123 è l’ID dell’utente;
• 456 è l’ID del token da revocare.

Dopo la revoca, generare il nuovo token:

$newToken = $user->createToken('api-token')->plainTextToken;

$newToken;

Il vecchio token non potrà più essere utilizzato per autenticarsi.

Revocare tutti i token dell’utente

Quando si sospetta che un token sia stato compromesso, può essere opportuno invalidare tutte le chiavi API dell’utente:

$user->tokens()->delete();

$newToken = $user->createToken('api-token')->plainTextToken;

$newToken;

Questa procedura:

1. elimina tutti i token associati all’utente;
2. invalida eventuali applicazioni o dispositivi che li utilizzano;
3. genera un nuovo token;
4. restituisce il nuovo valore in chiaro.

È una soluzione efficace, ma va usata con attenzione perché tutti i client dovranno essere aggiornati con il nuovo token.

Creare un token con permessi specifici

Sanctum permette di associare al token un insieme di abilità, dette abilities.

Per esempio:

$newToken = $user->createToken(
    'api-token',
    ['orders:read', 'orders:write']
)->plainTextToken;

In questo caso il token può essere utilizzato per le operazioni relative alla lettura e alla modifica degli ordini.

Per concedere tutti i permessi disponibili:

$newToken = $user->createToken(
    'api-token',
    ['*']
)->plainTextToken;

Quando possibile, è preferibile assegnare soltanto i permessi necessari, seguendo il principio del privilegio minimo.

Utilizzare il token nelle richieste HTTP

Il token deve essere inviato nell’header Authorization:

Authorization: Bearer 12|mVx2...token-segreto...

Esempio con cURL:

curl https://example.com/api/profile \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 12|mVx2...token-segreto..."

Se il token è valido e la rotta utilizza auth:sanctum, Laravel autenticherà la richiesta e renderà disponibile l’utente tramite:

$request->user();

Creare un comando Artisan dedicato

Se questa operazione deve essere eseguita frequentemente, è possibile creare un comando Artisan personalizzato:

php artisan make:command RegenerateSanctumToken

Aprire il file:

app/Console/Commands/RegenerateSanctumToken.php

e inserire il seguente codice:

<?php

namespace App\Console\Commands;

use App\Models\User;
use Illuminate\Console\Command;

class RegenerateSanctumToken extends Command
{
    protected $signature = 'user:token
                            {user : ID dell’utente}
                            {--revoke-all : Revoca tutti i token esistenti}
                            {--name=api-token : Nome del nuovo token}';

    protected $description = 'Genera un nuovo token Laravel Sanctum per un utente';

    public function handle(): int
    {
        $user = User::find($this->argument('user'));

        if (!$user) {
            $this->error('Utente non trovato.');

            return self::FAILURE;
        }

        if ($this->option('revoke-all')) {
            $user->tokens()->delete();
        }

        $token = $user
            ->createToken($this->option('name'))
            ->plainTextToken;

        $this->newLine();
        $this->info('Nuovo token generato:');
        $this->line($token);
        $this->newLine();
        $this->warn(
            'Salvalo ora: non sarà possibile recuperarlo dal database.'
        );

        return self::SUCCESS;
    }
}

Utilizzare il comando

Per generare un token lasciando attivi quelli esistenti:

php artisan user:token 123

Per revocare tutti i token esistenti e generarne uno nuovo:

php artisan user:token 123 --revoke-all

Per assegnare un nome personalizzato:

php artisan user:token 123 --name=mobile-app

È possibile combinare le opzioni:

php artisan user:token 123 \
  --name=mobile-app \
  --revoke-all

Buone pratiche di sicurezza

Un token Sanctum deve essere trattato come una password.

• Non inserirlo nel codice sorgente.
• Non pubblicarlo in repository Git.
• Non copiarlo nei log applicativi.
• Non inserirlo in screenshot o ticket pubblici.
• Trasmetterlo soltanto tramite HTTPS.
• Revocarlo immediatamente se si sospetta una compromissione.
• Utilizzare token separati per applicazioni e dispositivi diversi.
• Assegnare soltanto le abilities necessarie.
• Salvare il token in un secret manager o in una variabile d’ambiente protetta.

Per esempio, in un ambiente locale è possibile configurare un token in .env:

SANCTUM_API_TOKEN=12|mVx2...token-segreto...

Il file .env non deve essere versionato né esposto pubblicamente.

Conclusione

Un token Laravel Sanctum perso non può essere ricostruito dalla tabella personal_access_tokens, perché nel database viene conservato soltanto il suo hash. La procedura corretta consiste nel revocare il token precedente, quando necessario, e generarne uno nuovo tramite createToken().

La procedura più rapida è:

$user = App\Models\User::findOrFail(123);

$user->tokens()->delete();

$newToken = $user->createToken('api-token')->plainTextToken;

$newToken;

Il valore restituito deve essere copiato immediatamente e utilizzato come Bearer token nelle successive richieste API.

enjoy!