FastOG
주제

HMAC 서명 가이드

이 HMAC 서명 가이드는 FastOG용 HMAC-SHA256 서명을 구축하는 방법을 안내합니다. 이를 통해 구독 기반으로 동적 Open Graph 이미지를 즉석에서 생성할 수 있으며, 무료 계정과 Dynamic API 요금제(유료 렌더링은 깔끔하게 처리됨)가 포함됩니다. 여기서 어떤 언어로든 서명을 직접 작성하거나, 무료 OG 이미지 테스터를 사용하여 URL 형식을 먼저 확인할 수 있습니다.

개요

/api/v1/og에 대한 모든 요청에는 정식 웹사이트에서 발송되었음을 증명하는 HMAC-SHA256 서명이 포함되어야 합니다. 이를 통해 승인되지 않은 제3자가 사용자의 API 할당량을 사용하는 것을 방지할 수 있습니다.

인증의 두 계층:

  1. API 키 (쿼리 내: key=sk_quick_123abc) — 사용자 계정을 식별합니다 (렌더 할당량 계산용)
  2. HMAC 서명 (쿼리 내: s=<signature>) — 요청이 사용자의 웹사이트에서 왔음을 증명합니다

두 가지 모두 통과해야 합니다. API 키만으로는 충분하지 않습니다.

왜 쿼리 매개변수인가? OG 이미지는 사용자 정의 헤더를 전송하지 않는 소셜 네트워크 크롤러(LinkedIn, Twitter, Facebook)에 의해 가져와집니다. 서명은 반드시 URL에 포함되어야 합니다.

서명 생성

알고리즘

method = "GET"
path = "/api/v1/og"
canonicalQuery = for every query param EXCEPT `s` (including `key`):
  - array values are 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))

Query parameters:
  key=<apiKey>
  s=<signature>

요구 사항

  • 서명 형식: 64자 16진수 문자열(SHA256)
  • hash_equals() 사용: 상수 시간 비교를 위해 사용(타이밍 공격 방지)
  • 사용자별 비밀 키: 각 API 키는 고유한 hmac_secret 필드를 가집니다.

예제 구현

여러 프레임워크와 패턴에 대한 전체 튜토리얼은 다음을 참조하세요:

JavaScript (Node.js / 프론트엔드)

javascript
const crypto = require("crypto");

// rfc3986-encode: everything except A-Za-z0-9-._~
const enc = (s) =>
    encodeURIComponent(s).replace(
        /[!'()*]/g,
        (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase(),
    );

function generateOgImageUrl(baseUrl, params, apiKey, hmacSecret) {
    // every query param except `s`; key included; arrays expand to one pair each
    const all = { ...params, key: apiKey };
    const pairs = [];
    for (const [k, v] of Object.entries(all)) {
        for (const vv of Array.isArray(v) ? [...v].sort() : [v]) {
            pairs.push(`${enc(k)}=${enc(vv)}`);
        }
    }
    pairs.sort();
    const canonical = pairs.join("&");

    const signature = crypto
        .createHmac("sha256", hmacSecret)
        .update(`GET/api/v1/og\n${canonical}`)
        .digest("hex");

    const url = new URL(baseUrl);
    for (const [k, v] of Object.entries(all)) {
        const isArray = Array.isArray(v);
        for (const vv of isArray ? v : [v]) {
            url.searchParams.append(isArray ? `${k}[]` : k, vv);
        }
    }
    url.searchParams.set("s", signature);
    return url.toString();
}

// Usage in meta tag:
const ogUrl = generateOgImageUrl(
    "https://fastog.com/api/v1/og",
    { title: "Como criar um SaaS", template: "default" },
    "sk_quick_123abc",
    process.env.HMAC_SECRET,
);

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

PHP (Laravel)

php
function generateOgImageUrl(string $baseUrl, array $params, string $apiKey, string $hmacSecret): string
{
    // every query param except `s`; key included; array values sorted too
    $all = array_merge($params, ['key' => $apiKey]);

    $pairs = [];
    foreach ($all as $k => $v) {
        $values = is_array($v) ? $v : [$v];
        sort($values, SORT_STRING);
        foreach ($values as $vv) {
            $pairs[] = rawurlencode((string)$k) . '=' . rawurlencode((string)$vv);
        }
    }
    sort($pairs, SORT_STRING);
    $canonical = implode('&', $pairs);

    $signature = hash_hmac('sha256', 'GET/api/v1/og' . "\n" . $canonical, $hmacSecret);

    // URL uses bracket keys for arrays (features[]=a&features[]=b); canonical signs plain keys
    $urlPairs = [];
    foreach ($all as $k => $v) {
        $isArray = is_array($v);
        $values = $isArray ? $v : [$v];
        $urlKey = $isArray ? $k . '[]' : $k;
        foreach ($values as $vv) {
            $urlPairs[] = rawurlencode($urlKey) . '=' . rawurlencode((string)$vv);
        }
    }

    return $baseUrl . '?' . implode('&', $urlPairs) . '&s=' . $signature;
}

// Usage in Blade template:
$ogUrl = generateOgImageUrl(
    'https://fastog.com/api/v1/og',
    ['title' => 'Como criar um SaaS'],
    'sk_quick_123abc',
    env('HMAC_SECRET')
);

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

Python

python
import hmac
import hashlib
from urllib.parse import quote

def _enc(s):
    return quote(str(s), safe='-._~')

def generate_og_image_url(base_url, params, api_key, hmac_secret):
    # every query param except `s`; key included; array values sorted too
    all_params = {**params, 'key': api_key}

    pairs = []
    for k, v in all_params.items():
        for vv in sorted(v if isinstance(v, list) else [v]):
            pairs.append(f"{_enc(k)}={_enc(vv)}")
    canonical = '&'.join(sorted(pairs))

    signature = hmac.new(
        hmac_secret.encode(),
        f"GET/api/v1/og\n{canonical}".encode(),
        hashlib.sha256
    ).hexdigest()

    # URL uses bracket keys for arrays (features[]=a&features[]=b); canonical signs plain keys
    url_pairs = []
    for k, v in all_params.items():
        if isinstance(v, list):
            for vv in v:
                url_pairs.append(f"{_enc(f'{k}[]')}={_enc(vv)}")
        else:
            url_pairs.append(f"{_enc(k)}={_enc(v)}")

    return f"{base_url}?{'&'.join(url_pairs)}&s={signature}"

# Usage:
og_url = generate_og_image_url(
    'https://fastog.com/api/v1/og',
    {'title': 'Como criar um SaaS', 'template': 'default'},
    'sk_quick_123abc',
    os.environ['HMAC_SECRET']
)

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

전체 예시: Laravel Blade 템플릿

blade
{{-- In your blog post view --}}
@php
    $apiKey = 'sk_quick_123abc'; // Your full API key
    $hmacSecret = env('OG_RENDER_HMAC_SECRET');

    $params = [
        'template' => 'blog',
        'title' => $post->title,
        'subtitle' => $post->excerpt,
        'key' => $apiKey,
    ];

    // canonical query: sorted "k=v" pairs, rfc3986-encoded, every param except `s`
    $pairs = [];
    foreach ($params as $k => $v) {
        $pairs[] = rawurlencode((string)$k) . '=' . rawurlencode((string)$v);
    }
    sort($pairs, SORT_STRING);
    $canonical = implode('&', $pairs);
    $signature = hash_hmac('sha256', 'GET/api/v1/og' . "\n" . $canonical, $hmacSecret);

    $ogImageUrl = 'https://fastog.com/api/v1/og?' . $canonical . '&s=' . $signature;
@endphp

<head>
    <meta property="og:image" content="{{ $ogImageUrl }}" />
    <meta property="og:title" content="{{ $post->title }}" />
    <meta property="og:description" content="{{ $post->excerpt }}" />
</head>

보안 모범 사례

  1. 비밀 정보를 안전하게 저장 - 환경 변수 또는 비밀 관리 도구(secrets manager)를 사용하세요.
  2. 클라이언트 측 코드에 비밀 정보를 노출하지 마세요 - URL 서명은 서버에서만 수행하세요.
  3. HTTPS를 사용하세요 - 중간자 공격(MITM)을 방지합니다.
  4. 비밀 정보를 주기적으로 교체하세요 - 특히 유출된 경우에는 반드시 교체하세요.
  5. 실패한 서명을 모니터링하세요 - 반복적인 실패는 공격을 나타낼 수 있습니다.
  6. 사용자별 격리 - 각 API 키는 고유한 HMAC 비밀 정보를 보유합니다.

오류 응답

서명 누락

json
{
    "error": "Missing signature parameters",
    "code": "missing_signature",
    "required_params": ["s", "key"],
    "example": "/api/v1/og?title=Hello&key=sk_quick_123abc&s=<signature>"
}

잘못된 서명

json
{
    "error": "Invalid signature",
    "code": "invalid_signature"
}

테스트

테스트 URL을 생성합니다:

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

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

예상 응답:

  • ✅ 유효한 서명 → OG 이미지 반환 (템플릿 매개변수가 누락된 경우 검증 오류 반환)
  • ❌ 잘못된 서명 → {"error": "...", "code": "invalid_signature"}
  • ❌ 매개변수 누락 → {"error": "...", "code": "missing_signature"}

문제 해결

서명이 일치하지 않는 경우

  1. 올바른 HMAC 시크릿을 사용하고 있는지 확인합니다(대시보드에서 API 키 확인).
  2. 표준 쿼리(Canonical Query)를 확인합니다. s을 제외한 모든 쿼리 매개변수(key 포함)는 rfc3986 방식으로 인코딩된 값과 사전순으로 정렬된 키를 사용해야 합니다.
  3. 서명이 소문자 16진수(64자)인지 확인합니다.

HMAC 시크릿 가져오기

  1. 대시보드 → API 키로 이동합니다.
  2. 새 API 키를 생성하거나 기존 키를 사용합니다.
  3. API 키 옆에 표시된 HMAC 시크릿을 복사합니다(한 번만 표시됩니다!).
  4. 환경 변수에 안전하게 저장합니다.
bash
# Add to .env
OG_RENDER_HMAC_SECRET=<your-64-char-hex-secret>

curl로 테스트하기

bash
# Bash script to generate signed URL
SECRET="your-hmac-secret-here"
API_KEY="sk_quick_123abc"  # Your full API key

# canonical query: sorted "k=v" pairs, every param except `s` (key included)
CANONICAL="key=${API_KEY}&template=default&title=Test"
MESSAGE=$(printf 'GET/api/v1/og\n%s' "$CANONICAL")
SIGNATURE=$(printf '%s' "$MESSAGE" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)

curl "http://localhost:8000/api/v1/og?template=default&title=Test&key=${API_KEY}&s=${SIGNATURE}"

예상 결과: 이미지 데이터가 포함된 200 OK (템플릿 매개변수가 유효하지 않은 경우 422).

전체 API 참조

무료로 체험해 보세요 — 가입 불필요

몇 초 만에 동적 OG 이미지를 미리 보고 테스트하세요.

무료 OG 이미지 테스터 열기
LocaFile AI AI localization for games, apps, subtitles & sites SubtoVTT Convert & clean subtitle files BeCaSimulations Indie game studio

A BeCaSimulations site