HMAC-authenticatie en beveiliging

Beveilig je HMAC-ondertekende OG-image-URL's met FastOG's HMAC-SHA256-authenticatie. Deze handleiding behandelt het ondertekenen, valideren en oplossen van problemen bij elke aanvraag, zodat je dynamische Open Graph-afbeeldingen direct kunt leveren — met abonnementsbeperking en onbeperkte renders (geen maandelijkse renderlimiet en geen overschrijdingskosten). Meld je aan, kies een Dynamic API-plan en maak vervolgens je API-sleutel en HMAC-geheim aan in het dashboard (betaalde API-renders zijn schoon). Onderteken eenmalig op je server en integreer binnen enkele minuten.

🚀 Snel aan de slag

Nieuw met HMAC-ondertekening? Begin hier:

1. Snelstartgids — Aan de slag in 5 minuten
2. JavaScript-zelfstudie — Volledige handleiding voor Node.js/Next.js-ontwikkelaars
3. Alle framework-zelfstudies — kies je stack:
   • Next.js App Router
   • Next.js Pages Router
   • React
   • SvelteKit
   • Vue/Nuxt
   • Astro
   • Express
   • Vanilla Node.js
   • JavaScript
   • PHP/Laravel
   • Python
   • Ruby/Rails

📚 Documentatie-index

Kernconcepten

• HMAC-handtekeninggids — Volledige referentie met algoritmedetails, vereisten en voorbeelden in JavaScript, PHP en Python
• HMAC-validatie — Server-side implementatiedetails, beveiligingsfuncties en foutmeldingen

Tutorials

• JavaScript/Node.js-tutorial — Uitgebreide gids met:

  • Snelstart (5 minuten)
  • Next.js App Router (3 patronen)
  • Next.js Pages Router
  • Express.js-backend
  • Vanilla Node.js
  • Frontend-integratiepatronen (SSG, SSR, client-side)
  • Testen en debuggen
  • Veelvoorkomende valkuilen

• Next.js App Router

• Next.js Pages Router

• React

• SvelteKit

• Vue/Nuxt

• Astro

• Express

• Vanilla Node.js

• PHP/Laravel

• Python

• Ruby/Rails

Snelle referentie

Algoritme

method = "GET"
path = "/api/v1/og"
canonicalQuery = every query param EXCEPT `s` (including `key`): array values sorted too; each pair rfc3986Encode(key)=rfc3986Encode(value); pairs sorted lexicographically and joined with "&"

message = method + path + "\n" + canonicalQuery
signature = hex(HMAC-SHA256(message, hmac_secret))

URL: /api/v1/og?title=Hello&key=sk_quick_123abc&s=<signature>

Queryparameters

Foutcodes

🎯 Gebruikssituaties

Blogberichten

Genereer dynamische OG-afbeeldingen voor blogberichten:

const ogUrl = generateSignedOgUrl({
    template: "blog",
    title: post.title,
    subtitle: post.excerpt,
    author: post.author.name,
});

// <meta property="og:image" content="{ogUrl}" />

E-commerceproducten

Maak OG-afbeeldingen voor productpagina's:

const ogUrl = generateSignedOgUrl({
    template: "ecommerce",
    title: product.name,
    price: product.price,
    image: product.image,
});

Klantbeoordelingen

Genereer OG-afbeeldingen voor klantcitaten:

const ogUrl = generateSignedOgUrl({
    template: "testimonial",
    author_name: user.name,
    author_avatar: user.avatarUrl,
    quote: user.bio,
});

🔐 Beveiliging

Beste praktijken

1. Bewaar geheimen veilig — Gebruik omgevingsvariabelen of een geheimenbeheerder
2. Stel het HMAC-geheim nooit bloot in client-side code — Onderteken alleen op de server
3. Gebruik HTTPS — Voorkomt MITM-aanvallen
4. Roteer geheimen periodiek — Vooral als ze mogelijk gecompromitteerd zijn
5. Monitor mislukte handtekeningen — Herhaalde mislukkingen kunnen duiden op aanvallen
6. Isolatie per gebruiker — Elke API-sleutel heeft zijn eigen HMAC-geheim

Je HMAC-geheim verkrijgen

1. Ga naar Dashboard → API-sleutels
2. Maak een nieuwe API-sleutel aan
3. Kopieer het HMAC-geheim (wordt slechts één keer getoond!)
4. Sla het op in omgevingsvariabelen

# .env
FASTOG_HMAC_SECRET=<your-64-char-hex-secret>

🧪 Testen

Test-URL genereren

# Node.js
node -e "
const crypto = require('crypto');
const enc = (s) => encodeURIComponent(s).replace(/[!'()*]/g, (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase());
const all = { title: 'Test', key: 'sk_quick_123abc' };
const pairs = [];
for (const [k, v] of Object.entries(all)) for (const vv of Array.isArray(v) ? v : [v]) pairs.push(enc(k) + '=' + enc(vv));
pairs.sort();
const canonical = pairs.join('&');
const sig = crypto.createHmac('sha256', 'YOUR_HMAC_SECRET').update('GET/api/v1/og\n' + canonical).digest('hex');
console.log('https://fastog.com/api/v1/og?title=Test&key=sk_quick_123abc&s=' + sig);
"

Testen met curl

curl "https://fastog.com/api/v1/og?title=Test&key=sk_quick_123abc&s=<signature>"

Verwachte reacties

• ✅ Geldige handtekening → Retourneert OG-afbeelding (of 422 als templateparameters ongeldig zijn)
• ❌ Ongeldige handtekening → {"code": "invalid_signature"}
• ❌ Ontbrekende parameters → {"code": "missing_signature"}

🛠 Problemen oplossen

Handtekening komt niet overeen

1. Controleer of je de juiste HMAC-geheime sleutel gebruikt (check de API-sleutel in het dashboard)
2. Controleer de canonieke query: elke queryparameter behalve s (inclusief key), waarden rfc3986-gecodeerd, sleutels lexicografisch gesorteerd
3. Controleer of de handtekening kleine hexadecimale letters zijn (64 tekens)

📖 Aanvullende bronnen

• API-referentie — Volledige API-documentatie
• Beste beveiligingspraktijken — Gedetailleerde beveiligingshandleiding
• Kennisbank — Technische implementatiedetails

❓ FAQ

V: Waarom queryparameters in plaats van headers?
A: OG-afbeeldingen worden opgehaald door crawlers van sociale netwerken (LinkedIn, Twitter, Facebook) die geen aangepaste headers meesturen. De handtekening MOET in de URL staan.

V: Kan ik dezelfde handtekening voor meerdere verzoeken gebruiken?
A: Ja. Een handtekening wordt berekend op basis van de exacte query (minus s), dus dezelfde ondertekende URL blijft geldig zolang de parameters niet wijzigen. Wijzig je een parameter (inclusief key), dan moet je opnieuw ondertekenen.

V: Moet ik verzoeken voor alle sjablonen ondertekenen?
A: Ja. Alle verzoeken aan /api/v1/og vereisen HMAC-handtekeningen.

V: Wat gebeurt er als mijn HMAC-geheim wordt gecompromitteerd?
A: Trek de API-sleutel in het dashboard in en maak een nieuwe aan. Elke API-sleutel heeft zijn eigen HMAC-geheim.

V: Kan ik HMAC-validatie uitschakelen voor interne services?
A: Neem contact op met support voor maatwerkoplossingen. HMAC-validatie is verplicht voor alle publieke API-endpoints.

🆘 Ondersteuning

Hulp nodig?

• Bekijk de JavaScript-zelfstudie voor volledige codevoorbeelden
• Raadpleeg de HMAC-handtekeninggids voor algoritmedetails
• Neem contact op met ondersteuning via [email protected]

Gerelateerd

• Documentatie — Alle FastOG-gidsen en referenties
• Gratis OG-afbeeldingstester — Bekijk een voorbeeld zonder account
• Snelstartgids — Aan de slag in 5 minuten
• HMAC-handtekeninggids — Algoritmedetails
• HMAC-validatie — Validatie aan de serverzijde