Input van signed URL's correct verwerken

Doel van deze pagina

Wil je bij een tijdelijke deellink precies de voorwaarden gebruiken die bij het aanmaken van de link zijn vastgelegd, dan is het verifiëren van de URL-signature niet genoeg. Je moet ook consequent bepalen waar je de waarden vandaan haalt. Op deze pagina gebruiken we een voorbeeld waarin het rapporttype en het exportformaat in de URL staan en de route JSON voor een preview teruggeeft. Deze pagina is bedoeld voor Laravel 13. Zie URL’s genereren voor het genereren van URL’s in het algemeen en HTTP-requests voor de basis van het ophalen van input.

Een signature beschermt niet het hele request. Formulier- en JSON-bodies worden niet ondertekend. Haal ondertekende querywaarden na de signature-verificatie op met bijvoorbeeld $request->query('format'). Met input(), all() en dynamische properties kun je niet-ondertekende waarden uit de body ophalen. Dit onderscheid geldt ook voor GET-requests.

Wat de signature beschermt

Onderdeel	Behandeling
URL-pad	Wordt meegenomen in de signature-verificatie
Querystring	Wordt in principe meegenomen in de signature-verificatie, behalve parameters die je van de verificatie uitsluit
Schema en host	Worden normaal gesproken ondertekend, maar niet bij relatieve signatures
Formulier- en JSON-body	Wordt niet ondertekend
Vervaldatum	Wordt toegevoegd door `temporarySignedRoute()` en bij verificatie gecontroleerd

input() is een API die niet alleen de querystring maar ook de body leest. Wanneer Laravel deze input samenvoegt, krijgen waarden uit de body voorrang op die uit de querystring. query() haalt daarentegen alleen waarden uit de querystring op. Dat de signature-verificatie is geslaagd en dat de waarden die je daarna leest ondertekend zijn, zijn twee aparte dingen om te controleren.

Een tijdelijke previewlink implementeren

1. Definieer de route die de signature controleert

Definieer in routes/web.php een named route waarvoor een signature verplicht is. Deze route raakt geen database of bestanden aan en geeft alleen de ontvangen voorwaarden terug.

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

De signed-middleware controleert de signature en de vervaldatum voordat de closure wordt uitgevoerd. Is de signature ongeldig, dan wordt 403 teruggegeven.
Met query() haal je de waarden die je gebruikt expliciet uit de querystring.
De validatie wordt uitgevoerd op de opgehaalde array. Signature-verificatie garandeert niets over het type van de waarden of over wat zakelijk is toegestaan.

In dit voorbeeld krijgt Validator::make() alleen de waarden die met query() zijn opgehaald. Vervang je dit op een plek die bedoeld is om ondertekende querywaarden te valideren door $request->all(), dan werk je met input die ook de body bevat.

2. Genereer de URL in een vertrouwd uitgifteproces

Gebruik na het registreren van de named route de volgende code in het proces dat de link uitgeeft. report en format zijn geen placeholders in het pad en worden daarom aan de querystring toegevoegd.

use Illuminate\Support\Facades\URL;

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

Deze URL bevat naast de opgegeven voorwaarden ook expires en signature. expires en signature zijn gereserveerde parameters die Laravel gebruikt. Gebruik ze dus niet als namen voor je eigen parameters. Stel je het uitgifteproces in een echte applicatie beschikbaar, zorg dan dat niet iedereen links met willekeurige voorwaarden kan aanmaken en pas de nodige authenticatie en autorisatie toe.

3. Controleer het normale gebruik

Open je de uitgegeven URL ongewijzigd binnen de geldigheidsduur, dan krijg je de volgende JSON terug.

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

Is de link verlopen, dan geeft de signed-middleware van de route 403 terug. Een signed URL is geen eenmalig token. In dit voorbeeld kan dezelfde URL binnen de geldigheidsduur opnieuw worden gebruikt. Wil je een link maar één keer laten gebruiken, dan moet je los van de signature bijhouden of de link al is gebruikt.

Waarden die je van verificatie uitsluit apart houden

Wil je bijvoorbeeld een paginanummer toestaan dat de frontend toevoegt, dan kun je dat met hasValidSignatureWhileIgnoring(['page']) uitsluiten van de signature-verificatie. Uitgesloten waarden kan echter iedereen wijzigen, dus behandel ze niet als ondertekende voorwaarden. Zo hebben page voor de weergave en report en format, die bij de uitgifte worden vastgelegd, verschillende rollen. Sluit waarden die je gebruikt om te bepalen welke gegevens, welke ontvanger of welke prijs het betreft niet uit alleen omdat dat handig is.

Het voorbeeld hierboven gebruikt de gewone signed-middleware, dus ook page is niet uitgesloten. Wil je extra queryparameters gebruiken, bepaal dan eerst wat zowel bij het genereren als bij het verifiëren ondertekend moet worden.

Relatieve signatures gebruiken

Als het domein geen deel van de signature mag uitmaken, combineer je absolute: false bij het genereren met signed:relative bij het verifiëren.

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

Vervang in dat geval middleware('signed') in de route hierboven door middleware('signed:relative'). Ook bij relatieve signatures wordt de body niet ondertekend, dus je haalt de waarden nog steeds op met query().

Checklist voor de implementatie

De ontvangende route vereist signature-verificatie.
Ondertekende querywaarden worden opgehaald met query().
Het formaat en de toegestane waarden worden apart gevalideerd.
Waarden die van de signature-verificatie zijn uitgesloten, worden niet gebruikt als voorwaarden die bij de uitgifte zijn vastgelegd.
De instellingen voor absolute en relatieve signatures komen overeen tussen genereren en verifiëren.
Het kennen van de URL wordt niet gelijkgesteld aan de rechten van de ingelogde gebruiker.

Gerelateerde pagina’s en primaire bronnen

URL’s genereren: de API voor signed URL’s en reageren op ongeldige signatures
HTTP-requests: input en querystringwaarden ophalen
Validatie: het formaat en de toegestane waarden van input valideren
Officiële Laravel-documentatie: Signed URLs
Officiële Laravel-documentatie: Retrieving input from the query string
Laravel Framework: UrlGenerator
Laravel Framework: ValidateSignature

Architectuur

Database

Eloquent

Beveiliging

Events

E-mail en notificaties

Betalingen

Asynchrone verwerking

Realtime communicatie

Taakplanning

Caching en optimalisatie

Internationalisatie

Bestanden en opslag

Debugging en monitoring

Console en CLI

Performance

Frontend

AI-ontwikkeling

Ontwikkelomgeving

Input van signed URL's correct verwerken

Doel van deze pagina

Wat de signature beschermt

Een tijdelijke previewlink implementeren

1. Definieer de route die de signature controleert

2. Genereer de URL in een vertrouwd uitgifteproces

3. Controleer het normale gebruik

Waarden die je van verificatie uitsluit apart houden

Relatieve signatures gebruiken

Checklist voor de implementatie

Gerelateerde pagina’s en primaire bronnen

​Doel van deze pagina

​Wat de signature beschermt

​Een tijdelijke previewlink implementeren

​1. Definieer de route die de signature controleert

​2. Genereer de URL in een vertrouwd uitgifteproces

​3. Controleer het normale gebruik

​Waarden die je van verificatie uitsluit apart houden

​Relatieve signatures gebruiken

​Checklist voor de implementatie

​Gerelateerde pagina’s en primaire bronnen

Doel van deze pagina

Wat de signature beschermt

Een tijdelijke previewlink implementeren

1. Definieer de route die de signature controleert

2. Genereer de URL in een vertrouwd uitgifteproces

3. Controleer het normale gebruik

Waarden die je van verificatie uitsluit apart houden

Relatieve signatures gebruiken

Checklist voor de implementatie

Gerelateerde pagina’s en primaire bronnen