HMAC autentizace a zabezpečení

Zabezpečte své HMAC-podepsané OG image URL pomocí HMAC-SHA256 autentizace od FastOG. Tento průvodce pokrývá podepisování, ověřování a řešení problémů u každého požadavku, abyste mohli nasadit dynamické Open Graph obrázky za běhu — s omezením předplatným a bez omezení renderů (žádný měsíční limit renderů a žádné účtování za překročení). Zaregistrujte se, vyberte si Dynamic API plán, poté vytvořte svůj API klíč a HMAC tajemství v dashboardu (placené API rendery jsou čisté). Podepište na svém serveru jednou a integrujte během pár minut.

🚀 Rychlý start

Jste noví v podepisování HMAC? Začněte zde:

1. Průvodce rychlým startem — Běžíte za 5 minut
2. Tutoriál pro JavaScript — Kompletní průvodce pro vývojáře Node.js/Next.js
3. Všechny framework tutoriály — vyberte si svůj stack:
   • Next.js App Router
   • Next.js Pages Router
   • React
   • SvelteKit
   • Vue/Nuxt
   • Astro
   • Express
   • Vanilla Node.js
   • JavaScript
   • PHP/Laravel
   • Python
   • Ruby/Rails

📚 Rejstřík dokumentace

Základní koncepty

• Průvodce HMAC podpisem — Kompletní reference s detaily algoritmu, požadavky a příklady v JavaScriptu, PHP a Pythonu
• Validace HMAC — Implementace na straně serveru, bezpečnostní funkce a chybové odpovědi

Tutoriály

• Tutoriál JavaScript/Node.js — Obsáhlý průvodce pokrývající:

  • Rychlý start (5 minut)
  • Next.js App Router (3 vzory)
  • Next.js Pages Router
  • Express.js backend
  • Čistý Node.js
  • Integrační vzory frontendu (SSG, SSR, client-side)
  • Testování a ladění
  • Časté nástrahy

• Next.js App Router

• Next.js Pages Router

• React

• SvelteKit

• Vue/Nuxt

• Astro

• Express

• Čistý Node.js

• PHP/Laravel

• Python

• Ruby/Rails

Rychlý přehled

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>

Parametry dotazu

Chybové kódy

🎯 Případy použití

Příspěvky na blogu

Generujte dynamické OG obrázky pro příspěvky na blogu:

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

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

Produkty v e-shopu

Vytvářejte OG obrázky pro stránky produktů:

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

Reference

Generujte OG obrázky pro citace z referencí:

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

🔐 Zabezpečení

Doporučené postupy

1. Ukládejte tajemství bezpečně — Používejte proměnné prostředí nebo správce tajemství
2. Nikdy nevystavujte HMAC tajemství v kódu na straně klienta — Podepisujte pouze na serveru
3. Používejte HTTPS — Zabraňuje útokům typu MITM
4. Pravidelně obměňujte tajemství — Zejména pokud došlo k jejich kompromitaci
5. Sledujte neúspěšné podpisy — Opakované selhání může signalizovat útok
6. Izolace podle uživatele — Každý API klíč má vlastní HMAC tajemství

Získání vašeho HMAC tajemství

1. Přejděte do Dashboard → API Keys
2. Vytvořte nový API klíč
3. Zkopírujte HMAC tajemství (zobrazí se pouze jednou!)
4. Uložte do proměnných prostředí

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

🧪 Testování

Vygenerování testovací 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);
"

Testování pomocí curl

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

Očekávané odpovědi

• ✅ Platný podpis → Vrátí OG obrázek (nebo 422, pokud jsou parametry šablony neplatné)
• ❌ Neplatný podpis → {"code": "invalid_signature"}
• ❌ Chybějící parametry → {"code": "missing_signature"}

🛠 Řešení problémů

Podpis nesouhlasí

1. Ověřte, že používáte správný HMAC tajný klíč (zkontrolujte API klíč v dashboardu)
2. Zkontrolujte kanonický dotaz: každý parametr dotazu kromě s (včetně key), hodnoty zakódované podle rfc3986, klíče seřazené lexikograficky
3. Ověřte, že podpis je malými hex znaky (64 znaků)

📖 Další zdroje

• API Reference — Kompletní dokumentace API
• Security Best Practices — Podrobný bezpečnostní průvodce
• Knowledge Base — Technické detaily implementace

❓ Časté dotazy

O: Proč query parametry místo hlaviček?
A: OG obrázky stahují crawleři sociálních sítí (LinkedIn, Twitter, Facebook), kteří neposílají vlastní hlavičky. Podpis MUSÍ být v URL.

O: Mohu použít stejný podpis pro více požadavků?
A: Ano. Podpis se počítá z přesného dotazu (minus s), takže stejná podepsaná URL zůstává platná, dokud se parametry nezmění. Pokud změníte jakýkoli parametr (včetně key), musíte znovu podepsat.

O: Musím podepisovat požadavky pro všechny šablony?
A: Ano. Všechny požadavky na /api/v1/og vyžadují HMAC podpisy.

O: Co se stane, když je můj HMAC tajný klíč prozrazen?
A: Zneplatněte API klíč v dashboardu a vytvořte nový. Každý API klíč má vlastní HMAC tajný klíč.

O: Mohu vypnout HMAC validaci pro interní služby?
A: Kontaktujte podporu pro vlastní řešení. HMAC validace je povinná pro všechny veřejné API endpointy.

🆘 Podpora

Potřebujete pomoc?

• Prohlédněte si JavaScript tutoriál s kompletními příklady kódu
• Přečtěte si Průvodce HMAC podpisem pro detaily algoritmu
• Kontaktujte podporu na [email protected]

Související

• Dokumentace — Všechny průvodce a reference FastOG
• Bezplatný tester OG obrázků — Náhled bez účtu
• Průvodce rychlým startem — Začněte za 5 minut
• Průvodce podpisem HMAC — Detaily algoritmu
• Validace HMAC — Validace na straně serveru