Gestire correttamente l'input degli URL firmati

Scopo di questa pagina

Se vuoi usare così come sono le condizioni stabilite al momento dell’emissione di un link di condivisione a scadenza, oltre a verificare la firma dell’URL devi essere coerente anche su da dove leggi i valori. Questa pagina usa un esempio che include nell’URL il tipo di report e il formato di output e restituisce un JSON di anteprima. La pagina si riferisce a Laravel 13. Per la generazione degli URL in generale consulta Generazione degli URL, mentre per le basi del recupero dell’input consulta Richieste HTTP.

La firma non protegge l’intera richiesta. Il corpo di un form o di un JSON non è firmato. Dopo la verifica della firma, recupera i valori di query firmati con $request->query('format'). input(), all() e le proprietà dinamiche possono restituire valori non firmati provenienti dal corpo. Questa distinzione vale anche per le richieste GET.

Cosa protegge la firma

Elemento	Trattamento
Percorso dell’URL	Incluso nella verifica della firma
Query string	In linea di principio inclusa nella verifica, tranne i parametri esclusi
Schema e host	Normalmente inclusi nella firma, ma non con la firma relativa
Corpo del form o JSON	Non firmato
Scadenza	Aggiunta da `temporarySignedRoute()` e controllata durante la verifica

input() è un’API che gestisce non solo la query string ma anche il corpo. Quando Laravel unisce questi input, i valori del corpo hanno la precedenza su quelli della query string. query(), invece, recupera solo la query string. Il fatto che la verifica della firma sia riuscita e il fatto che i valori letti in seguito siano firmati sono due controlli distinti.

Implementare un link di anteprima a scadenza

1. Definire la route da verificare

In routes/web.php, definisci una route con nome che richiede la firma. Questo esempio non interagisce con database o file e restituisce solo le condizioni ricevute.

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

Route::get('/reports/preview', function (Request $request) {
    $options = Validator::make([
        'report' => $request->query('report'),
        'format' => $request->query('format'),
    ], [
        'report' => ['required', 'string', 'in:monthly,annual'],
        'format' => ['required', 'string', 'in:csv,pdf'],
    ])->validate();

    return response()->json($options);
})->middleware('signed')->name('reports.preview');

Il middleware signed verifica firma e scadenza prima dell’esecuzione della closure. Se non sono validi, restituisce 403.
query() recupera esplicitamente dalla query string i valori usati dall’elaborazione.
La validazione viene eseguita sull’array ottenuto. La verifica della firma non garantisce né il tipo dei valori né il rispetto dei limiti consentiti dalla logica di business.

In questo esempio a Validator::make() vengono passati solo i valori estratti con query(). Se in un punto destinato a validare la query firmata li sostituisci con $request->all(), finirai per gestire un input che include anche il corpo.

2. Generare l’URL in un processo di emissione affidabile

Dopo aver registrato la route con nome, usa il codice seguente nel processo che emette il link. report e format non sono segnaposto del percorso, quindi vengono aggiunti alla query string.

use Illuminate\Support\Facades\URL;

$url = URL::temporarySignedRoute(
    'reports.preview',
    now()->addMinutes(30),
    ['report' => 'monthly', 'format' => 'csv'],
);

Oltre alle condizioni specificate, questo URL contiene expires e signature. expires e signature sono parametri riservati usati da Laravel, quindi non usarli come nomi di parametri applicativi. Se in un’applicazione reale esponi il processo di emissione, non permettere a chiunque di emettere link con condizioni arbitrarie e applica l’autenticazione e l’autorizzazione necessarie.

3. Verificare l’uso normale

Aprendo l’URL emesso così com’è entro la scadenza, viene restituito il seguente JSON.

{
  "report": "monthly",
  "format": "csv"
}

Quando il link è scaduto, il middleware signed della route restituisce 403. Un URL firmato non è un token monouso. In questo esempio, lo stesso URL può essere riutilizzato finché non scade. Se vuoi consentirne un solo utilizzo, devi gestire uno stato “già usato” separatamente dalla firma.

Separare i valori esclusi dalla verifica

Se vuoi consentire valori aggiunti dal frontend, come il numero di pagina, puoi escluderli dalla verifica della firma con hasValidSignatureWhileIgnoring(['page']). Tuttavia, chiunque può modificare i valori esclusi, quindi non trattarli come condizioni firmate. Ad esempio, page, usato per la visualizzazione, ha un ruolo diverso da report e format, fissati al momento dell’emissione. Non escludere per semplice comodità i valori usati per decidere i dati di destinazione, il destinatario, il prezzo e simili.

L’esempio precedente usa il middleware signed standard, quindi nemmeno page è escluso. Se vuoi aggiungere parametri di query, decidi prima, sia lato generazione sia lato verifica, cosa deve essere firmato.

Usare la firma relativa

Se il progetto non include il dominio nella firma, combina absolute: false in fase di generazione con signed:relative in fase di verifica.

$url = URL::temporarySignedRoute(
    'reports.preview',
    now()->addMinutes(30),
    ['report' => 'monthly', 'format' => 'csv'],
    absolute: false,
);

In questo caso, sostituisci middleware('signed') con middleware('signed:relative') nella route precedente. Anche con la firma relativa il corpo non è firmato, quindi la regola di recuperare i valori con query() non cambia.

Checklist di implementazione

La route di ricezione richiede la verifica della firma.
I valori di query firmati vengono recuperati con query().
Il formato e i valori consentiti vengono validati separatamente.
I valori esclusi dalla verifica della firma non vengono usati come condizioni fissate all’emissione.
L’impostazione di firma assoluta o relativa è coerente tra generazione e verifica.
Conoscere l’URL non viene considerato equivalente ai permessi dell’utente autenticato.

Pagine correlate e fonti primarie

Generazione degli URL: API degli URL firmati e risposta alle firme non valide
Richieste HTTP: recupero dell’input e della query string
Validazione: validazione del formato dell’input e dei valori consentiti
Documentazione ufficiale di Laravel: Signed URLs
Documentazione ufficiale di Laravel: Retrieving input from the query string
Laravel Framework: UrlGenerator
Laravel Framework: ValidateSignature

Architettura

Database

Eloquent

Sicurezza

Eventi

Mail e notifiche

Pagamenti

Elaborazione asincrona

Comunicazione in tempo reale

Scheduling

Cache e ottimizzazione

Internazionalizzazione

File e storage

Debug e monitoraggio

Console e CLI

Performance

Frontend

Sviluppo con AI

Ambiente di sviluppo

Gestire correttamente l'input degli URL firmati

Scopo di questa pagina

Cosa protegge la firma

Implementare un link di anteprima a scadenza

1. Definire la route da verificare

2. Generare l’URL in un processo di emissione affidabile

3. Verificare l’uso normale

Separare i valori esclusi dalla verifica

Usare la firma relativa

Checklist di implementazione

Pagine correlate e fonti primarie

​Scopo di questa pagina

​Cosa protegge la firma

​Implementare un link di anteprima a scadenza

​1. Definire la route da verificare

​2. Generare l’URL in un processo di emissione affidabile

​3. Verificare l’uso normale

​Separare i valori esclusi dalla verifica

​Usare la firma relativa

​Checklist di implementazione

​Pagine correlate e fonti primarie

Scopo di questa pagina

Cosa protegge la firma

Implementare un link di anteprima a scadenza

1. Definire la route da verificare

2. Generare l’URL in un processo di emissione affidabile

3. Verificare l’uso normale

Separare i valori esclusi dalla verifica

Usare la firma relativa

Checklist di implementazione

Pagine correlate e fonti primarie