Autentikasi & Keamanan HMAC

Amankan URL gambar OG yang ditandatangani HMAC Anda dengan autentikasi HMAC-SHA256 dari FastOG. Panduan ini mencakup penandatanganan, validasi, dan pemecahan masalah untuk setiap permintaan, sehingga Anda dapat mengirimkan gambar Open Graph dinamis dengan cepat — dibatasi oleh langganan, dengan render tanpa batas (tanpa kuota render bulanan dan tanpa tagihan berlebih). Daftar, pilih paket Dynamic API, lalu buat kunci API dan rahasia HMAC Anda di dasbor (render API berbayar bersih). Tandatangani di server Anda sekali dan integrasikan dalam hitungan menit.

🚀 Mulai Cepat

Baru mengenal penandaan HMAC? Mulai dari sini:

1. Panduan Mulai Cepat — Siap digunakan dalam 5 menit
2. Tutorial JavaScript — Panduan lengkap untuk pengembang Node.js/Next.js
3. Semua tutorial framework — pilih tumpukan teknologi Anda:
   • Next.js App Router
   • Next.js Pages Router
   • React
   • SvelteKit
   • Vue/Nuxt
   • Astro
   • Express
   • Node.js murni
   • JavaScript
   • PHP/Laravel
   • Python
   • Ruby/Rails

📚 Indeks Dokumentasi

Konsep Inti

• Panduan Tanda Tangan HMAC — Referensi lengkap dengan detail algoritma, persyaratan, dan contoh dalam JavaScript, PHP, dan Python
• Validasi HMAC — Detail implementasi sisi server, fitur keamanan, dan respons kesalahan

Tutorial

• Tutorial JavaScript/Node.js — Panduan komprehensif yang mencakup:

  • Memulai Cepat (5 menit)
  • Next.js App Router (3 pola)
  • Next.js Pages Router
  • Backend Express.js
  • Node.js Murni
  • Pola Integrasi Frontend (SSG, SSR, Client-Side)
  • Pengujian & Debugging
  • Kesalahan Umum

• Next.js App Router

• Next.js Pages Router

• React

• SvelteKit

• Vue/Nuxt

• Astro

• Express

• Node.js Murni

• PHP/Laravel

• Python

• Ruby/Rails

Referensi Cepat

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>

Parameter Kueri

Kode Kesalahan

🎯 Kasus Penggunaan

Postingan Blog

Hasilkan gambar OG dinamis untuk postingan blog:

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

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

Produk E-commerce

Buat gambar OG untuk halaman produk:

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

Testimoni

Hasilkan gambar OG untuk kutipan testimoni:

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

🔐 Keamanan

Praktik Terbaik

1. Simpan rahasia dengan aman — Gunakan variabel lingkungan (environment variables) atau pengelola rahasia (secrets manager)
2. Jangan pernah mengekspos rahasia HMAC di kode sisi klien — Tandatangani hanya di server
3. Gunakan HTTPS — Mencegah serangan MITM
4. Rotasi rahasia secara berkala — Terutama jika telah disusupi
5. Pantau tanda tangan yang gagal — Kegagalan berulang dapat mengindikasikan serangan
6. Isolasi per pengguna — Setiap kunci API memiliki rahasia HMAC sendiri

Mendapatkan Rahasia HMAC Anda

1. Buka Dasbor → Kunci API
2. Buat kunci API baru
3. Salin Rahasia HMAC (hanya ditampilkan sekali!)
4. Simpan dalam variabel lingkungan

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

🧪 Pengujian

Membuat URL Pengujian

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

Menguji dengan curl

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

Respons yang Diharapkan

• ✅ Tanda tangan valid → Mengembalikan gambar OG (atau 422 jika parameter template tidak valid)
• ❌ Tanda tangan tidak valid → {"code": "invalid_signature"}
• ❌ Parameter tidak ada → {"code": "missing_signature"}

🛠 Pemecahan Masalah

Tanda tangan tidak cocok

1. Pastikan Anda menggunakan rahasia HMAC yang benar (periksa kunci API di dasbor)
2. Periksa kueri kanonis: setiap parameter kueri kecuali s (termasuk key), nilai dienkode dengan rfc3986, kunci diurutkan secara leksikografis
3. Pastikan tanda tangan berupa heksadesimal huruf kecil (64 karakter)

📖 Sumber Daya Tambahan

• Referensi API — Dokumentasi API lengkap
• Praktik Terbaik Keamanan — Panduan keamanan terperinci
• Basis Pengetahuan — Detail implementasi teknis

❓ FAQ

T: Mengapa menggunakan parameter kueri, bukan header?
J: Gambar OG diambil oleh perayap jaringan sosial (LinkedIn, Twitter, Facebook) yang tidak mengirim header kustom. Tanda tangan HARUS berada di URL.

T: Bisakah saya menggunakan tanda tangan yang sama untuk beberapa permintaan?
J: Ya. Tanda tangan dihitung dari kueri yang tepat (tanpa s), sehingga URL yang ditandatangani tetap valid selama parameternya tidak berubah. Ubah parameter apa pun (termasuk key) dan Anda harus menandatangani ulang.

T: Apakah saya perlu menandatangani permintaan untuk semua template?
J: Ya. Semua permintaan ke /api/v1/og memerlukan tanda tangan HMAC.

T: Apa yang terjadi jika rahasia HMAC saya bocor?
J: Cabut kunci API di dasbor dan buat yang baru. Setiap kunci API memiliki rahasia HMAC sendiri.

T: Bisakah saya menonaktifkan validasi HMAC untuk layanan internal?
J: Hubungi dukungan untuk solusi kustom. Validasi HMAC wajib untuk semua endpoint API publik.

🆘 Dukungan

Butuh bantuan?

• Lihat Tutorial JavaScript untuk contoh kode lengkap
• Tinjau Panduan Tanda Tangan HMAC untuk detail algoritma
• Hubungi dukungan di [email protected]

Terkait

• Dokumentasi — Semua panduan dan referensi FastOG
• Penguji Gambar OG Gratis — Pratinjau tanpa akun
• Panduan Memulai Cepat — Mulai berjalan dalam 5 menit
• Panduan Tanda Tangan HMAC — Detail algoritma
• Validasi HMAC — Validasi sisi server