Настройка CORS (Cross-Origin Resource Sharing) для API сайта

Настройка CORS (Cross-Origin Resource Sharing) для API сайта

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

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

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

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

Сервер должен ответить разрешением:

Access-Control-Allow-Origin: https://app.example.com
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.com', 'https://admin.example.com'],
    '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 часа.