HMAC-Authentifizierung & Sicherheit

Sichern Sie Ihre HMAC-signierten OG-Bild-URLs mit der HMAC-SHA256-Authentifizierung von FastOG. Dieser Leitfaden behandelt das Signieren, Validieren und Beheben von Problemen bei jeder Anfrage, sodass Sie dynamische Open-Graph-Bilder im Handumdrehen bereitstellen können – abonnementbasiert, mit unbegrenzten Renderings (kein monatliches Render-Kontingent und keine Übernutzungsabrechnung). Melden Sie sich an, wählen Sie einen Dynamic-API-Plan und erstellen Sie anschließend Ihren API-Schlüssel und Ihr HMAC-Geheimnis im Dashboard (bezahlte API-Renderings sind sauber). Signieren Sie einmal auf Ihrem Server und integrieren Sie es in wenigen Minuten.

🚀 Schnellstart

Neu bei der HMAC-Signierung? Beginnen Sie hier:

1. Schnellstart-Anleitung — In 5 Minuten einsatzbereit
2. JavaScript-Tutorial — Vollständiger Leitfaden für Node.js/Next.js-Entwickler
3. Alle Framework-Tutorials — wählen Sie Ihren Stack:
   • Next.js App Router
   • Next.js Pages Router
   • React
   • SvelteKit
   • Vue/Nuxt
   • Astro
   • Express
   • Vanilla Node.js
   • JavaScript
   • PHP/Laravel
   • Python
   • Ruby/Rails

📚 Dokumentationsindex

Grundkonzepte

• HMAC-Signatur-Leitfaden — Vollständige Referenz mit Algorithmusdetails, Anforderungen und Beispielen in JavaScript, PHP und Python
• HMAC-Validierung — Serverseitige Implementierungsdetails, Sicherheitsfunktionen und Fehlerantworten

Tutorials

• JavaScript/Node.js-Tutorial — Umfassender Leitfaden mit:

  • Schnellstart (5 Minuten)
  • Next.js App Router (3 Muster)
  • Next.js Pages Router
  • Express.js-Backend
  • Vanilla Node.js
  • Frontend-Integrationsmuster (SSG, SSR, Client-seitig)
  • Testen und Debugging
  • Häufige Fallstricke

• Next.js App Router

• Next.js Pages Router

• React

• SvelteKit

• Vue/Nuxt

• Astro

• Express

• Vanilla Node.js

• PHP/Laravel

• Python

• Ruby/Rails

Kurzreferenz

Algorithmus

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>

Abfrageparameter

Fehlercodes

🎯 Anwendungsfälle

Blogbeiträge

Dynamische OG-Bilder für Blogbeiträge generieren:

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

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

E-Commerce-Produkte

OG-Bilder für Produktseiten erstellen:

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

Kundenstimmen

OG-Bilder für Testimonial-Zitate generieren:

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

🔐 Sicherheit

Bewährte Methoden

1. Geheimnisse sicher speichern — Verwenden Sie Umgebungsvariablen oder einen Secrets Manager
2. HMAC-Geheimnis niemals im clientseitigen Code offenlegen — Signieren Sie nur auf dem Server
3. HTTPS verwenden — Verhindert MITM-Angriffe
4. Geheimnisse regelmäßig rotieren — Insbesondere bei Kompromittierung
5. Fehlgeschlagene Signaturen überwachen — Wiederholte Fehler können auf Angriffe hindeuten
6. Isolation pro Benutzer — Jeder API-Schlüssel hat sein eigenes HMAC-Geheimnis

So erhalten Sie Ihr HMAC-Geheimnis

1. Gehen Sie zu Dashboard → API-Schlüssel
2. Erstellen Sie einen neuen API-Schlüssel
3. Kopieren Sie das HMAC-Geheimnis (wird nur einmal angezeigt!)
4. Speichern Sie es in Umgebungsvariablen

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

🧪 Testen

Test-URL generieren

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

Mit curl testen

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

Erwartete Antworten

• ✅ Gültige Signatur → Gibt ein OG-Bild zurück (oder 422, wenn die Vorlagenparameter ungültig sind)
• ❌ Ungültige Signatur → {"code": "invalid_signature"}
• ❌ Fehlende Parameter → {"code": "missing_signature"}

🛠 Fehlerbehebung

Signatur stimmt nicht überein

1. Vergewissern Sie sich, dass Sie das korrekte HMAC-Geheimnis verwenden (prüfen Sie den API-Schlüssel im Dashboard)
2. Überprüfen Sie die kanonische Abfrage: jeder Abfrageparameter außer s (einschließlich key), Werte rfc3986-kodiert, Schlüssel lexikografisch sortiert
3. Stellen Sie sicher, dass die Signatur ein hexadezimaler Kleinbuchstabenwert ist (64 Zeichen)

📖 Zusätzliche Ressourcen

• API-Referenz — Vollständige API-Dokumentation
• Sicherheits-Best Practices — Ausführlicher Sicherheitsleitfaden
• Wissensdatenbank — Technische Implementierungsdetails

❓ FAQ

F: Warum Abfrageparameter anstelle von Headern?
A: OG-Bilder werden von Crawlern sozialer Netzwerke (LinkedIn, Twitter, Facebook) abgerufen, die keine benutzerdefinierten Header senden. Die Signatur MUSS in der URL enthalten sein.

F: Kann ich dieselbe Signatur für mehrere Anfragen verwenden?
A: Ja. Eine Signatur wird aus der exakten Abfrage (abzüglich s) berechnet, sodass dieselbe signierte URL gültig bleibt, solange sich die Parameter nicht ändern. Wenn Sie einen Parameter (einschließlich key) ändern, müssen Sie neu signieren.

F: Muss ich Anfragen für alle Vorlagen signieren?
A: Ja. Alle Anfragen an /api/v1/og erfordern HMAC-Signaturen.

F: Was passiert, wenn mein HMAC-Geheimnis kompromittiert wird?
A: Widerrufen Sie den API-Schlüssel im Dashboard und erstellen Sie einen neuen. Jeder API-Schlüssel hat sein eigenes HMAC-Geheimnis.

F: Kann ich die HMAC-Validierung für interne Dienste deaktivieren?
A: Kontaktieren Sie den Support für individuelle Lösungen. Die HMAC-Validierung ist für alle öffentlichen API-Endpunkte verpflichtend.

🆘 Support

Benötigen Sie Hilfe?

• Sehen Sie sich das JavaScript-Tutorial für vollständige Codebeispiele an
• Lesen Sie den HMAC-Signatur-Leitfaden für Details zum Algorithmus
• Kontaktieren Sie den Support unter [email protected]

Verwandte Themen

• Dokumentation — Alle FastOG-Anleitungen und Referenzen
• Kostenloser OG-Bild-Tester — Vorschau ohne Konto
• Schnellstart-Anleitung — In 5 Minuten einsatzbereit
• HMAC-Signatur-Anleitung — Algorithmus-Details
• HMAC-Validierung — Serverseitige Validierung