HMAC-autentisering og sikkerhet

Sikre dine HMAC-signerte OG-bilde-URL-er med FastOGs HMAC-SHA256-autentisering. Denne guiden dekker signering, validering og feilsøking av hver forespørsel, slik at du kan levere dynamiske Open Graph-bilder i sanntid — abonnementsbegrenset, med uavgrensede render (uten månedlig render-kvote og uten fakturering for overskridelse). Registrer deg, velg en Dynamic API-plan, og opprett deretter API-nøkkelen og HMAC-hemmeligheten i dashbordet (betalte API-render er rene). Signer på serveren din én gang og integrer på få minutter.

🚀 Hurtigstart

Ny på HMAC-signering? Start her:

1. Hurtigstart-guide — Kom i gang på 5 minutter
2. JavaScript-veiledning — Fullstendig guide for Node.js/Next.js-utviklere
3. Alle rammeverksveiledninger — velg din stabel:
   • Next.js App Router
   • Next.js Pages Router
   • React
   • SvelteKit
   • Vue/Nuxt
   • Astro
   • Express
   • Vanilla Node.js
   • JavaScript
   • PHP/Laravel
   • Python
   • Ruby/Rails

📚 Dokumentasjonsindeks

Kjerneprinsipper

• HMAC-signaturveiledning — Fullstendig referanse med algoritmedetaljer, krav og eksempler i JavaScript, PHP og Python
• HMAC-validering — Implementeringsdetaljer på serversiden, sikkerhetsfunksjoner og feilmeldinger

Veiledninger

• JavaScript/Node.js-veiledning — Omfattende guide som dekker:

  • Hurtigstart (5 minutter)
  • Next.js App Router (3 mønstre)
  • Next.js Pages Router
  • Express.js-backend
  • Ren Node.js
  • Frontend-integreringsmønstre (SSG, SSR, klientside)
  • Testing og feilsøking
  • Vanlige fallgruver

• Next.js App Router

• Next.js Pages Router

• React

• SvelteKit

• Vue/Nuxt

• Astro

• Express

• Ren Node.js

• PHP/Laravel

• Python

• Ruby/Rails

Hurtigreferanse

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>

Forespørselsparametere

Feilkoder

🎯 Bruksområder

Blogginnlegg

Generer dynamiske OG-bilder for blogginnlegg:

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

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

E-handelsprodukter

Lag OG-bilder for produktsider:

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

Attester

Generer OG-bilder for attest-sitater:

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

🔐 Sikkerhet

Beste praksis

1. Oppbevar hemmeligheter sikkert — Bruk miljøvariabler eller en hemmelighetsbehandler
2. Aldri eksponer HMAC-hemmeligheten i klientsidekode — Signer kun på serveren
3. Bruk HTTPS — Forhindrer MITM-angrep
4. Roter hemmeligheter jevnlig — Spesielt hvis de er kompromittert
5. Overvåk mislykkede signaturer — Gjentatte feil kan tyde på angrep
6. Isolasjon per bruker — Hver API-nøkkel har sin egen HMAC-hemmelighet

Hvordan få tak i HMAC-hemmeligheten din

1. Gå til Dashbord → API-nøkler
2. Opprett en ny API-nøkkel
3. Kopier HMAC-hemmeligheten (vises kun én gang!)
4. Lagre den i miljøvariabler

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

🧪 Testing

Generer test-URL

# 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);
"

Test med curl

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

Forventede svar

• ✅ Gyldig signatur → Returnerer OG-bilde (eller 422 hvis malparametrene er ugyldige)
• ❌ Ugyldig signatur → {"code": "invalid_signature"}
• ❌ Manglende parametere → {"code": "missing_signature"}

🛠 Feilsøking

Signaturen stemmer ikke

1. Kontroller at du bruker riktig HMAC-hemmelighet (sjekk API-nøkkelen i dashbordet)
2. Sjekk den kanoniske spørringen: alle spørringsparametere unntatt s (inkludert key), verdier rfc3986-kodet, nøkler sortert leksikografisk
3. Kontroller at signaturen er med små bokstaver i hex (64 tegn)

📖 Ytterligere ressurser

• API-referanse — Fullstendig API-dokumentasjon
• Sikkerhetsbeste praksis — Detaljert sikkerhetsveiledning
• Kunnskapsbase — Tekniske implementeringsdetaljer

❓ FAQ

Spørsmål: Hvorfor spørreparametere i stedet for headere?
Svar: OG-bilder hentes av crawlerne til sosiale nettverk (LinkedIn, Twitter, Facebook) som ikke sender egendefinerte headere. Signaturen MÅ ligge i URL-en.

Spørsmål: Kan jeg bruke samme signatur for flere forespørsler?
Svar: Ja. En signatur beregnes ut fra den nøyaktige spørringen (minus s), så den samme signerte URL-en forblir gyldig så lenge parameterne ikke endres. Endrer du en parameter (inkludert key), må du signere på nytt.

Spørsmål: Må jeg signere forespørsler for alle maler?
Svar: Ja. Alle forespørsler til /api/v1/og krever HMAC-signaturer.

Spørsmål: Hva skjer hvis HMAC-hemmeligheten min blir kompromittert?
Svar: Tilbakekall API-nøkkelen i dashbordet og opprett en ny. Hver API-nøkkel har sin egen HMAC-hemmelighet.

Spørsmål: Kan jeg deaktivere HMAC-validering for interne tjenester?
Svar: Kontakt kundestøtte for tilpassede løsninger. HMAC-validering er obligatorisk for alle offentlige API-endepunkter.

🆘 Støtte

Trenger du hjelp?

• Se JavaScript-veiledningen for komplette kodeeksempler
• Gå gjennom HMAC-signaturguiden for algoritmedetaljer
• Kontakt støtte på [email protected]

Relatert

• Dokumentasjon — Alle FastOG-guider og referanser
• Gratis OG-bildetester — Forhåndsvis uten konto
• Hurtigstartguide — Kom i gang på 5 minutter
• HMAC-signaturguide — Algoritmedetaljer
• HMAC-validering — Validering på serversiden