# Настройка Content-Security-Policy

Content-Security-Policy (CSP) — HTTP-заголовок, который ограничивает источники скриптов, стилей, изображений и других ресурсов веб-страницы. При его настройке необходимо учитывать, что Панель управления Webim, страницы авторизации и чат посетителя загружаются как отдельные HTML-документы. Для них используются разные политики.

Ниже приведены примеры для nginx и рекомендации по их применению. Если в аккаунте используются дополнительные интеграции, разрешённые источники могут отличаться.

## Область действия CSP

| Документ | Назначение |
| --- | --- |
| `/agent/` | Панель управления |
| `/framed/…` | Встроенные страницы Панели управления |
| `/auth/` | Вход, регистрация и восстановление доступа |
| `/visitor/chat` | Страница чата посетителя, в том числе внутри iframe |
| Страница сайта с виджетом | Собственная CSP сайта, действующая на скрипты и ресурсы, которые выполняются непосредственно на нём |

Политика действует на тот HTML-документ, в ответе которого пришёл этот заголовок. Например, CSP страницы сайта не заменяет политику документа `/visitor/chat` внутри iframe. Аналогично CSP Панели управления не наследуется встроенными страницами `/framed/`.

## Примеры политик для Webim

Примеры ниже задают основные разрешения. Для наглядности каждая директива собирается отдельной строкой nginx `set`, а в HTTP-ответ отправляется единое значение заголовка. **Вставляйте полный фрагмент для соответствующего документа**, а не отдельные строки из нескольких примеров. `set` и `add_header` должны находиться в допустимом для них контексте nginx, который формирует конечный HTML-ответ.

На этапе проверки используйте `Content-Security-Policy-Report-Only`. После проверки его заменяют на `Content-Security-Policy` в том же `add_header`.

### Панель управления

Для `/agent/` и встроенных страниц `/framed/…` необходимы разрешения на инлайн-скрипты и стили (`'unsafe-inline'`), локальные изображения `data:` и звуковые уведомления. В частности, стили компонентов создаются в браузере, поэтому разрешения только на CSS-файлы со своего домена недостаточно. Хеш или nonce в одной директиве вместе с `'unsafe-inline'` отключает `'unsafe-inline'`. Webim nonce не подставляет, а стили, созданные уже в браузере, постоянным хешем не закрыть.

```nginx
set $csp "default-src 'none';";
set $csp "$csp script-src 'self' 'unsafe-inline';";
set $csp "$csp style-src 'self' 'unsafe-inline';";
set $csp "$csp img-src 'self' data:;";
set $csp "$csp font-src 'self';";
set $csp "$csp media-src 'self';";
set $csp "$csp connect-src 'self';";
set $csp "$csp frame-src 'self';";
set $csp "$csp frame-ancestors 'self';";
set $csp "$csp base-uri 'self';";
set $csp "$csp form-action 'self';";
set $csp "$csp object-src 'none';";
set $csp "$csp manifest-src 'self';";
add_header Content-Security-Policy-Report-Only $csp always;
```

Заголовок должен приходить с HTML-ответами как `/agent/`, так и `/framed/…`. Директива `frame-ancestors 'self'` позволяет открывать внутренние страницы в Панели управления, но не разрешает встраивание Панели управления в стороннюю CRM. Для CRM применяется [отдельная настройка](#crm). `frame-ancestors` не берётся из `default-src`: если директиву убрать, ограничение предков исчезнет. В `/agent/` и `/auth/` есть `<base href="/">`, поэтому в примерах стоит `base-uri 'self'`, а не `'none'`.

При использовании встроенных отчётов или кнопки обращения в поддержку с другого домена добавьте соответствующий адрес в `frame-src` страницы, открывающей фрейм. На стороне встраиваемого сервиса его `frame-ancestors` также должен разрешать источник Панели управления.

### Вход и восстановление доступа

Страницы `/auth/` используют динамически добавляемые стили и шрифты Google Fonts. Поэтому для стилей предусмотрено `'unsafe-inline'`, а для шрифтов — соответствующие внешние источники.

```nginx
set $csp "default-src 'none';";
set $csp "$csp script-src 'self';";
set $csp "$csp style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;";
set $csp "$csp img-src 'self';";
set $csp "$csp font-src 'self' https://fonts.gstatic.com;";
set $csp "$csp media-src 'none';";
set $csp "$csp connect-src 'self';";
set $csp "$csp frame-src 'self';";
set $csp "$csp frame-ancestors 'self';";
set $csp "$csp base-uri 'self';";
set $csp "$csp form-action 'self';";
set $csp "$csp object-src 'none';";
set $csp "$csp manifest-src 'self';";
add_header Content-Security-Policy-Report-Only $csp always;
```

`script-src 'self'` — начальный вариант для входа и восстановления доступа. Если итоговый HTML содержит инлайн-скрипты или обработчики событий и браузер фиксирует их блокировку, может потребоваться `'unsafe-inline'` либо изменение способа подключения этих скриптов.

Если при регистрации используется reCAPTCHA, необходимо дополнительно разрешить её скрипты, фреймы и сетевые обращения к Google. **Измените существующие строки** `script-src`, `frame-src` и `connect-src`, добавив требуемые источники; не добавляйте вторые директивы с теми же именами. Их точный перечень проверяйте по запросам браузера.

Если Панель управления встроена в CRM, страница повторного входа открывается в том же iframe. Поэтому источник CRM должен быть разрешён в `frame-ancestors` не только для `/agent/` и `/framed/`, но и для `/auth/`.

### Чат посетителя

Для документа `/visitor/chat` нужны инлайн-скрипты и стили, доступ к ресурсам Webim и разрешение на локальные `blob:`-адреса предпросмотра файлов.

```nginx
set $csp "default-src 'none';";
set $csp "$csp script-src 'self' 'unsafe-inline';";
set $csp "$csp style-src 'self' 'unsafe-inline';";
set $csp "$csp img-src 'self' blob:;";
set $csp "$csp font-src 'self';";
set $csp "$csp media-src 'self';";
set $csp "$csp connect-src 'self';";
set $csp "$csp frame-src 'self';";
set $csp "$csp frame-ancestors 'self' https://shop.client.local;";
set $csp "$csp base-uri 'self';";
set $csp "$csp form-action 'self';";
set $csp "$csp object-src 'none';";
add_header Content-Security-Policy-Report-Only $csp always;
```

Замените `https://shop.client.local` на источник сайта, в котором открывается чат. Если чат встраивается на нескольких сайтах, перечислите все разрешённые источники в одной директиве `frame-ancestors`. Для каждого указывайте схему, домен и при необходимости порт. При наличии внешних изображений или звуков добавляйте их источники в `img-src` и `media-src` соответственно.

Способ настройки самого iframe приведён в статье [«Встраивание виджета чата через iframe»](https://webim.ru/kb/devops/widget-iframe.html).

## CSP сайта с виджетом

Если Webim подключён к стороннему сайту, CSP этого сайта настраивается отдельно. В неё **добавляют разрешения для ресурсов Webim, сохраняя существующие разрешения сайта**. Не заменяйте политику сайта целиком приведёнными выше примерами с `default-src 'none'`.

При изменении директивы учитывайте её текущее значение: если отдельной директивы `script-src`, `img-src` или `connect-src` нет, браузер использует `default-src`. Добавляя отдельную директиву, перенесите в неё также необходимые разрешения из действующего `default-src`. Например, при `default-src 'self'` новая `img-src` должна сохранить `'self'`, если изображения самого сайта должны продолжать загружаться.

Требования зависят от способа подключения:

| Способ | Что учесть в CSP сайта |
| --- | --- |
| **Стандартная кнопка** | Источник скрипта Webim в `script-src`; разрешение для инлайн-скрипта установки и динамических стилей (обычно `'unsafe-inline'` при отсутствии другого допустимого механизма); адреса HTTP(S)-запросов и WebSocket в `connect-src`; хост чата в `img-src` и `media-src`, потому что страница сама запрашивает изображения и звуки чата; `blob:` в `img-src`, если предпросмотр выполняется на странице сайта |
| **Простой HTML iframe** | Адрес сервера чата в `frame-src`. Скрипт кнопки и `'unsafe-inline'` в `script-src` сайта для самого iframe не требуются |
| **Управляемый iframe** | Источник `iframe-helper.js` в `script-src`, адрес чата в `frame-src` и разрешение на инлайн-код инициализации, если он используется |

В стандартной кнопке часть логики выполняется на самой странице сайта. Поэтому её `connect-src` может потребовать конкретные источники `https://chat.client.local` и `wss://chat.client.local`. На странице, открытой по HTTP, сокет диалога обычно идёт на `ws://chat.client.local`, если не включён `force_visitor_https`; совместный просмотр и в этом случае использует `wss://`. Скрипт кнопки подключает код виджета по `https://`. Изображения и звуки чата, которые запрашивает сама страница, добавляйте в `img-src` и `media-src`, а не в `connect-src`. В iframe запросы документа `/visitor/chat` регулирует CSP этого документа, а не родительской страницы.

Подробная установка описана отдельно: [стандартная кнопка](https://webim.ru/kb/getting-started/install-button.html), [виджет в iframe](https://webim.ru/kb/dev/iframe.html) и [JavaScript API виджета Webim](https://webim.ru/kb/dev/api/webim-js-api.html). Для управляемого iframe используется `iframe-helper.js`; настройки и обработчики событий следует брать из соответствующей инструкции.

### WebSocket

Webim использует WebSocket для обмена сообщениями. При работе по HTTPS соединение обычно устанавливается по `wss://` с сервером чата; совместный просмотр также использует защищённый WebSocket. Соединения контролируются директивой `connect-src` документа, который их открывает.

В примерах для документов Webim указано `connect-src 'self'`. Если браузер блокирует WebSocket, добавьте точный адрес сервера с соответствующей схемой, например `wss://chat.client.local`. Не разрешайте схему `wss:` без указания хоста: это расширит доступ ко всем WebSocket-серверам.

## Встраивание Панели управления в CRM { #crm }

Для встраивания Панели управления в CRM необходимо согласовать политики обеих сторон:

- в CSP страницы CRM разрешить сервер Панели управления через `frame-src`;
- в `frame-ancestors` документов `/agent/`, `/framed/` и `/auth/` разрешить источник CRM, сохранив `'self'` для внутренних фреймов Webim.

Например, в соответствующем фрагменте nginx замените **имеющуюся строку** `frame-ancestors` на:

```nginx
set $csp "$csp frame-ancestors 'self' https://crm.client.local;";
```

Для каждого документа должна остаться только одна директива `frame-ancestors`. Обмен событиями через `postMessage` настраивается отдельно и сам по себе не разрешает встраивание. См. [«Встраивание Панели управления через iframe»](https://webim.ru/kb/devops/admin-iframe.html) и [интерфейс postMessage для CRM](https://webim.ru/kb/dev/postmessage.html).

Если сервер уже выдаёт `X-Frame-Options`, учитывайте его при проверке. В современных Chrome и Firefox принудительная CSP с `frame-ancestors` имеет приоритет над X-Frame-Options; режим `Content-Security-Policy-Report-Only` такого эффекта не даёт. Несколько принудительных CSP на одном ответе действуют одновременно: более широкий список источников в одном заголовке не отменит ограничений второго. Когда полную политику переводите на `Content-Security-Policy`, не оставляйте второй принудительный заголовок из статей про [панель](https://webim.ru/kb/devops/admin-iframe.html) и [виджет](https://webim.ru/kb/devops/widget-iframe.html): перенесите источник CRM или сайта в `frame-ancestors` одной политики.

## Настройка nginx

Примеры CSP нужно добавлять в конфигурацию nginx для **конечных HTML-ответов** соответствующих страниц. Расположение конфигурационных файлов и набор `location` зависят от установки Webim. В одном `location` могут обрабатываться и HTML, и другие ресурсы. Внутренний `rewrite` также может изменить обработчик запроса, поэтому наличие заголовка проверяйте по фактическому ответу страницы.

По умолчанию `add_header` наследуется из вышестоящего контекста только при отсутствии собственных `add_header` в текущем `location`. При добавлении CSP сохраняйте необходимые заголовки, в частности `Strict-Transport-Security` и CORS, если они применяются к этому ответу. Параметр `always` не меняет правила наследования.

В новых версиях nginx на наследование может влиять `add_header_inherit`. Проверьте действующую конфигурацию, прежде чем добавлять новые правила: объединение заголовков может привести к нескольким принудительным CSP. Они не объединяют разрешения, а применяются одновременно. Не добавляйте `'unsafe-eval'` без подтверждённой необходимости и не включайте `upgrade-insecure-requests`, если требуемые ресурсы недоступны по HTTPS.

Для облачного аккаунта изменения серверной CSP выполняются на стороне Webim. При самостоятельном размещении проверьте конфигурацию nginx своей установки. После обновления сервера или конфигурации убедитесь, что необходимые заголовки сохранились.

## Проверка и применение

Настройку CSP рекомендуется предварительно проверять на тестовом контуре.

1. Сохраните копию действующей конфигурации nginx.
2. Добавьте нужные фрагменты с заголовком `Content-Security-Policy-Report-Only`. Проверьте конфигурацию командой `nginx -t` и примените её перезагрузкой nginx.
3. Убедитесь, что заголовок присутствует в конечных HTML-ответах `/agent/`, `/auth/signin`, `/visitor/chat` и используемых страниц `/framed/`. Например:

    ```bash
    curl -sD - -o /dev/null https://chat.client.local/agent/
    ```

    Проверяйте GET-запросы и конечные адреса после перенаправлений. Для авторизованных страниц используйте браузерную сессию.
4. Проверьте в Chrome и Firefox вход и повторную авторизацию, работу Панели управления, сообщения, WebSocket, звуковые уведомления, вложения и виджет на сайте. Дополнительные функции (CRM, reCAPTCHA, отчёты) проверяйте, если они используются.
5. По сообщениям консоли разрешайте только необходимые источники в соответствующих директивах. Если нарушается встраивание iframe, дополнительно проверьте `frame-ancestors` и `X-Frame-Options` в режиме принудительной CSP: Report-Only не отменяет действующие ограничения встраивания.
6. После успешной проверки замените заголовок на `Content-Security-Policy`, снова выполните `nginx -t`, примените конфигурацию и повторите проверку. Избегайте конфликтующих принудительных CSP на одном HTML-ответе.

Если после изменения CSP перестала работать часть интерфейса, проверьте в консоли заблокированный ресурс и его директиву. При необходимости восстановите сохранённую конфигурацию, проверьте её через `nginx -t` и перезагрузите nginx. Перезапуск других служб Webim для изменения HTTP-заголовка не требуется.

---

Источник: https://webim.ru/kb/devops/content-security-policy.html
