Налаштування CORS (Cross-Origin Resource Sharing) для API сайту

Налаштування CORS (Cross-Origin Resource Sharing) для API сайту

CORS — механізм браузера, який дозволяє або забороняє веб-сторінці робити запити до іншого домену. Без правильної настройки фронтенд на app.example.ua не зможе звертатися до API на api.example.ua, навіть якщо обидва належать вам.

Принцип роботи

Для «простих» запитів (GET, POST з певними заголовками) браузер відправляє запит та перевіряє заголовки відповіді. Для «складних» (PUT, DELETE, кастомні заголовки) спочатку йде preflight-запит OPTIONS:

OPTIONS /api/users HTTP/1.1
Origin: https://app.example.ua
Access-Control-Request-Method: DELETE
Access-Control-Request-Headers: Authorization, Content-Type

Сервер має відповісти дозволом:

Access-Control-Allow-Origin: https://app.example.ua
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Max-Age: 86400

Налаштування в Nginx

location /api/ {
    if ($request_method = 'OPTIONS') {
        add_header Access-Control-Allow-Origin $http_origin;
        add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS";
        add_header Access-Control-Allow-Headers "Authorization, Content-Type, X-Requested-With";
        add_header Access-Control-Max-Age 86400;
        return 204;
    }

    add_header Access-Control-Allow-Origin $http_origin always;
    add_header Access-Control-Allow-Credentials true always;
    proxy_pass http://backend;
}

Налаштування в Laravel

// config/cors.php
return [
    'paths' => ['api/*'],
    'allowed_methods' => ['*'],
    'allowed_origins' => ['https://app.example.ua', 'https://admin.example.ua'],
    'allowed_headers' => ['Authorization', 'Content-Type', 'X-Requested-With'],
    'exposed_headers' => ['X-Total-Count'],
    'max_age' => 86400,
    'supports_credentials' => true,
];

Пакет fruitcake/laravel-cors (вбудований у Laravel 7+) обробляє все автоматично через middleware.

Credentials та cookies

Якщо API використовує cookie-сесії або передає credentials:

• Сервер має повернути Access-Control-Allow-Credentials: true
• Access-Control-Allow-Origin не може бути * — тільки конкретний домен
• Фронтенд має вказати credentials: 'include' у fetch або withCredentials: true в Axios

Типові помилки

• Access-Control-Allow-Origin: * з credentials: true — браузер заблокує
• Динамічна $http_origin без перевірки whitelist — будь-який сайт отримає доступ
• Відсутність CORS-заголовків на помилкових відповідях (4xx/5xx) — фронтенд не побачить тіло помилки

Строк реалізації

Базова настройка CORS для типового проекту — 2–4 години.