HMAC-hitelesítés és biztonság

Védje meg HMAC-aláírt OG-kép URL-jeit a FastOG HMAC-SHA256 hitelesítésével. Ez az útmutató lefedi az egyes kérések aláírását, ellenőrzését és hibaelhárítását, így menet közben állíthat elő dinamikus Open Graph képeket — előfizetéshez kötötten, korlátlan rendereléssel (havi renderelési kvóta és túllépési díj nélkül). Regisztráljon, válasszon Dynamic API-csomagot, majd hozza létre API-kulcsát és HMAC-titkát az irányítópulton (a fizetős API-renderelések tiszták). Írja alá egyszer a szerverén, és percek alatt integrálja.

🚀 Gyors kezdés

Új az HMAC-alapú aláírásban? Kezdje itt:

1. Gyors kezdési útmutató — Induljon el 5 perc alatt
2. JavaScript-oktatóanyag — Teljes útmutató Node.js/Next.js-fejlesztőknek
3. Az összes keretrendszer-oktatóanyag — válassza ki a stackjét:
   • Next.js App Router
   • Next.js Pages Router
   • React
   • SvelteKit
   • Vue/Nuxt
   • Astro
   • Express
   • Tiszta Node.js
   • JavaScript
   • PHP/Laravel
   • Python
   • Ruby/Rails

📚 Dokumentációs index

Alapfogalmak

• HMAC-aláírás útmutató — Teljes referenciaként szolgál az algoritmus részleteivel, követelményeivel és JavaScript, PHP és Python példákkal
• HMAC-ellenőrzés — Szerveroldali megvalósítási részletek, biztonsági funkciók és hibaválaszok

Oktatóanyagok

• JavaScript/Node.js oktatóanyag — Átfogó útmutató, amely az alábbiakat fedi le:

  • Gyors kezdés (5 perc)
  • Next.js App Router (3 minta)
  • Next.js Pages Router
  • Express.js háttérrendszer
  • Tiszta Node.js
  • Frontend-integrációs minták (SSG, SSR, kliensoldali)
  • Tesztelés és hibakeresés
  • Gyakori buktatók

• Next.js App Router

• Next.js Pages Router

• React

• SvelteKit

• Vue/Nuxt

• Astro

• Express

• Tiszta Node.js

• PHP/Laravel

• Python

• Ruby/Rails

Gyors referencia

Algoritmus

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>

Lekérdezési paraméterek

Hibakódok

🎯 Felhasználási esetek

Blogbejegyzések

Dinamikus OG-képek generálása blogbejegyzésekhez:

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

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

E-kereskedelmi termékek

OG-képek létrehozása termékoldalakhoz:

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

Vásárlói vélemények

OG-képek generálása ajánlásokhoz:

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

🔐 Biztonság

Bevált gyakorlatok

1. Tárolja a titkos kulcsokat biztonságosan — Használjon környezeti változókat vagy titkosításkezelőt
2. Soha ne tegye közzé az HMAC-titkot kliensoldali kódban — Csak szerveroldalon írjon alá
3. Használjon HTTPS-t — Megakadályozza a MITM-támadásokat
4. Forgassa a titkos kulcsokat időszakosan — Különösen, ha kompromittálódtak
5. Figyelje a sikertelen aláírásokat — Az ismétlődő hibák támadásra utalhatnak
6. Felhasználónkénti elkülönítés — Minden API-kulcs saját HMAC-titokkal rendelkezik

Az HMAC-titok beszerzése

1. Lépjen a Vezérlőpult → API-kulcsok menüpontra
2. Hozzon létre egy új API-kulcsot
3. Másolja ki az HMAC-titkot (csak egyszer jelenik meg!)
4. Tárolja környezeti változókban

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

🧪 Tesztelés

Teszt URL generálása

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

Tesztelés curl-lel

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

Várt válaszok

• ✅ Érvényes aláírás → OG-képet ad vissza (vagy 422-t, ha a sablonparaméterek érvénytelenek)
• ❌ Érvénytelen aláírás → {"code": "invalid_signature"}
• ❌ Hiányzó paraméterek → {"code": "missing_signature"}

🛠 Hibaelhárítás

Az aláírás nem egyezik

1. Ellenőrizze, hogy a megfelelő HMAC-titkot használja (ellenőrizze az API-kulcsot az irányítópulton)
2. Ellenőrizze a kanonikus lekérdezést: minden lekérdezési paraméter a s kivételével (beleértve a key-et is), az értékek rfc3986-kódolással, a kulcsok lexikografikus sorrendben rendezve
3. Ellenőrizze, hogy az aláírás kisbetűs hexadecimális formátumú (64 karakter)

📖 Kiegészítő források

• API-referencia — Teljes API-dokumentáció
• Biztonsági ajánlások — Részletes biztonsági útmutató
• Tudásbázis — Technikai megvalósítási részletek

❓ GYIK

K: Miért lekérdezési paraméterek, és nem fejlécek?
V: Az OG-képeket közösségi hálózati robotok (LinkedIn, Twitter, Facebook) töltik le, amelyek nem küldenek egyéni fejléceket. Az aláírásnak az URL-ben KELL lennie.

K: Használhatom ugyanazt az aláírást több kéréshez is?
V: Igen. Az aláírás a pontos lekérdezésből számítódik (s nélkül), így ugyanaz az aláírt URL érvényes marad, amíg a paraméterek nem változnak. Bármely paraméter módosítása (beleértve a key-et is) újra-aláírást igényel.

K: Minden sablonhoz alá kell írnom a kéréseket?
V: Igen. A /api/v1/og címre küldött összes kérés HMAC-aláírást igényel.

K: Mi történik, ha a HMAC-titkom kompromittálódik?
V: Vonja vissza az API-kulcsot az irányítópulton, és hozzon létre egy újat. Minden API-kulcsnak saját HMAC-titka van.

K: Kikapcsolhatom a HMAC-ellenőrzést belső szolgáltatásokhoz?
V: Egyedi megoldásokért forduljon az ügyfélszolgálathoz. A HMAC-ellenőrzés kötelező minden nyilvános API-végpont esetében.

🆘 Támogatás

Segítségre van szüksége?

• Tekintse át a JavaScript oktatóanyagot a teljes kódpéldákért
• Nézze meg a HMAC aláírás útmutatót az algoritmus részleteiért
• Vegye fel a kapcsolatot az ügyfélszolgálattal a [email protected] címen

Kapcsolódó

• Dokumentáció — Minden FastOG-útmutató és referencia
• Ingyenes OG-képtesztelő — Előnézet fiók nélkül
• Gyorsindítási útmutató — Kezdje el 5 perc alatt
• HMAC-aláírás útmutató — Az algoritmus részletei
• HMAC-ellenőrzés — Szerveroldali ellenőrzés