FastOG
Subiect

Autentificare HMAC și Securitate

Protejează-ți URL-urile de imagini OG semnate HMAC cu autentificarea HMAC-SHA256 de la FastOG. Acest ghid acoperă semnarea, validarea și depanarea fiecărei cereri, astfel încât să poți livra imagini Open Graph dinamice pe loc — limitate prin abonament, cu randări nemăsurate (fără cotă lunară de randări și fără facturare pentru depășiri). Înregistrează-te, alege un plan Dynamic API, apoi creează-ți cheia API și secretul HMAC în panoul de control (randările API plătite sunt curate). Semnează o singură dată pe serverul tău și integrează în câteva minute.

🚀 Pornire rapidă

Nou în semnarea HMAC? Începe aici:

  1. Ghid de pornire rapidă — Pornește în 5 minute
  2. Tutorial JavaScript — Ghid complet pentru dezvoltatorii Node.js/Next.js
  3. Toate tutorialele pentru framework-uri — alege stiva ta:

📚 Indexul Documentației

Concepte de Bază

  • Ghidul Semnăturii HMAC — Referință completă cu detalii despre algoritm, cerințe și exemple în JavaScript, PHP și Python
  • Validarea HMAC — Detalii de implementare pe server, funcționalități de securitate și răspunsuri de eroare

Tutoriale

Referință Rapidă

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>

Parametri de Interogare

Parametru Descriere Exemplu
key Cheie API completă sk_quick_123abc
s Semnătură HMAC-SHA256 (64 caractere hex) 9f8a1b2c3d4e...

Coduri de Eroare

Cod Status HTTP Descriere
missing_signature 401 Lipsește parametrul key sau s
invalid_signature 401 Semnătura nu se potrivește

🎯 Cazuri de utilizare

Articole de blog

Generați imagini OG dinamice pentru articolele de blog:

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

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

Produse de comerț electronic

Creați imagini OG pentru paginile de produse:

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

Testimoniale

Generați imagini OG pentru citatele din testimoniale:

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

🔐 Securitate

Cele mai bune practici

  1. Stochează secretele în siguranță — Folosește variabile de mediu sau un manager de secrete
  2. Nu expune niciodată secretul HMAC în codul client — Semnează doar pe server
  3. Folosește HTTPS — Previne atacurile de tip MITM
  4. Rotește secretele periodic — Mai ales dacă au fost compromise
  5. Monitorizează semnăturile eșuate — Eșecurile repetate pot indica atacuri
  6. Izolare per utilizator — Fiecare cheie API are propriul secret HMAC

Obținerea secretului HMAC

  1. Mergi la Dashboard → API Keys
  2. Creează o nouă cheie API
  3. Copiază HMAC Secret (afișat o singură dată!)
  4. Stochează-l în variabile de mediu
bash
# .env
FASTOG_HMAC_SECRET=<your-64-char-hex-secret>

🧪 Testare

Generarea URL-ului de test

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

Testare cu curl

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

Răspunsuri așteptate

  • ✅ Semnătură validă → Returnează imaginea OG (sau 422 dacă parametrii șablonului sunt invalizi)
  • ❌ Semnătură invalidă → {"code": "invalid_signature"}
  • ❌ Parametri lipsă → {"code": "missing_signature"}

🛠 Depanare

Semnătura nu se potrivește

  1. Verifică că folosești secretul HMAC corect (verifică cheia API din panoul de control)
  2. Verifică interogarea canonică: fiecare parametru de interogare, cu excepția s (inclusiv key), valorile codificate rfc3986, cheile sortate lexicografic
  3. Verifică că semnătura este hexazecimal cu litere mici (64 de caractere)

📖 Resurse suplimentare

❓ Întrebări frecvente

Î: De ce parametri de interogare în loc de anteturi?
R: Imaginile OG sunt preluate de crawler-ele rețelelor sociale (LinkedIn, Twitter, Facebook) care nu trimit anteturi personalizate. Semnătura TREBUIE să fie în URL.

Î: Pot folosi aceeași semnătură pentru mai multe cereri?
R: Da. O semnătură este calculată din interogarea exactă (minus s), deci același URL semnat rămâne valid atâta timp cât parametrii nu se schimbă. Schimbă orice parametru (inclusiv key) și trebuie să resemnezi.

Î: Trebuie să semnez cererile pentru toate template-urile?
R: Da. Toate cererile către /api/v1/og necesită semnături HMAC.

Î: Ce se întâmplă dacă secretul meu HMAC este compromis?
R: Revocă cheia API din dashboard și creează una nouă. Fiecare cheie API are propriul secret HMAC.

Î: Pot dezactiva validarea HMAC pentru serviciile interne?
R: Contactează suportul pentru soluții personalizate. Validarea HMAC este obligatorie pentru toate endpoint-urile publice ale API-ului.

🆘 Suport

Ai nevoie de ajutor?

Încearcă gratuit — nu este necesară înregistrarea

Previzualizează și testează imagini OG dinamice în câteva secunde.

Deschide Testerul gratuit de imagini OG
LocaFile AI AI localization for games, apps, subtitles & sites SubtoVTT Convert & clean subtitle files BeCaSimulations Indie game studio

A BeCaSimulations site