HMAC-аутентификация и безопасность

Защитите свои URL-адреса OG-изображений, подписанные через HMAC, с помощью HMAC-SHA256-аутентификации от FastOG. Это руководство охватывает подписание, проверку и устранение неполадок для каждого запроса, чтобы вы могли создавать динамические Open Graph изображения на лету — с ограничением по подписке и без лимита на рендеринг (без ежемесячной квоты на рендеринг и без оплаты за превышение). Зарегистрируйтесь, выберите тарифный план Dynamic API, затем создайте свой API-ключ и HMAC-секрет в панели управления (платные рендеры 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-подписи — Полный справочник с деталями алгоритма, требованиями и примерами на JavaScript, PHP и Python
• Проверка HMAC — Детали серверной реализации, функции безопасности и ответы об ошибках

Учебные руководства

• Учебное руководство по JavaScript/Node.js — Подробное руководство, охватывающее:

  • Быстрый старт (5 минут)
  • Next.js App Router (3 паттерна)
  • Next.js Pages Router
  • Бэкенд на Express.js
  • Чистый Node.js
  • Паттерны интеграции во фронтенде (SSG, SSR, клиентская часть)
  • Тестирование и отладка
  • Типичные ошибки

• Next.js App Router

• Next.js Pages Router

• React

• SvelteKit

• Vue/Nuxt

• Astro

• Express

• Чистый 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>

Параметры запроса

Коды ошибок

🎯 Варианты использования

Записи в блоге

Генерация динамических OG-изображений для записей в блоге:

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

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

Товары в интернет-магазинах

Создание OG-изображений для страниц товаров:

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

Отзывы клиентов

Генерация OG-изображений для цитат из отзывов:

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

🔐 Безопасность

Рекомендации

1. Храните секреты безопасно — используйте переменные окружения или менеджер секретов
2. Никогда не раскрывайте HMAC-секрет в клиентском коде — подписывайте только на сервере
3. Используйте HTTPS — предотвращает атаки типа MITM
4. Периодически меняйте секреты — особенно в случае компрометации
5. Отслеживайте неудачные подписи — повторные сбои могут указывать на атаки
6. Изоляция по пользователям — каждый API-ключ имеет собственный HMAC-секрет

Получение HMAC-секрета

1. Перейдите в Панель управления → API-ключи
2. Создайте новый API-ключ
3. Скопируйте HMAC-секрет (отображается только один раз!)
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 (проверьте ключ API в панели управления)
2. Проверьте канонический запрос: все параметры запроса, кроме s (включая key), значения закодированы по RFC3986, ключи отсортированы в лексикографическом порядке
3. Убедитесь, что подпись указана в нижнем регистре в шестнадцатеричном формате (64 символа)

📖 Дополнительные ресурсы

• Справочник API — Полная документация по API
• Рекомендации по безопасности — Подробное руководство по безопасности
• База знаний — Технические детали реализации

❓ Часто задаваемые вопросы

В: Почему используются query-параметры, а не заголовки?
О: OG-изображения запрашиваются краулерами социальных сетей (LinkedIn, Twitter, Facebook), которые не отправляют пользовательские заголовки. Подпись ОБЯЗАТЕЛЬНО должна быть в URL.

В: Можно ли использовать одну и ту же подпись для нескольких запросов?
О: Да. Подпись вычисляется на основе точного запроса (за вычетом s), поэтому один и тот же подписанный URL остается действительным, пока параметры не меняются. При изменении любого параметра (включая key) необходимо подписать запрос заново.

В: Нужно ли подписывать запросы для всех шаблонов?
О: Да. Все запросы к /api/v1/og требуют HMAC-подписей.

В: Что произойдет, если мой HMAC-секрет будет скомпрометирован?
О: Отзовите API-ключ в панели управления и создайте новый. Каждый API-ключ имеет собственный HMAC-секрет.

В: Можно ли отключить проверку HMAC для внутренних сервисов?
О: Обратитесь в поддержку для индивидуальных решений. Проверка HMAC обязательна для всех публичных API-эндпоинтов.

🆘 Поддержка

Нужна помощь?

• Ознакомьтесь с JavaScript-руководством для полных примеров кода
• Изучите руководство по HMAC-подписи для деталей алгоритма
• Свяжитесь со службой поддержки по адресу [email protected]

Связанные материалы

• Документация — все руководства и справочники FastOG
• Бесплатный тестер OG-изображений — предпросмотр без аккаунта
• Краткое руководство по началу работы — запуск за 5 минут
• Руководство по подписи HMAC — детали алгоритма
• Проверка HMAC — серверная валидация