Authentification HMAC et sécurité

Sécurisez vos URL d’images OG signées HMAC avec l’authentification HMAC-SHA256 de FastOG. Ce guide couvre la signature, la validation et le dépannage de chaque requête, afin que vous puissiez générer des images Open Graph dynamiques à la volée — avec contrôle par abonnement et rendus sans limite (aucun quota mensuel de rendus ni facturation de dépassement). Inscrivez-vous, choisissez un plan Dynamic API, puis créez votre clé API et votre secret HMAC dans le tableau de bord (les rendus API payants sont propres). Signez une fois sur votre serveur et intégrez en quelques minutes.

🚀 Démarrage rapide

Nouveau dans la signature HMAC ? Commencez ici :

1. Guide de démarrage rapide — Lancez-vous en 5 minutes
2. Tutoriel JavaScript — Guide complet pour les développeurs Node.js/Next.js
3. Tous les tutoriels par framework — choisissez votre pile :
   • Next.js App Router
   • Next.js Pages Router
   • React
   • SvelteKit
   • Vue/Nuxt
   • Astro
   • Express
   • Node.js natif
   • JavaScript
   • PHP/Laravel
   • Python
   • Ruby/Rails

📚 Index de la documentation

Concepts fondamentaux

• Guide de signature HMAC — Référence complète avec détails sur l’algorithme, les exigences et des exemples en JavaScript, PHP et Python
• Validation HMAC — Détails d’implémentation côté serveur, fonctionnalités de sécurité et réponses d’erreur

Tutoriels

• Tutoriel JavaScript/Node.js — Guide complet couvrant :

  • Démarrage rapide (5 minutes)
  • Next.js App Router (3 modèles)
  • Next.js Pages Router
  • Backend Express.js
  • Node.js natif
  • Modèles d’intégration frontend (SSG, SSR, côté client)
  • Tests et débogage
  • Pièges courants

• Next.js App Router

• Next.js Pages Router

• React

• SvelteKit

• Vue/Nuxt

• Astro

• Express

• Node.js natif

• PHP/Laravel

• Python

• Ruby/Rails

Référence rapide

Algorithme

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>

Paramètres de requête

Codes d’erreur

🎯 Cas d’utilisation

Articles de blog

Générez des images OG dynamiques pour les articles de blog :

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

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

Produits e-commerce

Créez des images OG pour les pages produits :

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

Témoignages

Générez des images OG pour les citations de témoignages :

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

🔐 Sécurité

Bonnes pratiques

1. Stockez les secrets de manière sécurisée — Utilisez des variables d'environnement ou un gestionnaire de secrets
2. N'exposez jamais le secret HMAC dans le code côté client — Signez uniquement côté serveur
3. Utilisez HTTPS — Empêche les attaques de type MITM
4. Faites pivoter les secrets périodiquement — Surtout en cas de compromission
5. Surveillez les signatures échouées — Des échecs répétés peuvent indiquer des attaques
6. Isolation par utilisateur — Chaque clé API possède son propre secret HMAC

Obtenir votre secret HMAC

1. Allez dans Tableau de bord → Clés API
2. Créez une nouvelle clé API
3. Copiez le Secret HMAC (affiché une seule fois !)
4. Stockez-le dans les variables d'environnement

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

🧪 Tests

Générer une URL de test

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

Tester avec curl

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

Réponses attendues

• ✅ Signature valide → Renvoie l’image OG (ou 422 si les paramètres du template sont invalides)
• ❌ Signature invalide → {"code": "invalid_signature"}
• ❌ Paramètres manquants → {"code": "missing_signature"}

🛠 Dépannage

La signature ne correspond pas

1. Vérifiez que vous utilisez le bon secret HMAC (consultez la clé API dans le tableau de bord)
2. Vérifiez la requête canonique : chaque paramètre de requête sauf s (y compris key), valeurs encodées en rfc3986, clés triées par ordre lexicographique
3. Vérifiez que la signature est en hexadécimal minuscule (64 caractères)

📖 Ressources complémentaires

• Référence API — Documentation complète de l’API
• Bonnes pratiques de sécurité — Guide de sécurité détaillé
• Base de connaissances — Détails techniques d’implémentation

❓ FAQ

Q : Pourquoi des paramètres de requête plutôt que des en-têtes ?
R : Les images OG sont récupérées par les robots des réseaux sociaux (LinkedIn, Twitter, Facebook) qui n'envoient pas d'en-têtes personnalisés. La signature DOIT figurer dans l'URL.

Q : Puis-je utiliser la même signature pour plusieurs requêtes ?
R : Oui. Une signature est calculée à partir de la requête exacte (moins s), donc la même URL signée reste valide tant que les paramètres ne changent pas. Modifiez un paramètre (y compris key) et vous devez re-signer.

Q : Dois-je signer les requêtes pour tous les modèles ?
R : Oui. Toutes les requêtes vers /api/v1/og exigent des signatures HMAC.

Q : Que se passe-t-il si mon secret HMAC est compromis ?
R : Révoquez la clé API dans le tableau de bord et créez-en une nouvelle. Chaque clé API possède son propre secret HMAC.

Q : Puis-je désactiver la validation HMAC pour les services internes ?
R : Contactez le support pour des solutions personnalisées. La validation HMAC est obligatoire pour tous les points de terminaison publics de l'API.

🆘 Support

Besoin d’aide ?

• Consultez le tutoriel JavaScript pour des exemples de code complets
• Revoyez le guide des signatures HMAC pour les détails de l’algorithme
• Contactez le support à [email protected]

Rubriques connexes

• Documentation — Tous les guides et références FastOG
• Testeur d’image OG gratuit — Aperçu sans compte
• Guide de démarrage rapide — Prise en main en 5 minutes
• Guide de signature HMAC — Détails de l’algorithme
• Validation HMAC — Validation côté serveur