Uwierzytelnianie HMAC i bezpieczeństwo

Zabezpiecz swoje adresy URL obrazów OG podpisane HMAC za pomocą uwierzytelniania HMAC-SHA256 w FastOG. Ten przewodnik obejmuje podpisywanie, weryfikację i rozwiązywanie problemów z każdym żądaniem, dzięki czemu możesz dostarczać dynamiczne obrazy Open Graph na bieżąco — ograniczone subskrypcją, z nielimitowanymi renderami (bez miesięcznego limitu renderów i bez naliczania opłat za przekroczenie). Zarejestruj się, wybierz plan Dynamic API, a następnie utwórz klucz API i sekret HMAC w panelu (płatne rendery API są czyste). Podpisz po stronie serwera raz i zintegruj w kilka minut.

🚀 Szybki start

Dopiero zaczynasz z podpisywaniem HMAC? Zacznij tutaj:

1. Przewodnik szybkiego startu — Wystartuj w 5 minut
2. Samouczek JavaScript — Kompletny przewodnik dla programistów Node.js/Next.js
3. Wszystkie samouczki frameworków — wybierz swój stos technologiczny:
   • Next.js App Router
   • Next.js Pages Router
   • React
   • SvelteKit
   • Vue/Nuxt
   • Astro
   • Express
   • Czysty Node.js
   • JavaScript
   • PHP/Laravel
   • Python
   • Ruby/Rails

📚 Indeks dokumentacji

Podstawowe koncepcje

• Przewodnik po sygnaturze HMAC — Pełna referencja ze szczegółami algorytmu, wymaganiami oraz przykładami w JavaScript, PHP i Python
• Walidacja HMAC — Szczegóły implementacji po stronie serwera, funkcje bezpieczeństwa i odpowiedzi błędów

Samouczki

• Samouczek JavaScript/Node.js — Obszerny przewodnik obejmujący:

  • Szybki start (5 minut)
  • Next.js App Router (3 wzorce)
  • Next.js Pages Router
  • Backend Express.js
  • Czysty Node.js
  • Wzorce integracji frontendu (SSG, SSR, po stronie klienta)
  • Testowanie i debugowanie
  • Częste pułapki

• Next.js App Router

• Next.js Pages Router

• React

• SvelteKit

• Vue/Nuxt

• Astro

• Express

• Czysty Node.js

• PHP/Laravel

• Python

• Ruby/Rails

Szybka referencja

Algorytm

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 zapytania

Kody błędów

🎯 Przykłady zastosowań

Wpisy na blogu

Generowanie dynamicznych obrazów OG dla wpisów na blogu:

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

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

Produkty w sklepie internetowym

Tworzenie obrazów OG dla stron produktów:

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

Opinie klientów

Generowanie obrazów OG dla cytatów z opinii:

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

🔐 Bezpieczeństwo

Najlepsze praktyki

1. Przechowuj sekrety bezpiecznie — używaj zmiennych środowiskowych lub menedżera sekretów
2. Nigdy nie ujawniaj sekretu HMAC w kodzie po stronie klienta — podpisuj wyłącznie po stronie serwera
3. Używaj HTTPS — zapobiega atakom typu MITM
4. Rotuj sekrety okresowo — zwłaszcza jeśli zostały skompromitowane
5. Monitoruj nieudane podpisy — powtarzające się błędy mogą wskazywać na ataki
6. Izolacja per użytkownik — każdy klucz API ma własny sekret HMAC

Uzyskanie sekretu HMAC

1. Przejdź do Dashboard → API Keys
2. Utwórz nowy klucz API
3. Skopiuj HMAC Secret (pokazywany tylko raz!)
4. Zapisz w zmiennych środowiskowych

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

🧪 Testowanie

Generowanie adresu URL testowego

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

Testowanie za pomocą curl

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

Oczekiwane odpowiedzi

• ✅ Prawidłowy podpis → Zwraca obraz OG (lub 422, jeśli parametry szablonu są nieprawidłowe)
• ❌ Nieprawidłowy podpis → {"code": "invalid_signature"}
• ❌ Brakujące parametry → {"code": "missing_signature"}

🛠 Rozwiązywanie problemów

Podpis nie pasuje

1. Sprawdź, czy używasz prawidłowego sekretu HMAC (sprawdź klucz API w panelu)
2. Sprawdź kanoniczne zapytanie: każdy parametr zapytania oprócz s (w tym key), wartości zakodowane zgodnie z rfc3986, klucze posortowane leksykograficznie
3. Sprawdź, czy podpis jest zapisany małymi literami w formacie szesnastkowym (64 znaki)

📖 Dodatkowe zasoby

• Dokumentacja API — Pełna dokumentacja API
• Najlepsze praktyki bezpieczeństwa — Szczegółowy przewodnik po bezpieczeństwie
• Baza wiedzy — Szczegóły techniczne implementacji

❓ FAQ

P: Dlaczego parametry zapytania zamiast nagłówków?
O: Obrazy OG są pobierane przez roboty sieci społecznościowych (LinkedIn, Twitter, Facebook), które nie wysyłają niestandardowych nagłówków. Podpis MUSI znajdować się w URL.

P: Czy mogę użyć tego samego podpisu dla wielu żądań?
O: Tak. Podpis jest obliczany na podstawie dokładnego zapytania (minus s), więc ten sam podpisany URL pozostaje ważny, dopóki parametry się nie zmienią. Zmiana dowolnego parametru (w tym key) wymaga ponownego podpisania.

P: Czy muszę podpisywać żądania dla wszystkich szablonów?
O: Tak. Wszystkie żądania do /api/v1/og wymagają podpisów HMAC.

P: Co się stanie, jeśli mój sekret HMAC zostanie ujawniony?
O: Unieważnij klucz API w panelu (dashboard) i utwórz nowy. Każdy klucz API ma własny sekret HMAC.

P: Czy mogę wyłączyć walidację HMAC dla usług wewnętrznych?
O: Skontaktuj się z supportem w sprawie rozwiązań niestandardowych. Walidacja HMAC jest obowiązkowa dla wszystkich publicznych endpointów API.

🆘 Wsparcie

Potrzebujesz pomocy?

• Sprawdź Samouczek JavaScript z pełnymi przykładami kodu
• Przejrzyj Przewodnik po podpisach HMAC ze szczegółami algorytmu
• Skontaktuj się z wsparciem pod adresem [email protected]

Powiązane

• Dokumentacja — Wszystkie przewodniki i referencje FastOG
• Darmowy tester obrazów OG — Podgląd bez konta
• Przewodnik szybkiego startu — Zacznij w 5 minut
• Przewodnik po podpisach HMAC — Szczegóły algorytmu
• Walidacja HMAC — Walidacja po stronie serwera