Laravel Herd's SSL certificaten automatiseren voor lokale HTTPS-ontwikkeling

Wanneer je API-integraties test die HTTPS vereisen, stuit je op het probleem dat localhost geen geldig SSL-certificaat heeft. Laravel Herd lost dit op door automatisch zelfondertekende certificaten aan te maken, maar ik kom regelmatig situaties tegen waarin de standaardconfiguratie niet volstaat. Vooral bij het testen van webhooks van externe services of het integreren met payment providers die strikte SSL-verificatie hanteren, moet je de certificaatconfiguratie verfijnen.

Custom domeinen configureren met geldige certificaten

Laravel Herd maakt standaard een certificaat aan voor je projectnaam.test, maar soms heb je specifieke domeinnamen nodig die overeenkomen met je productieomgeving. Dit doe ik door eerst het gewenste domein toe te voegen aan mijn /etc/hosts bestand en vervolgens Herd te instrueren een certificaat voor dat domein te genereren.

# Voeg custom domein toe aan hosts
echo "127.0.0.1 api.mijnproject.local" | sudo tee -a /etc/hosts

# Genereer SSL certificaat via Herd CLI
herd secure api.mijnproject.local

Wat hier gebeurt is dat Herd een zelfondertekend certificaat aanmaakt en dit opslaat in de macOS Keychain. Het certificaat wordt automatisch vertrouwd door het systeem, waardoor browsers en HTTP-clients het als geldig beschouwen. Dit elimineert SSL-waarschuwingen die anders je testsessies verstoren.

Het mooie van deze aanpak is dat je meerdere subdomeinen kunt configureren voor één project. Ik doe dit vaak bij microservice-architecturen waarbij ik verschillende services op verschillende subdomeinen draai. Door elk subdomein apart te beveiligen, kan ik lokaal exact hetzelfde domeingedrag simuleren als in productie.

// In je Laravel .env bestand
APP_URL=https://api.mijnproject.local
FRONTEND_URL=https://app.mijnproject.local
ADMIN_URL=https://admin.mijnproject.local

Certificaten delen tussen teamleden

Een uitdaging die ik vaak tegenkom is dat SSL-certificaten niet automatisch worden gedeeld tussen teamgenoten. Iedereen moet zijn eigen certificaten genereren, wat inconsistentie kan veroorzaken in de ontwikkelomgeving. Ik heb een workflow ontwikkeld waarbij ik certificaatconfiguraties documenteer in het project.

#!/bin/bash
# scripts/setup-ssl.sh

# SSL setup voor lokale ontwikkeling
DOMAINS=(
    "api.mijnproject.local"
    "app.mijnproject.local" 
    "admin.mijnproject.local"
)

for domain in "${DOMAINS[@]}"; do
    echo "Configureer SSL voor $domain"
    echo "127.0.0.1 $domain" | sudo tee -a /etc/hosts
    herd secure "$domain"
done

echo "SSL configuratie voltooid"

Dit script zet ik in de projectrepository zodat nieuwe teamleden met één commando hun lokale SSL-omgeving kunnen opzetten. Het voorkomt dat iemand vergeet een specifiek subdomein te beveiligen en vervolgens tegen SSL-fouten aanloopt tijdens het testen van cross-domain requests.

Belangrijk hierbij is dat je de Herd-configuratie niet toevoegt aan version control. De .herd map bevat lokale paden en certificaatverwijzingen die specifiek zijn voor elke machine. In plaats daarvan documenteer je alleen welke domeinen beveiligd moeten worden.

API-integraties testen met geldig HTTPS

Externe services zoals Stripe, PayPal of custom webhook providers controleren vaak of je endpoint een geldig SSL-certificaat heeft. Zelfs voor development webhooks weigeren sommige services verbinding te maken met onbeveiligde endpoints. Hier wordt Herd's SSL-functionaliteit cruciaal voor je workflow.

// routes/api.php
Route::post('/webhooks/stripe', function (Request $request) {
    // Stripe webhook handler
    $payload = $request->getContent();
    $sig_header = $request->header('Stripe-Signature');
    
    // Verificatie werkt alleen met HTTPS
    $endpoint_secret = config('services.stripe.webhook_secret');
    
    try {
        $event = \Stripe\Webhook::constructEvent(
            $payload, $sig_header, $endpoint_secret
        );
    } catch(\UnexpectedValueException $e) {
        return response('Invalid payload', 400);
    } catch(\Stripe\Exception\SignatureVerificationException $e) {
        return response('Invalid signature', 400);
    }
    
    // Process webhook event
    return response('OK', 200);
});

Door je lokale ontwikkelomgeving te beveiligen met https://api.mijnproject.local/webhooks/stripe, kan Stripe daadwerkelijk webhooks naar je lokale machine sturen tijdens ontwikkeling. Dit elimineert de behoefte aan ngrok of vergelijkbare tunneling-services voor de meeste ontwikkeltaken.

Tevens kun je met een geldig HTTPS-endpoint OAuth-flows testen die callbacks naar je lokale applicatie maken. Veel OAuth-providers accepteren alleen HTTPS redirect URI's, zelfs voor development. Door Herd's SSL-certificaten te combineren met custom domeinen, bootst je productiegedrag na zonder externe dependencies.

Certificaatproblemen debuggen en oplossen

Ondanks dat Herd SSL-configuratie grotendeels automatiseert, loop je soms tegen problemen aan. Browser-caches kunnen oude certificaatinformatie vasthouden, of het certificaat wordt niet correct geïnstalleerd in de systeemkeychain. Ik heb een aantal debuggingsstappen die ik consequent doorloop.

# Controleer of certificaat correct is geïnstalleerd
security find-certificate -a -c "mijnproject.local" -p

# Verwijder oud certificaat indien nodig
security delete-certificate -c "mijnproject.local"

# Herinstalleer certificaat via Herd
herd unsecure mijnproject.local
herd secure mijnproject.local

Een veelvoorkomend probleem is dat browsers certificaten cachen, ook nadat je een nieuw certificaat hebt gegenereerd. Chrome's developer tools tonen SSL-certificaatdetails onder het Security-tabblad, waar je kunt verifiëren of het juiste certificaat actief is. Firefox heeft vergelijkbare tools onder de padlock-icon in de adresbalk.

Soms helpt het om de browsercache volledig te wissen of een incognito-venster te openen voor je tests. Certificaatwijzigingen worden niet altijd onmiddellijk opgepikt door actieve browsersessies. Ook kan het nuttig zijn om curl te draaien vanuit de terminal om te verifiëren dat SSL buiten de browser correct werkt.

Voor Node.js applicaties die API-calls naar je Laravel backend maken, moet je mogelijk de NODE_TLS_REJECT_UNAUTHORIZED environment variabele instellen op development omgevingen waar je zelfondertekende certificaten draait. Dit voorkomt SSL-verificatiefouten in je JavaScript-code.

De flexibiliteit van Herd's SSL-implementatie maakt lokale HTTPS-ontwikkeling toegankelijk zonder de complexiteit van handmatige certificaatbeheer. Door deze workflows in je projecten te integreren, creëer je een ontwikkelomgeving die dichter bij productie staat en minder verrassingen oplevert tijdens deployment.