HMAC-autentisering och säkerhet

Säkra dina HMAC-signerade OG-bild-URL:er med FastOG:s HMAC-SHA256-autentisering. Den här guiden täcker signering, validering och felsökning av varje förfrågan, så att du kan leverera dynamiska Open Graph-bilder i farten — prenumerationsbegränsade, med obegränsade renderingar (ingen månatlig renderingskvot och ingen överbetalningsfakturering). Registrera dig, välj en Dynamic API-plan och skapa sedan din API-nyckel och HMAC-hemlighet i instrumentpanelen (betalda API-renderingar är rena). Signera på din server en gång och integrera på några minuter.

🚀 Snabbstart

Ny på HMAC-signering? Börja här:

1. Snabbstartsguide — Kom igång på 5 minuter
2. JavaScript-handledning — Komplett guide för Node.js/Next.js-utvecklare
3. Alla ramverkshandledningar — välj din stack:
   • Next.js App Router
   • Next.js Pages Router
   • React
   • SvelteKit
   • Vue/Nuxt
   • Astro
   • Express
   • Vanilla Node.js
   • JavaScript
   • PHP/Laravel
   • Python
   • Ruby/Rails

📚 Dokumentationsindex

Grundläggande koncept

• HMAC-signaturguide — Fullständig referens med algoritmdetaljer, krav och exempel i JavaScript, PHP och Python
• HMAC-validering — Implementeringsdetaljer på serversidan, säkerhetsfunktioner och felmeddelanden

Handledningar

• JavaScript/Node.js-handledning — Omfattande guide som täcker:

  • Snabbstart (5 minuter)
  • Next.js App Router (3 mönster)
  • Next.js Pages Router
  • Express.js-backend
  • Vanilla Node.js
  • Frontend-integrationsmönster (SSG, SSR, klientsidan)
  • Testning och felsökning
  • Vanliga fallgropar

• Next.js App Router

• Next.js Pages Router

• React

• SvelteKit

• Vue/Nuxt

• Astro

• Express

• Vanilla Node.js

• PHP/Laravel

• Python

• Ruby/Rails

Snabbreferens

Algoritm

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>

Frågeparametrar

Felkoder

🎯 Användningsområden

Blogginlägg

Generera dynamiska OG-bilder för blogginlägg:

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

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

E-handelsprodukter

Skapa OG-bilder för produktsidor:

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

Kundomdömen

Generera OG-bilder för citat från kundomdömen:

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

🔐 Säkerhet

Bästa praxis

1. Förvara hemligheter säkert — Använd miljövariabler eller en hemlighetshanterare
2. Exponera aldrig HMAC-hemligheten i klientkod — Signera endast på servern
3. Använd HTTPS — Förhindrar MITM-attacker
4. Rotera hemligheter regelbundet — Särskilt om de komprometterats
5. Övervaka misslyckade signaturer — Upprepade misslyckanden kan tyda på attacker
6. Isolering per användare — Varje API-nyckel har sin egen HMAC-hemlighet

Hämta din HMAC-hemlighet

1. Gå till Instrumentpanel → API-nycklar
2. Skapa en ny API-nyckel
3. Kopiera HMAC-hemligheten (visas endast en gång!)
4. Förvara den i miljövariabler

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

🧪 Testning

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

Testa med curl

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

Förväntade svar

• ✅ Giltig signatur → Returnerar OG-bild (eller 422 om mallparametrarna är ogiltiga)
• ❌ Ogiltig signatur → {"code": "invalid_signature"}
• ❌ Saknade parametrar → {"code": "missing_signature"}

🛠 Felsökning

Signaturen matchar inte

1. Kontrollera att du använder rätt HMAC-hemlighet (kontrollera API-nyckeln i instrumentpanelen)
2. Kontrollera den kanoniska frågesträngen: varje frågeparameter utom s (inklusive key), värden RFC3986-kodade, nycklar sorterade lexikografiskt
3. Kontrollera att signaturen är hexadecimal med gemener (64 tecken)

📖 Yttre resurser

• API-referens — Fullständig API-dokumentation
• Säkerhetsrekommendationer — Detaljerad säkerhetsguide
• Kunskapsbas — Tekniska implementeringsdetaljer

❓ FAQ

F: Varför query-parametrar istället för headers?
S: OG-bilder hämtas av sociala nätverkscrawlers (LinkedIn, Twitter, Facebook) som inte skickar anpassade headers. Signaturen MÅSTE finnas i URL:en.

F: Kan jag använda samma signatur för flera förfrågningar?
S: Ja. En signatur beräknas från den exakta queryn (minus s), så samma signerade URL förblir giltig så länge parametrarna inte ändras. Ändrar du någon parameter (inklusive key) måste du signera om.

F: Måste jag signera förfrågningar för alla mallar?
S: Ja. Alla förfrågningar till /api/v1/og kräver HMAC-signaturer.

F: Vad händer om min HMAC-hemlighet komprometteras?
S: Återkalla API-nyckeln i dashboarden och skapa en ny. Varje API-nyckel har sin egen HMAC-hemlighet.

F: Kan jag inaktivera HMAC-validering för interna tjänster?
S: Kontakta supporten för anpassade lösningar. HMAC-validering är obligatorisk för alla publika API-endpoints.

🆘 Support

Behöver du hjälp?

• Kolla JavaScript-handledningen för kompletta kodexempel
• Gå igenom HMAC-signaturguiden för algoritmdetaljer
• Kontakta supporten på [email protected]

Relaterat

• Dokumentation — Alla FastOG-guider och referenser
• Gratis OG-Bildtestare — Förhandsvisa utan konto
• Snabbstartsguide — Kom igång på 5 minuter
• HMAC-signaturguide — Algoritmdetaljer
• HMAC-validering — Validering på serversidan