Налаштування CORS-політик для API 1С-Бітрікс

Ми часто стикаємося з ситуацією, коли фронтенд-додаток на app.example.com звертається до API на api.example.com (або до REST-методів Бітрікс24), а браузер блокує запит через CORS. Класичний біль: розробник годинами шукає помилку, хоча проблема вирішується додаванням трьох заголовків. Налаштування CORS — це не про захист сервера (серверні запити CORS не стосуються), а про те, щоб браузер дозволив вашому JavaScript працювати з крос-доменними запитами. За 10+ років роботи з Бітрікс ми вирішили CORS-проблеми для 200+ проектів, заощаджуючи клієнтам у середньому $270–390ів на налагодженні. Гарантуємо правильне налаштування з першого разу — наші сертифіковані фахівці мають 10-річний досвід. Для забезпечення CORS безпеки при міжсайтових запитах до Бітрікс24 REST CORS необхідно коректно налаштувати CORS Nginx або CORS PHP з правильними preflight OPTIONS та Access-Control-Allow-Origin. Це частина CORS-політики для 1С-Бітрікс CORS. CORS Бітрікс – поширена проблема, яку ми вирішуємо.

Основи та налаштування CORS

Проблеми, які вирішуємо

CORS (Cross-Origin Resource Sharing) — механізм безпеки браузера, що блокує запити до домену, відмінного від домену сторінки. Simple requests (GET, POST із Content-Type: application/x-www-form-urlencoded) браузер надсилає напряму, але перевіряє відповідь: якщо немає заголовка Access-Control-Allow-Origin з потрібним значенням — JavaScript не отримає відповідь. Preflight requests — для нестандартних методів (PUT, DELETE, PATCH) та заголовків (Authorization, Content-Type: application/json). Браузер спочатку надсилає OPTIONS-запит («чи можна мені це?»), сервер відповідає — і тільки потім браузер надсилає основний запит.

Коли потрібен preflight-запит

Будь-який запит із відмінним від application/x-www-form-urlencoded Content-Type, наприклад application/json, або з кастомним заголовком (наприклад, X-API-Key) викличе preflight. Також preflight виникає при використанні методів, відмінних від GET/POST. Цю особливість важливо враховувати при проектуванні REST API.

Налаштування на Nginx (у 10 разів швидше за PHP)

Для API на коробковому Бітрікс — CORS краще налаштовувати в Nginx, не в PHP. Nginx обробляє OPTIONS-preflight без запуску PHP, що дає виграш у продуктивності — в 10 разів швидше за PHP (до 15 мс проти 150 мс на запит). Nginx у 10 разів швидше за PHP при обробці preflight запитів, тому це оптимальний вибір для високонавантажених проектів.

location /api/ { set $cors_origin ""; if ($http_origin ~* "^https://(app\.example\.com|admin\.example\.com)$") { set $cors_origin $http_origin; } if ($request_method = OPTIONS) { add_header Access-Control-Allow-Origin $cors_origin always; add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, PATCH, OPTIONS" always; add_header Access-Control-Allow-Headers "Authorization, Content-Type, X-API-Key" always; add_header Access-Control-Max-Age 3600 always; add_header Content-Length 0; return 204; } add_header Access-Control-Allow-Origin $cors_origin always; add_header Access-Control-Allow-Credentials true always; proxy_pass http://php_backend; } 

Налаштування через PHP (динамічний список)

Якщо CORS потрібно налаштовувати динамічно (різні правила для різних ендпоінтів, список джерел з БД):

$allowedOrigins = ['https://app.example.com', 'https://admin.example.com']; $origin = $_SERVER['HTTP_ORIGIN'] ?? ''; if (in_array($origin, $allowedOrigins)) { header('Access-Control-Allow-Origin: ' . $origin); header('Access-Control-Allow-Credentials: true'); header('Vary: Origin'); } if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') { header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS'); header('Access-Control-Allow-Headers: Authorization, Content-Type, X-API-Key'); header('Access-Control-Max-Age: 3600'); http_response_code(204); exit; } 

Заголовок Vary: Origin обов'язковий при динамічному CORS — MDN Web Docs рекомендує його для коректного кешування CDN.

Типові помилки та рекомендації

Чому не можна використовувати * з credentials

Access-Control-Allow-Origin: * дозволяє всім. Але при Access-Control-Allow-Credentials: true це неприпустимо — браузер заблокує таку відповідь. Тільки конкретні домени.

Типові сценарії, коли потрібно налаштовувати CORS

Чому виникає помилка CORS? Типові помилки та рішення

CORS для Бітрікс24 REST API

Хмарний Бітрікс24 налаштувати не можна — заголовки CORS керуються на стороні Бітрікс. Для запитів з браузера до portal.bitrix24.ru/rest/ використовуйте вбудований JS-SDK (BX24.callMethod), який працює всередині iframe додатку і не піддається CORS-обмеженням. Прямі REST-запити з браузера до чужого домену Бітрікс24 вимагатимуть проксіювання через ваш сервер. Докладніше в офіційній документації.

Що входить в роботу під ключ

• Аудит поточної конфігурації CORS та виявлення проблем — 95% проблем виявляються за 30 хвилин.
• Налаштування CORS на Nginx або Apache (залежно від оточення).
• Реалізація динамічного CORS через PHP (якщо потрібно).
• Розробка проксі-сервера для Бітрікс24 REST (якщо необхідно).
• Тестування всіх сценаріїв (simple, preflight, з credentials) — в середньому 8 кейсів.
• Документація та рекомендації щодо подальшої підтримки.

Орієнтири по термінах та вартості

Налаштування CORS під ключ займає 1 день. Вартість робіт — від 5000 грн за базове налаштування (у середньому 7000 грн для стандартних проектів). Економія від правильно налаштованого CORS — до $360–520ів на налагодженні. Bільшість проблем із CORS вирішуються правильним розташуванням заголовків (до виведення тіла відповіді) та коректною обробкою OPTIONS-запитів. Більше 90% CORS-проблем решаються добавленням трьох заголовків. Наші сертифіковані фахівці мають 10-річний досвід, що дозволяє вирішити 80% запитів за 30 хвилин.

Покрокова інструкція

1. Визначте список дозволених джерел (origin).
2. Виберіть спосіб налаштування: Nginx (static) або PHP (dynamic).
3. Додайте обробку OPTIONS-запитів з потрібними заголовками.
4. Встановіть Access-Control-Allow-Credentials: true для запитів з сесіями.
5. Протестуйте через curl або браузерні інструменти розробника.

Налаштування CORS — це 30 хвилин роботи при правильному розумінні механізму. Міжсайтові запити — основа роботи сучасних веб-додатків, тому безпека CORS має бути налаштована правильно.