N8n cors

N8n CORS: Полное руководство по настройке и устранению проблем с политикой общего доступа к ресурсам

CORS (Cross-Origin Resource Sharing) — это механизм безопасности, реализованный в современных веб-браузерах, который использует HTTP-заголовки для определения, могут ли веб-приложения, работающие на одном источнике (домене, протоколе, порту), получать доступ к ресурсам с другого источника. N8n, как платформа автоматизации рабочих процессов, часто развертывается самостоятельно (self-hosted) и выступает в роли бэкенд-сервиса для пользовательских веб-интерфейсов или интегрируется с внешними приложениями. В таких сценариях правильная настройка CORS становится критически важной для обеспечения функциональности и безопасности.

Архитектура CORS в контексте N8n

N8n — это Node.js приложение, которое по умолчанию обслуживает как фронтенд (редактор рабочих процессов), так и бэкенд (REST API). Когда внешнее веб-приложение, размещенное на домене `app.example.com`, пытается выполнить запрос к API N8n, работающему на `n8n.your-company.com`, браузер инициирует механизм CORS. Браузер отправляет «предварительный» (preflight) запрос типа OPTIONS к N8n, чтобы проверить, разрешены ли кросс-доменные запросы с указанного источника и с использованием указанных методов и заголовков. Сервер N8n должен ответить соответствующими заголовками CORS, чтобы браузер разрешил основной запрос.

Детальная настройка CORS в N8n

Настройка CORS в N8n осуществляется преимущественно через переменные окружения или конфигурационный файл. Основные параметры сосредоточены вокруг переменной `N8N_CORS_ORIGIN`.

Переменные окружения для управления CORS

Переменная окружения	Значение по умолчанию	Описание и допустимые значения	Пример
N8N_CORS_ORIGIN	*	Определяет разрешенные источники (origins). Может быть строкой, разделенным запятыми списком или регулярным выражением. Значение * разрешает все источники (небезопасно для продакшена).	https://myapp.com,https://admin.myapp.com
N8N_CORS_METHODS	GET,POST,PUT,PATCH,DELETE	HTTP-методы, разрешенные для кросс-доменных запросов.	GET,POST,OPTIONS
N8N_CORS_CREDENTIALS	false	Если установлено в true, разрешает отправку учетных данных (куки, заголовки авторизации). При использовании true в N8N_CORS_ORIGIN нельзя использовать *.	true
N8N_CORS_ALLOWED_HEADERS	Стандарный набор заголовков (Content-Type, Authorization и др.)	Заголовки запроса, которые могут быть использованы при реальном запросе. Для нестандартных заголовков их необходимо перечислить.	Content-Type,Authorization,X-API-Key,X-Requested-With
N8N_CORS_EXPOSED_HEADERS	Пусто	Заголовки ответа, которые браузер должен сделать доступными для клиентского скрипта.	X-n8n-request-id
N8N_CORS_MAX_AGE	600 (10 минут)	Время в секундах, на которое браузер может кэшировать ответ предварительного запроса (OPTIONS).	86400
N8N_PROTOCOL и N8N_HOST	Зависят от развертывания	Косвенно влияют на CORS, так как определяют публичный URL N8n. Важно для корректного формирования URL в ответах и вебхуках.	N8N_PROTOCOL=https, N8N_HOST=n8n.mydomain.com

Практические примеры конфигурации

Пример 1: Разрешение доступа для нескольких конкретных доменов с учетными данными.

• Сценарий: Ваш фронтенд работает на `https://portal.company.com`, а панель администратора — на `https://admin.company.com`. Оба должны отправлять запросы с куками аутентификации к N8n на `https://automate.company.com`.
• Конфигурация в файле `.env`:

  N8N_CORS_ORIGIN=https://portal.company.com,https://admin.company.com
  N8N_CORS_CREDENTIALS=true
  N8N_CORS_METHODS=GET,POST,PUT,PATCH,DELETE,OPTIONS
  N8N_CORS_ALLOWED_HEADERS=Content-Type,Authorization,X-Requested-With
  

Пример 2: Использование регулярного выражения для динамических поддоменов.

• Сценарий: Вы хотите разрешить доступ для всех поддоменов `*.yourplatform.io`.
• Конфигурация:

  N8N_CORS_ORIGIN=/^https://[a-zA-Z0-9-]+.yourplatform.io$/
  

Пример 3: Развертывание за обратным прокси (Reverse Proxy).

• Сценарий: N8n доступен через Nginx или Apache на одном домене с фронтендом, но на разных путях (например, `/` для фронтенда и `/n8n/` для API). В этом случае CORS может не требоваться, так как источник (origin) одинаков. Однако, если прокси добавляет или изменяет заголовки, может потребоваться тонкая настройка `N8N_CORS_ALLOWED_HEADERS`. Важно также установить `N8N_HOST` и `WEBHOOK_URL` на публичный адрес.

Диагностика и устранение проблем с CORS в N8n

Типичная ошибка CORS в консоли браузера: Access to fetch at 'https://n8n.server.com/api/v1/workflows' from origin 'https://app.client.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Пошаговый алгоритм диагностики:

1. Проверка фактических заголовков ответа: Используйте вкладку «Network» в инструментах разработчика браузера. Найдите запрос, который завершился ошибкой, и проверьте ответ на предварительный (OPTIONS) или основной запрос. Убедитесь, что заголовки `Access-Control-Allow-Origin`, `Access-Control-Allow-Methods` присутствуют и корректны.
2. Валидация переменных окружения: Убедитесь, что переменные окружения загружены правильно. При запуске через Docker Compose или Kubernetes проверьте корректность синтаксиса YAML. Перезапустите инстанс N8n после изменения переменных.
3. Проверка использования учетных данных: Если в вашем фронтенд-коде для запросов установлен флаг `credentials: ‘include’` (Fetch API) или `withCredentials: true` (Axios), то переменная `N8N_CORS_CREDENTIALS` должна быть `true`, а в `N8N_CORS_ORIGIN` должен быть явно указан конкретный источник, а не звездочка.
4. Анализ предварительного запроса (Preflight): Если ваш запрос использует нестандартные заголовки или методы (например, `DELETE`, `PATCH`), браузер отправит OPTIONS запрос. Убедитесь, что `N8N_CORS_METHODS` и `N8N_CORS_ALLOWED_HEADERS` включают необходимые значения.
5. Проверка наличия обратного прокси: Если перед N8n стоит Nginx, Traefik или облачный балансировщик, они также могут управлять заголовками CORS. Возможен конфликт, когда и N8n, и прокси добавляют одни и те же заголовки. Часто решение — отключить CORS на уровне N8n (оставив `N8N_CORS_ORIGIN` пустым или `false`) и настроить его исключительно на обратном прокси.

Расширенная конфигурация: CORS при использовании аутентификации и вебхуков

Сценарии, требующие особого внимания:

• Интеграция с внешними одностраничными приложениями (SPA): При использовании OAuth2 или JWT аутентификации через фронтенд, заголовок `Authorization` должен быть явно разрешен в `N8N_CORS_ALLOWED_HEADERS`. Учетные данные (`N8N_CORS_CREDENTIALS`) должны быть `true`, если используется аутентификация на основе сессий/кук.
• Вебхуки (Webhooks): CORS не применяется к запросам, инициированным сервером (например, вызовам вебхуков от внешних сервисов к N8n). Однако, если вы создаете пользовательский интерфейс для управления вебхуками, который делает запросы к API N8n из браузера, CORS настройки применяются к этим API-запросам.
• Режим редактора и API: Редактор N8n, работающий на том же домене, что и бэкенд, не подвержен ограничениям CORS. Проблемы возникают только при попытке доступа к API N8n с внешнего домена.

Безопасность и рекомендации для продакшена

Использование `N8N_CORS_ORIGIN=*` в производственной среде крайне не рекомендуется, так как это позволяет любому сайту делать запросы к вашему инстансу N8n от имени пользователя браузера (с его куками/токенами).

• Принцип наименьших привилегий: Явно перечисляйте все разрешенные источники, методы и заголовки.
• Использование переменных окружения: Храните конфигурацию CORS в защищенных переменных окружения, а не в коде приложения.
• Регулярный аудит: Периодически проверяйте актуальность списка разрешенных источников.
• Защита на уровне сети: Дополнительно к CORS используйте брандмауэры веб-приложений (WAF) и ограничивайте доступ к порту N8n только доверенным IP-адресам (например, адресам ваших фронтенд-серверов или сетей).

Ответы на часто задаваемые вопросы (FAQ)

Вопрос 1: Я настроил CORS, но все равно получаю ошибку «No ‘Access-Control-Allow-Origin’ header». В чем причина?

Ответ: Наиболее вероятные причины:

1. Переменные окружения не были применены. Убедитесь, что вы перезапустили службу N8n (docker container, pm2 процесс) после изменения `.env` файла.
2. Конфликт с обратным прокси. Если вы используете Nginx, проверьте его конфигурацию на наличие директив `add_header Access-Control-Allow-Origin`. Попробуйте временно отключить CORS в Nginx и позволить N8n самостоятельно управлять заголовками.
3. Некорректный синтаксис в `N8N_CORS_ORIGIN`. Для нескольких доменов используйте запятые без пробелов: `domain1.com,domain2.com`. При использовании регулярных выражений убедитесь в их корректности.

Вопрос 2: Нужно ли настраивать CORS, если я обращаюсь к N8n API с серверного приложения (Node.js, Python)?

Ответ: Нет. Политика CORS является механизмом браузера и применяется только когда запрос инициируется из JavaScript, выполняющегося в веб-браузере. Серверные приложения, мобильные приложения или инструменты командной строки (например, cURL) не подвержены ограничениям CORS. Для них контроль доступа должен осуществляться через API-ключи, аутентификацию и сетевые политики.

Вопрос 3: Как настроить CORS при развертывании N8n в Docker/Docker Compose?

Ответ: В файле `docker-compose.yml` определите переменные окружения в секции `environment` для сервиса n8n:

services:
  n8n:
    image: n8nio/n8n
    environment:
      - N8N_CORS_ORIGIN=https://my-frontend.com
      - N8N_CORS_CREDENTIALS=true
      - N8N_HOST=n8n.mydomain.com
    ports:
      - "5678:5678"

Убедитесь, что файл `.env`, если он используется, монтируется в контейнер, или переменные передаются напрямую, как показано выше.

Вопрос 4: Можно ли полностью отключить CORS в N8n?

Ответ: Да. Для этого вы можете установить переменную `N8N_CORS_ORIGIN` в пустое значение или `false`. Например: `N8N_CORS_ORIGIN=`. Это приведет к тому, что middleware CORS в N8n не будет добавлять заголовки, и браузеры будут блокировать все кросс-доменные запросы. Это безопасная настройка, если вы не планируете предоставлять API для внешних веб-интерфейсов.

Вопрос 5: Почему при использовании `N8N_CORS_CREDENTIALS=true` я должен указывать конкретный домен, а не звездочку?

Ответ: Это требование спецификации безопасности W3C для CORS. Сочетание `Access-Control-Allow-Credentials: true` и `Access-Control-Allow-Origin: *` считается небезопасным, так как позволяет любому сайту делать авторизованные запросы к вашему API, используя учетные данные пользователя. Браузер в таком случае отклонит запрос. Для безопасного использования учетных данных необходимо явно указывать доверенный источник.

Вопрос 6: Как настроить CORS для локальной разработки?

Ответ: При разработке фронтенда на `http://localhost:3000` и обращении к локальному N8n на `http://localhost:5678` настройте CORS следующим образом: `N8N_CORS_ORIGIN=http://localhost:3000`. Для удобства можно разрешить несколько локальных портов: `http://localhost:3000,http://localhost:8080`. Не используйте `*` в продакшене, даже на этапе разработки, чтобы избежать привыкания к небезопасной конфигурации.