HMAC Kimlik Doğrulama ve Güvenlik

HMAC imzalı OG görsel URL'lerinizi FastOG'un HMAC-SHA256 kimlik doğrulamasıyla koruyun. Bu kılavuz, her isteğin imzalanması, doğrulanması ve sorun giderme süreçlerini kapsar; böylece dinamik Open Graph görsellerini anında yayınlayabilirsiniz — abonelik tabanlı, sınırsız işleme (aylık işleme kotası veya aşım faturalandırması yok). Kaydolun, bir Dynamic API planı seçin, ardından panelde API anahtarınızı ve HMAC gizli anahtarınızı oluşturun (ücretli API işlemeleri temizdir). Sunucunuzda bir kez imzalayın ve dakikalar içinde entegre edin.

🚀 Hızlı Başlangıç

HMAC imzalamada yeni misiniz? Buradan başlayın:

1. Hızlı Başlangıç Rehberi — 5 dakikada çalışır duruma gelin
2. JavaScript Eğitimi — Node.js/Next.js geliştiricileri için eksiksiz rehber
3. Tüm framework eğitimleri — kendi yığınınızı seçin:
   • Next.js App Router
   • Next.js Pages Router
   • React
   • SvelteKit
   • Vue/Nuxt
   • Astro
   • Express
   • Saf Node.js
   • JavaScript
   • PHP/Laravel
   • Python
   • Ruby/Rails

📚 Dokümantasyon Dizini

Temel Kavramlar

• HMAC İmza Kılavuzu — Algoritma ayrıntıları, gereksinimler ve JavaScript, PHP ile Python örneklerini içeren eksiksiz referans
• HMAC Doğrulama — Sunucu tarafı uygulama ayrıntıları, güvenlik özellikleri ve hata yanıtları

Eğiticiler

• JavaScript/Node.js Eğiticisi — Kapsamlı kılavuz şunları kapsar:

  • Hızlı Başlangıç (5 dakika)
  • Next.js App Router (3 desen)
  • Next.js Pages Router
  • Express.js Backend
  • Saf Node.js
  • Ön Uç Entegrasyon Desenleri (SSG, SSR, İstemci Tarafı)
  • Test ve Hata Ayıklama
  • Sık Karşılaşılan Tuzaklar

• Next.js App Router

• Next.js Pages Router

• React

• SvelteKit

• Vue/Nuxt

• Astro

• Express

• Saf Node.js

• PHP/Laravel

• Python

• Ruby/Rails

Hızlı Referans

Algoritma

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>

Sorgu Parametreleri

Hata Kodları

🎯 Kullanım Senaryoları

Blog Yazıları

Blog yazıları için dinamik OG görselleri oluşturun:

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

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

E-ticaret Ürünleri

Ürün sayfaları için OG görselleri oluşturun:

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

Müşteri Yorumları

Müşteri yorumları için OG görselleri oluşturun:

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

🔐 Güvenlik

En İyi Uygulamalar

1. Sırları güvenli şekilde saklayın — Ortam değişkenleri veya sır yöneticisi kullanın
2. HMAC sırrını asla istemci tarafı kodda açığa çıkarmayın — Yalnızca sunucuda imzalayın
3. HTTPS kullanın — MITM saldırılarını önler
4. Sırları periyodik olarak döndürün — Özellikle tehlikeye girerse
5. Başarısız imzaları izleyin — Tekrarlanan başarısızlıklar saldırıya işaret edebilir
6. Kullanıcı başına izolasyon — Her API anahtarının kendi HMAC sırrı vardır

HMAC Sırrınızı Alma

1. Panel → API Anahtarları bölümüne gidin
2. Yeni bir API anahtarı oluşturun
3. HMAC Sırrını kopyalayın (yalnızca bir kez gösterilir!)
4. Ortam değişkenlerinde saklayın

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

🧪 Test Etme

Test URL’si Oluşturma

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

curl ile Test Etme

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

Beklenen Yanıtlar

• ✅ Geçerli imza → OG görselini döndürür (şablon parametreleri geçersizse 422 döndürür)
• ❌ Geçersiz imza → {"code": "invalid_signature"}
• ❌ Eksik parametreler → {"code": "missing_signature"}

🛠 Sorun Giderme

İmza eşleşmiyor

1. Doğru HMAC gizli anahtarını kullandığınızı doğrulayın (panodaki API anahtarını kontrol edin)
2. Kanonik sorguyu kontrol edin: s hariç tüm sorgu parametreleri (key dahil), değerler rfc3986 kodlu, anahtarlar sözlükbilimsel olarak sıralanmış
3. İmzanın küçük harfli onaltılık (hex) olduğunu doğrulayın (64 karakter)

📖 Ek Kaynaklar

• API Referansı — Eksiksiz API dokümantasyonu
• Güvenlik En İyi Uygulamaları — Ayrıntılı güvenlik rehberi
• Bilgi Tabanı — Teknik uygulama ayrıntıları

❓ SSS

S: Neden başlıklar yerine sorgu parametreleri?
C: OG görselleri, özel başlık göndermeyen sosyal ağ tarayıcıları (LinkedIn, Twitter, Facebook) tarafından getirilir. İmza URL'de OLMALIDIR.

S: Aynı imzayı birden fazla istek için kullanabilir miyim?
C: Evet. Bir imza, tam sorgudan (s hariç) hesaplanır; bu nedenle parametreler değişmediği sürece aynı imzalı URL geçerli kalır. Herhangi bir parametreyi (key dahil) değiştirirseniz yeniden imzalamanız gerekir.

S: Tüm şablonlar için istekleri imzalamam gerekiyor mu?
C: Evet. /api/v1/og adresine yapılan tüm istekler HMAC imzası gerektirir.

S: HMAC gizli anahtarım tehlikeye girerse ne olur?
C: Panodan API anahtarını iptal edin ve yeni bir tane oluşturun. Her API anahtarının kendi HMAC gizli anahtarı vardır.

S: Dahili hizmetler için HMAC doğrulamasını devre dışı bırakabilir miyim?
C: Özel çözümler için destek ekibiyle iletişime geçin. HMAC doğrulaması tüm genel API uç noktaları için zorunludur.

🆘 Destek

Yardıma mı ihtiyacınız var?

• Tam kod örnekleri için JavaScript Eğitimi inceleyin
• Algoritma ayrıntıları için HMAC İmza Rehberi gözden geçirin
• [email protected] adresinden destek ekibiyle iletişime geçin

İlgili

• Dokümantasyon — Tüm FastOG rehberleri ve referansları
• Ücretsiz OG Görsel Test Aracı — Hesap olmadan önizleme
• Hızlı Başlangıç Rehberi — 5 dakikada çalışmaya başlayın
• HMAC İmza Rehberi — Algoritma detayları
• HMAC Doğrulama — Sunucu tarafı doğrulama