การรับรองความถูกต้อง HMAC และความปลอดภัย

รักษาความปลอดภัย URL รูปภาพ OG ที่ลงนามด้วย HMAC ด้วยการรับรองความถูกต้อง HMAC-SHA256 ของ FastOG คู่มือนี้ครอบคลุมการลงนาม การตรวจสอบ และการแก้ไขปัญหาทุกคำขอ เพื่อให้คุณสามารถส่งมอบรูปภาพ Open Graph แบบไดนามิกได้ทันที — จำกัดด้วยการสมัครสมาชิก พร้อมการเรนเดอร์แบบไม่จำกัดจำนวน (ไม่มีโควต้าการเรนเดอร์รายเดือนและไม่มีค่าใช้จ่ายเกินโควต้า) ลงทะเบียน เลือกแผน Dynamic API จากนั้นสร้างคีย์ API และ HMAC secret ในแดชบอร์ด (การเรนเดอร์ API แบบชำระเงินจะสะอาด) ลงนามบนเซิร์ฟเวอร์ของคุณเพียงครั้งเดียวและผสานรวมได้ภายในไม่กี่นาที

🚀 เริ่มต้นใช้งานอย่างรวดเร็ว

ยังไม่คุ้นเคยกับการลงนาม HMAC หรือไม่? เริ่มต้นที่นี่:

1. คู่มือเริ่มต้นใช้งานอย่างรวดเร็ว — เริ่มต้นใช้งานได้ภายใน 5 นาที
2. บทช่วยสอน JavaScript — คู่มือฉบับสมบูรณ์สำหรับนักพัฒนา Node.js/Next.js
3. บทช่วยสอนทุกเฟรมเวิร์ก — เลือกสแตกที่คุณใช้:
   • Next.js App Router
   • Next.js Pages Router
   • React
   • SvelteKit
   • Vue/Nuxt
   • Astro
   • Express
   • Vanilla Node.js
   • JavaScript
   • PHP/Laravel
   • Python
   • Ruby/Rails

📚 สารบัญเอกสาร

แนวคิดหลัก

• คู่มือ HMAC Signature — เอกสารอ้างอิงฉบับสมบูรณ์พร้อมรายละเอียดอัลกอริทึม ข้อกำหนด และตัวอย่างใน JavaScript, PHP และ Python
• การตรวจสอบ HMAC — รายละเอียดการใช้งานฝั่งเซิร์ฟเวอร์ คุณสมบัติด้านความปลอดภัย และการตอบสนองข้อผิดพลาด

บทช่วยสอน

• บทช่วยสอน JavaScript/Node.js — คู่มือฉบับสมบูรณ์ครอบคลุม:

  • เริ่มต้นใช้งานอย่างรวดเร็ว (5 นาที)
  • Next.js App Router (3 รูปแบบ)
  • Next.js Pages Router
  • Backend ด้วย Express.js
  • Vanilla Node.js
  • รูปแบบการผสานรวม Frontend (SSG, SSR, Client-Side)
  • การทดสอบและการดีบัก
  • ข้อผิดพลาดที่พบบ่อย

• Next.js App Router

• Next.js Pages Router

• React

• SvelteKit

• Vue/Nuxt

• Astro

• Express

• Vanilla Node.js

• PHP/Laravel

• Python

• Ruby/Rails

เอกสารอ้างอิงฉบับย่อ

อัลกอริทึม

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>

พารามิเตอร์ Query

รหัสข้อผิดพลาด

🎯 กรณีการใช้งาน

บทความบล็อก

สร้าง OG image แบบไดนามิกสำหรับบทความบล็อก:

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

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

สินค้าอีคอมเมิร์ซ

สร้าง OG image สำหรับหน้าสินค้า:

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

คำรับรองจากลูกค้า

สร้าง OG image สำหรับคำพูดรับรอง:

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

🔐 ความปลอดภัย

แนวทางปฏิบัติที่ดีที่สุด

1. จัดเก็บความลับอย่างปลอดภัย — ใช้ตัวแปรสภาพแวดล้อม (environment variables) หรือตัวจัดการความลับ (secrets manager)
2. ห้ามเปิดเผย HMAC secret ในโค้ดฝั่งไคลเอนต์ — ลงนามบนเซิร์ฟเวอร์เท่านั้น
3. ใช้ HTTPS — ป้องกันการโจมตีแบบ MITM
4. หมุนเวียนความลับเป็นระยะ — โดยเฉพาะหากมีการรั่วไหล
5. ตรวจสอบลายเซ็นที่ล้มเหลว — ความล้มเหลวซ้ำๆ อาจบ่งชี้ถึงการโจมตี
6. แยกตามผู้ใช้ — คีย์ API แต่ละคีย์มี HMAC secret ของตัวเอง

การรับ HMAC Secret ของคุณ

1. ไปที่ แดชบอร์ด → คีย์ API
2. สร้างคีย์ API ใหม่
3. คัดลอก HMAC Secret (แสดงเพียงครั้งเดียวเท่านั้น!)
4. จัดเก็บในตัวแปรสภาพแวดล้อม

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

🧪 การทดสอบ

สร้าง URL สำหรับทดสอบ

# 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

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

ผลลัพธ์ที่คาดหวัง

• ✅ ลายเซ็นที่ถูกต้อง → ส่งคืนรูปภาพ OG (หรือ 422 หากพารามิเตอร์เทมเพลตไม่ถูกต้อง)
• ❌ ลายเซ็นไม่ถูกต้อง → {"code": "invalid_signature"}
• ❌ พารามิเตอร์หายไป → {"code": "missing_signature"}

🛠 การแก้ไขปัญหา

ลายเซ็นไม่ตรงกัน

1. ตรวจสอบว่าคุณใช้ HMAC secret ที่ถูกต้อง (ตรวจสอบคีย์ API ในแดชบอร์ด)
2. ตรวจสอบ canonical query: พารามิเตอร์ query ทุกตัวยกเว้น s (รวมถึง key) ค่าต่างๆ ถูกเข้ารหัสแบบ rfc3986 และคีย์ถูกจัดเรียงตามลำดับตัวอักษร
3. ตรวจสอบว่าลายเซ็นเป็นเลขฐานสิบหกตัวพิมพ์เล็ก (64 ตัวอักษร)

📖 แหล่งข้อมูลเพิ่มเติม

• เอกสารอ้างอิง API — เอกสารประกอบ API ฉบับสมบูรณ์
• แนวปฏิบัติด้านความปลอดภัยที่ดีที่สุด — คู่มือความปลอดภัยโดยละเอียด
• ฐานความรู้ — รายละเอียดการนำไปใช้งานทางเทคนิค

❓ คำถามที่พบบ่อย

ถาม: ทำไมต้องใช้พารามิเตอร์ใน query แทนที่จะใช้ headers?
ตอบ: OG images ถูกดึงข้อมูลโดย crawler ของโซเชียลเน็ตเวิร์ก (LinkedIn, Twitter, Facebook) ซึ่งไม่ส่ง custom headers มาให้ ลายเซ็นจึงต้องอยู่ใน URL

ถาม: ฉันสามารถใช้ลายเซ็นเดียวกันสำหรับหลายคำขอได้หรือไม่?
ตอบ: ได้ ลายเซ็นถูกคำนวณจาก query ที่แน่นอน (ไม่รวม s) ดังนั้น URL ที่ลงนามแล้วจะยังคงใช้ได้ตราบใดที่พารามิเตอร์ไม่เปลี่ยนแปลง หากเปลี่ยนพารามิเตอร์ใดก็ตาม (รวมถึง key) คุณต้องลงนามใหม่

ถาม: ฉันจำเป็นต้องลงนามคำขอสำหรับทุกเทมเพลตหรือไม่?
ตอบ: ใช่ คำขอทั้งหมดไปยัง /api/v1/og จำเป็นต้องมีลายเซ็น HMAC

ถาม: จะเกิดอะไรขึ้นหาก HMAC secret ของฉันถูกเปิดเผย?
ตอบ: เพิกถอน API key ในแดชบอร์ดและสร้างใหม่ แต่ละ API key จะมี HMAC secret ของตัวเอง

ถาม: ฉันสามารถปิดการตรวจสอบ HMAC สำหรับบริการภายในได้หรือไม่?
ตอบ: ติดต่อฝ่ายสนับสนุนสำหรับโซลูชันที่กำหนดเอง การตรวจสอบ HMAC เป็นข้อบังคับสำหรับ endpoint API สาธารณะทั้งหมด

🆘 การสนับสนุน

ต้องการความช่วยเหลือหรือไม่?

• ดู บทช่วยสอน JavaScript สำหรับตัวอย่างโค้ดที่สมบูรณ์
• ทบทวน คู่มือลายเซ็น HMAC สำหรับรายละเอียดอัลกอริทึม
• ติดต่อฝ่ายสนับสนุนได้ที่ [email protected]

เกี่ยวข้อง

• เอกสารประกอบ — คู่มือและข้อมูลอ้างอิงทั้งหมดของ FastOG
• เครื่องมือทดสอบ OG Image ฟรี — ดูตัวอย่างโดยไม่ต้องมีบัญชี
• คู่มือเริ่มต้นใช้งาน — เริ่มต้นใช้งานภายใน 5 นาที
• คู่มือลายเซ็น HMAC — รายละเอียดอัลกอริทึม
• การตรวจสอบ HMAC — การตรวจสอบฝั่งเซิร์ฟเวอร์