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

# Gestire correttamente l'input degli URL firmati

> Cosa protegge un URL firmato in Laravel 13 e perché recuperare i valori di query firmati con query(), spiegato con un esempio di link a scadenza.

## 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](/it/urls), mentre per le basi del recupero dell'input consulta [Richieste HTTP](/it/requests).

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

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

```mermaid theme={null}
flowchart TD
    A["Accesso tramite URL a scadenza"] --> B{"Middleware signed<br>verifica firma e scadenza"}
    B -->|Non valido| C["Risposta 403"]
    B -->|Valido| D["Recupera i valori di query firmati<br>con query()"]
    D --> E["Valida formato e valori consentiti"]
    E --> F["Restituisci l'anteprima"]
```

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

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

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

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

```php theme={null}
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](/it/authentication) e l'[autorizzazione](/it/authorization) necessarie.

### 3. Verificare l'uso normale

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

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

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

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

```php theme={null}
$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](/it/urls): API degli URL firmati e risposta alle firme non valide
* [Richieste HTTP](/it/requests): recupero dell'input e della query string
* [Validazione](/it/validation): validazione del formato dell'input e dei valori consentiti
* [Documentazione ufficiale di Laravel: Signed URLs](https://github.com/laravel/docs/blob/13.x/urls.md#signed-urls)
* [Documentazione ufficiale di Laravel: Retrieving input from the query string](https://github.com/laravel/docs/blob/13.x/requests.md#retrieving-input-from-the-query-string)
* [Laravel Framework: UrlGenerator](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Routing/UrlGenerator.php)
* [Laravel Framework: ValidateSignature](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Routing/Middleware/ValidateSignature.php)


## Related topics

- [Generazione degli URL](/it/urls.md)
- [Laravel AI SDK](/it/ai-sdk.md)
- [Asset pubblici e aggiornamento di un pacchetto](/it/advanced/package-assets.md)
- [Basic client - Laravel Bluesky](/it/packages/laravel-bluesky/basic-client.md)
- [Autenticazione OAuth 2.0 - Google Sheets API for Laravel](/it/packages/laravel-google-sheets/oauth.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.