FastOG
Argomento

Autenticazione HMAC e Sicurezza

Proteggi i tuoi URL di immagini OG firmati con HMAC utilizzando l'autenticazione HMAC-SHA256 di FastOG. Questa guida copre la firma, la validazione e la risoluzione dei problemi per ogni richiesta, così puoi pubblicare immagini Open Graph dinamiche al volo — con accesso basato su abbonamento e rendering senza limiti (nessun limite mensile di rendering e nessun addebito per eccedenze). Registrati, scegli un piano API dinamico, poi crea la tua chiave API e il segreto HMAC nel dashboard (i rendering API a pagamento sono puliti). Firma una volta sul tuo server e integra in pochi minuti.

🚀 Avvio Rapido

Nuovo alla firma HMAC? Inizia qui:

  1. Guida all'Avvio Rapido — Configura tutto in 5 minuti
  2. Tutorial JavaScript — Guida completa per sviluppatori Node.js/Next.js
  3. Tutti i tutorial sui framework — scegli il tuo stack:

📚 Indice della Documentazione

Concetti Fondamentali

  • Guida alla Firma HMAC — Riferimento completo con dettagli sull'algoritmo, requisiti ed esempi in JavaScript, PHP e Python
  • Validazione HMAC — Dettagli di implementazione lato server, funzionalità di sicurezza e risposte di errore

Tutorial

Riferimento Rapido

Algoritmo

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 di Query

Parametro Descrizione Esempio
key Chiave API completa sk_quick_123abc
s Firma HMAC-SHA256 (64 caratteri hex) 9f8a1b2c3d4e...

Codici di Errore

Codice Stato HTTP Descrizione
missing_signature 401 Parametro key o s mancante
invalid_signature 401 La firma non corrisponde

🎯 Casi d’uso

Articoli del blog

Genera immagini OG dinamiche per gli articoli del blog:

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

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

Prodotti e-commerce

Crea immagini OG per le pagine prodotto:

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

Testimonianze

Genera immagini OG per le citazioni delle testimonianze:

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

🔐 Sicurezza

Buone pratiche

  1. Conserva le chiavi in modo sicuro — Usa variabili d'ambiente o un gestore di segreti
  2. Non esporre mai il segreto HMAC nel codice lato client — Firma solo sul server
  3. Usa HTTPS — Previene gli attacchi MITM
  4. Ruota i segreti periodicamente — Soprattutto se compromessi
  5. Monitora le firme fallite — Fallimenti ripetuti possono indicare attacchi
  6. Isolamento per utente — Ogni chiave API ha il proprio segreto HMAC

Ottenere il tuo segreto HMAC

  1. Vai su Dashboard → Chiavi API
  2. Crea una nuova chiave API
  3. Copia il Segreto HMAC (mostrato solo una volta!)
  4. Salvalo nelle variabili d'ambiente
bash
# .env
FASTOG_HMAC_SECRET=<your-64-char-hex-secret>

🧪 Test

Genera URL di 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);
"

Test con curl

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

Risposte attese

  • ✅ Firma valida → Restituisce l’immagine OG (o 422 se i parametri del template non sono validi)
  • ❌ Firma non valida → {"code": "invalid_signature"}
  • ❌ Parametri mancanti → {"code": "missing_signature"}

🛠 Risoluzione dei problemi

La firma non corrisponde

  1. Verifica di utilizzare il segreto HMAC corretto (controlla la chiave API nella dashboard)
  2. Controlla la query canonica: ogni parametro di query tranne s (incluso key), valori codificati secondo rfc3986, chiavi ordinate lessicograficamente
  3. Verifica che la firma sia in esadecimale minuscolo (64 caratteri)

📖 Risorse aggiuntive

❓ FAQ

D: Perché parametri di query invece di header?
R: Le immagini OG vengono recuperate dai crawler dei social network (LinkedIn, Twitter, Facebook) che non inviano header personalizzati. La firma DEVE essere nell'URL.

D: Posso usare la stessa firma per più richieste?
R: Sì. Una firma viene calcolata dalla query esatta (meno s), quindi lo stesso URL firmato rimane valido finché i parametri non cambiano. Se modifichi un qualsiasi parametro (incluso key), devi rifirmare.

D: Devo firmare le richieste per tutti i template?
R: Sì. Tutte le richieste a /api/v1/og richiedono firme HMAC.

D: Cosa succede se il mio segreto HMAC viene compromesso?
R: Revoca la chiave API nella dashboard e creane una nuova. Ogni chiave API ha il proprio segreto HMAC.

D: Posso disabilitare la validazione HMAC per i servizi interni?
R: Contatta il supporto per soluzioni personalizzate. La validazione HMAC è obbligatoria per tutti gli endpoint API pubblici.

🆘 Supporto

Hai bisogno di aiuto?

Provalo gratis — nessuna registrazione richiesta

Anteprima e test delle immagini OG dinamiche in pochi secondi.

Apri il tester gratuito di immagini OG
LocaFile AI AI localization for games, apps, subtitles & sites SubtoVTT Convert & clean subtitle files BeCaSimulations Indie game studio

A BeCaSimulations site