Condo API — это гибкий инструмент, который подходит для самых разных сценариев,
выходящих за рамки управления недвижимостью.
На его основе разработчики создают даже собственные пет-проекты.
В качестве примера можно привести open-source аналог JIRA,
построенный с использованием нашего API.
Когда вы используете Condo API как бэкенд для своего веб-приложения,
ваш сервер должен выступать в роли посредника (прокси) между фронтендом и нашим API.
Это необходимо для обхода политик безопасности CORS в браузерах,
которые не позволяют делать прямые запросы к API на другом домене.
Такое проксирование открывает возможности для кастомизации и интеграций, но также создаёт техническую задачу:
как сохранить исходный IP-адрес пользователя?
Проблема IP-адресов при проксировании
По умолчанию, когда ваш сервер перенаправляет запрос в Condo API, наше API «видит» только IP-адрес вашего сервера,
а не IP-адрес конечного пользователя. Это приводит к нескольким проблемам:
- Некорректная работа лимитов: Системы защиты от флуда и ограничения частоты запросов (rate limiting) в Condo API работают на основе ID пользователей и их IP-адресов. Если все запросы приходят с одного IP вашего прокси-сервера, лимиты могут быть быстро исчерпаны, что затронет всех ваших пользователей.
- Снижение безопасности: IP-адрес является важным элементом для анализа безопасности и расследования инцидентов. Потеря этой информации усложняет мониторинг и защиту.
Решение: Передача IP-адреса через заголовки
Чтобы решить эту проблему, Condo API поддерживает специальный механизм передачи оригинального IP-адреса пользователя через HTTP-заголовки.
Для этого ваш прокси-сервер должен при каждом запросе к нашему API добавлять группу специальных заголовков.
Для использования этого механизма вам необходимо сначала связаться с командой Condo, чтобы получить идентификатор прокси (
x-proxy-id) и секретный ключ для подписи запросов.Необходимые заголовки
Для корректной передачи IP-адреса необходимо добавить в запрос следующие заголовки:
| Название заголовка | Описание |
|---|---|
x-proxy-id | Уникальный идентификатор вашего прокси-сервера, выданный командой Condo. |
x-proxy-ip | Реальный IP-адрес конечного пользователя. |
x-proxy-timestamp | Текущее время в формате Unix Timestamp (в миллисекундах). |
x-proxy-signature | Подпись запроса для обеспечения безопасности. |
Генерация подписи x-proxy-signature
Подпись
x-proxy-signature представляет собой JSON Web Token (JWT), сгенерированный с использованием секретного ключа, который мы вам предоставим.Токен должен содержать следующий набор полей (payload):
json{ "x-proxy-id": "ваш-идентификатор", "x-proxy-ip": "IP-адрес-пользователя", "x-proxy-timestamp": "текущий-timestamp", "method": "HTTP-метод оригинального запроса", "url": "Путь запроса" }
Подпись действительна в течение 5 секунд с момента, указанного в
x-proxy-timestamp. Это защищает от повторного использования перехваченных запросов (replay attacks).Пример
Предположим, вам выдан
x-proxy-id: my-proxy-123, и пользователь с IP 1.2.3.4 делает POST-запрос на /admin/api.- Формируем
payloadдля JWT:json
{ "x-proxy-id": "my-proxy-123", "x-proxy-ip": "1.2.3.4", "x-proxy-timestamp": "1756633489141", "method": "POST", "url": "/admin/api" } - Подписываем
payloadвашим секретным ключом с использованием алгоритма HS256 и получаем JWT-токен (это и будет значениеx-proxy-signature). - Отправляем запрос в Condo API с добавлением всех необходимых заголовков.
Использование @open-condo/miniapp-utils для генерации заголовков
Если ваша прокси написана на языке Javascript, то вы можете воспользоваться нашим готовым NPM-пакетом
@open-condo/miniapp-utils,
в котором есть готовая имплементация вышеописанного алгоритма:
typescriptimport { getProxyHeadersForIp } from '@open-condo/miniapp-utils/helpers/proxying' const headers = getProxyHeadersForIp('POST', '/admin/api', '1.2.3.4', 'jwt-secret')