Защита бэкенда Node.js: Валидация HMAC для вебхуков Didit (RU)

Защита целостности данныхВалидация HMAC-подписи необходима для проверки подлинности и целостности полезной нагрузки вебхуков, защищая ваш бэкенд от поддельных или измененных запросов.

Предотвращение атак повторного воспроизведенияВалидация временной метки в сочетании с HMAC-подписями добавляет критически важный уровень защиты от атак повторного воспроизведения, гарантируя обработку только свежих уведомлений.

Бесшовная интеграцияПодход Didit, ориентированный на разработчиков, предоставляет четкую документацию и инструменты, делая интеграцию безопасной обработки вебхуков в ваше Node.js-приложение простой и эффективной.

Безопасная инфраструктура DiditПлатформа Didit создана с учетом требований безопасности, предлагая уведомления KYC в реальном времени через вебхуки с надежной проверкой HMAC-подписи, что позволяет создавать доверенные, соответствующие требованиям решения для идентификации.

Критическая необходимость в безопасности вебхуков

Вебхуки — это мощные инструменты для обмена данными в реальном времени между сервисами, обеспечивающие мгновенные обновления и событийно-ориентированные архитектуры. В контексте проверки личности Didit использует вебхуки для уведомления вашего бэкенда о завершении сеансов проверки, результатах AML-скрининга или других критически важных событиях, связанных с идентификацией. Хотя вебхуки невероятно эффективны, они также создают проблемы безопасности. Без надлежащей проверки злоумышленник может отправить поддельные или измененные полезные нагрузки вебхуков, что приведет к некорректной обработке данных, несанкционированным действиям или даже компрометации системы.

Именно здесь валидация HMAC-подписи (Hash-based Message Authentication Code) становится незаменимой. HMAC предоставляет криптографический механизм для проверки как подлинности, так и целостности сообщения. Используя общий секретный ключ, ваш бэкенд может быть уверен, что полезная нагрузка вебхука поступила от Didit и не была изменена при передаче. Для любой системы, работающей с конфиденциальными данными идентификации, такими как данные, обрабатываемые службами Didit ID Verification, AML Screening или Proof of Address, этот уровень безопасности является не просто лучшей практикой — это необходимость.

Понимание валидации HMAC-подписи

Валидация HMAC работает путем генерации уникальной подписи для каждой полезной нагрузки вебхука с использованием секретного ключа, известного только Didit и вашему приложению. Когда ваш бэкенд Node.js получает вебхук, он выполняет тот же расчет подписи, используя свою копию секретного ключа. Если рассчитанная подпись совпадает с подписью, предоставленной в заголовках вебхука, вы можете быть уверены, что полезная нагрузка подлинна и не была изменена.

Вебхуки Didit включают заголовок X-Signature, содержащий HMAC-SHA256 подпись, и заголовок X-Timestamp. Временная метка имеет решающее значение для предотвращения атак повторного воспроизведения. Атака повторного воспроизведения происходит, когда злоумышленник перехватывает легитимный вебхук и переотправляет его позже. Проверяя, что временная метка является свежей (например, в течение 5-минутного окна), вы можете отбросить старые, потенциально повторно воспроизведенные запросы.

Реализация валидации HMAC в Node.js

Давайте рассмотрим шаги по реализации валидации HMAC-подписи для вебхуков Didit в приложении Node.js Express. Вам потребуется доступ к вашему секретному ключу вебхука, который можно найти в вашей Didit Business Console или получить через API управления.

1. Настройка конечной точки вебхука

Сначала настройте конечную точку Express, которая может принимать POST-запросы. Крайне важно получить доступ к необработанному телу запроса до любого промежуточного программного обеспечения для парсинга JSON, поскольку подпись рассчитывается по необработанной полезной нагрузке.

const express = require('express');
const crypto = require('crypto');
const bodyParser = require('body-parser');

const app = express();
const DIDIT_WEBHOOK_SECRET = process.env.DIDIT_WEBHOOK_SECRET; // Store securely!

// Middleware to get raw body
app.use(bodyParser.json({ verify: (req, res, buf) => {
  req.rawBody = buf.toString();
}}));

app.post('/api/webhooks/didit', (req, res) => {
  // Webhook processing logic will go here
  res.status(200).send('Webhook received');
});

app.listen(3000, () => console.log('Server running on port 3000'));

2. Проверка HMAC-подписи

Внутри вашего обработчика вебхуков вы извлечете временную метку и подпись из заголовков, восстановите подписанную полезную нагрузку и сравните свою рассчитанную подпись с той, что предоставлена Didit.

app.post('/api/webhooks/didit', (req, res) => {
  const signatureHeader = req.headers['x-signature'];
  const timestampHeader = req.headers['x-timestamp'];
  const rawBody = req.rawBody;

  if (!signatureHeader || !timestampHeader || !rawBody) {
    return res.status(400).send('Missing webhook headers or body.');
  }

  const [algorithm, diditSignature] = signatureHeader.split('=');

  if (algorithm !== 'sha256') {
    return res.status(400).send('Unsupported signature algorithm.');
  }

  // Reconstruct the signed payload string
  const signedPayload = `${timestampHeader}.${rawBody}`;

  // Calculate your own signature
  const expectedSignature = crypto
    .createHmac('sha256', DIDIT_WEBHOOK_SECRET)
    .update(signedPayload)
    .digest('hex');

  // Compare signatures securely
  const signatureMatches = crypto.timingSafeEqual(
    Buffer.from(diditSignature, 'utf8'),
    Buffer.from(expectedSignature, 'utf8')
  );

  if (!signatureMatches) {
    console.warn('Webhook signature mismatch!');
    return res.status(401).send('Invalid signature.');
  }

  // Signature is valid, now check timestamp
  // ... (timestamp validation in next step)

  // Process event
  console.log('Webhook validated successfully:', req.body);
  res.status(200).send('Webhook received and processed.');
});

3. Валидация временной метки

После проверки подписи убедитесь, что вебхук не является повторным. Распространенной практикой является допущение небольшого окна толерантности (например, 5 минут) для задержек в сети.

// ... (inside the webhook handler, after signature validation)

  const fiveMinutesAgo = Date.now() / 1000 - (5 * 60); // 5 minutes in seconds
  const eventTimestamp = parseInt(timestampHeader, 10);

  if (isNaN(eventTimestamp) || eventTimestamp < fiveMinutesAgo) {
    console.warn('Webhook timestamp too old or invalid!');
    return res.status(401).send('Invalid or old timestamp.');
  }

  // Now you can safely parse and process the JSON body
  try {
    const event = JSON.parse(rawBody);
    console.log('Processed Didit event:', event);
    // Example: Update user status based on event.database_validation.status

    // Didit's Database Validation Report structure:
    // const validationStatus = event.database_validation.status;
    // const matchType = event.database_validation.match_type;
    // console.log(`Validation Status: ${validationStatus}, Match Type: ${matchType}`);

    res.status(200).send('Webhook received and processed.');
  } catch (error) {
    console.error('Error parsing webhook body:', error);
    res.status(400).send('Invalid JSON body.');
  }
});

Лучшие практики обработки вебхуков

• Надежное хранение секретов: Никогда не прописывайте секретный ключ вебхука в коде. Используйте переменные окружения или защищенный сервис управления секретами.
• Идемпотентность: Разрабатывайте обработчики вебхуков таким образом, чтобы они были идемпотентными. Это означает, что обработка одного и того же вебхука несколько раз (например, из-за повторных попыток) должна иметь тот же эффект, что и однократная обработка.
• Асинхронная обработка: Для длительных задач немедленно подтверждайте вебхук ответом 200 OK, а затем асинхронно обрабатывайте полезную нагрузку с использованием очереди сообщений. Это предотвращает таймауты и гарантирует, что Didit не будет постоянно повторять отправку вебхука.
• Логирование и мониторинг: Внедрите надежное логирование для всех полученных вебхуков, включая сбои валидации. Отслеживайте вашу конечную точку вебхука на предмет необычной активности или высокого уровня ошибок.
• Обработка ошибок: Возвращайте соответствующие коды состояния HTTP (например, 400 для некорректного запроса, 401 для неавторизованного, 500 для ошибок сервера), чтобы помочь Didit понять, требуется ли повторная попытка.

Как Didit помогает

Didit разработан как AI-нативная, ориентированная на разработчиков платформа идентификации, делающая безопасные интеграции, такие как обработка вебхуков, простой и надежной. Наша модульная архитектура означает, что вы можете легко подключать проверки личности, включая проверку ID, пассивную и активную проверку живости, а также AML-скрининг и мониторинг, и получать обновления в реальном времени через безопасные вебхуки. Didit предоставляет четкую документацию и примеры для интеграции вебхуков, гарантируя, что вы сможете быстро настроить надежные, безопасные каналы связи.

Мы верим в то, что проверка личности должна быть доступной и мощной. Вот почему мы предлагаем Free Core KYC, модель оплаты за успешную проверку и абсолютно никаких стартовых сборов. Используя платформу Didit, вы получаете доступ к глобальному, масштабируемому решению, которое автоматизирует доверие и управляет рисками, при этом поддерживая высочайшие стандарты безопасности, включая валидацию HMAC-подписи для уведомлений в реальном времени.

Готовы начать?

Готовы увидеть Didit в действии? Получите бесплатную демонстрацию уже сегодня.

Начните бесплатно проверять личности с бесплатным тарифом Didit.