# Чек-лист внедрения аутентификации Manticore в продакшн

Чек-лист внедрения аутентификации в Manticore Search: инвентаризация клиентов, создание пользователей с минимальными привилегиями, тестирование в staging, переключение и безопасное устранение неполадок

В проде «включил и готово» почти никогда не работает. Технически это 4 шага: auth, рестарт, админ, обновить клиентов. На практике это почти всегда ломает что‑то неочевидное: ночной воркер, скрипты админа, BI‑дашборд, который никто не трогал полгода.

Поэтому считайте это не настройкой, а мини‑релизом: сначала инвентаризация клиентов, потом тесты, и только потом переключение. Так вы заранее увидите, где будут отказы, и не будете чинить всё в авральном режиме.

Этот чек-лист написан для пользователей, которые планируют включить аутентификацию и хотят сделать это максимально безопасно для текущей системы. Помните, что аутентификация отключена, пока вы не настроите `auth`; после переключения клиенты, которые по-прежнему не передают учётные данные будут получать отказ.

## Этап 1. Инвентаризация перед любыми изменениями

Начните с того, что выпишите информацию о каждом клиенте (приложении или его обособленной части), который обращается к Manticore Search. Сделайте это до того, как будете править конфигурацию.

Что обычно стоит проверить:

- поисковые фронтенды приложений
- воркеры, загружающие данные
- cron-задачи
- дашборды и BI-инструменты
- инструменты поддержки и администрирования
- скрипты изменения/обновления схемы
- скрипты резервного копирования и обслуживания
- локальные скрипты, которые запускаются вручную

Для каждого клиента запишите примерно следующее:

| Клиент | Протокол | Таблицы или кластеры | Нужные действия | Примечания |
|---|---|---|---|---|
| приложение поиска по товарам | HTTP | `products` | `read` | будет использовать Bearer-токен |
| воркер, загружающий каталог | SQL | `products` | `write` | использует парольную аутентификацию |
| задача миграции схемы | SQL | `products` | `schema` | запускается только во время деплоя |
| администратор доступа | SQL | `*` | `admin` | управляет пользователями и правами |

Затем уточните базовые параметры развёртывания:

- Вы работаете в RT-режиме или в plain-режиме?
- В plain-режиме — где должен находиться файл аутентификации?
- Настроен ли `pid_file` в конфиге? Он нужен для инициализации.
- Будут ли SQL-клиенты использовать SSL, а HTTP-клиенты — HTTPS, когда учётные данные передаются по сети?
- Где будут безопасно храниться учётные данные, включая временные Bearer-токены?
- Кому разрешено видеть пароль первого администратора?

Не пропускайте два последних пункта. `CREATE USER` возвращает Bearer-токен в открытом виде; `TOKEN` генерирует новый токен для указанного пользователя. `SHOW TOKEN` позже показывает сохранённый хеш токена, а не сам токен в открытом виде. Если токен в открытом виде потерян, смените его командой `TOKEN` и обновите токен в вашем приложении.

## Этап 2. Задание пользователей с минимальными правами

Создавайте пользователей под задачи, а не под догадки о том, что может пригодиться потом.

Используйте небольшую матрицу вроде такой:

| Нагрузка | Пользователь | Права |
|---|---|---|
| поисковый фронтенд | `app_read` | `GRANT read ON 'products' TO 'app_read'` |
| воркер, загружающий данные | `app_ingest` | `GRANT write ON 'products' TO 'app_ingest'` |
| задача миграции схемы | `schema_job` | `GRANT schema ON 'products' TO 'schema_job'` |
| оператор аутентификации | `security_admin` | `GRANT admin ON * TO 'security_admin'` |

Держите в уме, что `admin` — это узкое право. Оно всего лишь даёт управлять состоянием аутентификации и авторизации, но не подразумевает `read`, `write`, `schema` или `replication`.

Это важно, так как человеку, который управляет учётными данными, не обязательно читать бизнес-данные. Сервису, который ищет товары, не нужно записывать документы. Задаче миграции не нужно управлять пользователями.

Сразу спланируйте и проверки на запрет. Для каждого создаваемого пользователя выберите хотя бы одно действие, которое ему должно быть разрешено, и одно — которое должно быть запрещено.

Примеры:

- `app_read` может искать по `products`.
- `app_read` не может вставлять данные в `products`.
- `app_ingest` может писать в `products`.
- `app_ingest` не может управлять аутентификацией.
- `schema_job` может менять схему `products`.
- `schema_job` не может читать таблицы, пока вы не выдадите `read`.

## Этап 3. Тестирование в staging

Используйте staging-окружение, чтобы заранее отработать последовательность действий, запланированную для продакшена.

В RT-режиме:

```ini
searchd {
    data_dir = /var/lib/manticore
    auth = 1
    auth_log_level = info
    ...
}
```

Чтобы явно отключить аутентификацию в RT-режиме:

```ini
searchd {
    data_dir = /var/lib/manticore
    auth = 0
    ...
}
```

В plain-режиме:

```ini
searchd {
    auth = /var/lib/manticore/auth.json
    auth_log_level = info
    ...
}
```

Ограничьте доступ к файлу аутентификации. До первой инициализации Manticore Search может создать пустой файл аутентификации. После инициализации в этом файле хранятся данные аутентификации и хеши учётных данных.

Запустите `searchd`, затем создайте первого администратора:

```bash
searchd --config /etc/manticoresearch/manticore.conf --auth
```

Для настройки через скрипт:
```bash
printf 'admin\nStrongPass#2026\nStrongPass#2026\n' | \
  searchd --config /etc/manticoresearch/manticore.conf --auth-non-interactive
```
⚠️ Внимание: пароль в этом случае передаётся в открытом виде в командной строке и может попасть в историю команд и список процессов. Используйте только в безопасной среде.

Эта команда создаёт первого администратора и наделяет этого пользователя всеми правами. Bearer-токен при этом не возвращается. Если этому администратору нужен доступ по HTTP Bearer, подключитесь под администратором и выполните `TOKEN` или используйте HTTP-эндпоинт `POST /token`.

Далее создайте пользователей для staging исходя из ваших заметок с прошлых этапов. Например:

```sql
CREATE USER 'app_read' IDENTIFIED BY 'ReadPass#2026';
GRANT read ON 'products' TO 'app_read';

CREATE USER 'app_ingest' IDENTIFIED BY 'IngestPass#2026';
GRANT write ON 'products' TO 'app_ingest';

CREATE USER 'schema_job' IDENTIFIED BY 'SchemaPass#2026';
GRANT schema ON 'products' TO 'schema_job';

CREATE USER 'security_admin' IDENTIFIED BY 'AdminPass#2026';
GRANT admin ON * TO 'security_admin';
```

Сохраните возвращённые Bearer-токены в безопасном хранилище. Помните: токены в открытом виде нельзя оставлять в логах, истории команд или незащищённых файлах. Если нужно сменить какой-то из них, используйте:

```sql
TOKEN 'app_read';
```

`SHOW TOKEN` не позволяет восстановить токен в открытом виде:

```sql
SHOW TOKEN FOR 'app_read';
```

Просмотрите пользователей и права:
```sql
SHOW USERS;
SHOW PERMISSIONS;
SHOW PERMISSIONS FOR 'app_read';
```

Выполните один тест на разрешение и один на запрет доступа для каждого пользователя. Для пользователя с доступом только на чтение:
```bash
curl -H "Authorization: Bearer <app_read_token>" \
  http://127.0.0.1:9308/sql?mode=raw \
  -d "SELECT * FROM products LIMIT 10"
```

Затем проверьте ситуацию, когда прав не хватает:
```bash
curl -H "Authorization: Bearer <app_read_token>" \
  http://127.0.0.1:9308/sql?mode=raw \
  -d "INSERT INTO products(id,title) VALUES(1,'test')"
```

Для этой проверки по HTTP ожидайте `403 Forbidden`. По SQL/MySQL при нехватке прав вернётся `ERROR 1045` с сообщением об отказе в доступе.

SQL-клиенты должны подключаться с именем пользователя и паролем Manticore Search. Протокол SQL/MySQL в Manticore поддерживает `mysql_native_password`.

```bash
MYSQL_PWD=ReadPass#2026 \
  mysql -h127.0.0.1 -P9306 -uapp_read \
  -e "SELECT * FROM products LIMIT 10"
```

HTTP-клиенты могут использовать Basic-аутентификацию или Bearer-токены:

```bash
curl -u app_read:ReadPass#2026 \
  http://127.0.0.1:9308/sql?mode=raw \
  -d "SELECT * FROM products LIMIT 10"
```

HTTP-схемы аутентификации (`Basic`, `Bearer`) нечувствительны к регистру; имена пользователей — чувствительны.

Если во время обслуживания вы правите файл аутентификации в обход демона, перезагрузите его:

```sql
RELOAD AUTH;
```

## Этап 4. Чек-лист внедрения в продакшен

Используйте это как чек-лист на момент переключения. Можете даже распечатать и ставить галочки.

- [ ] Убедитесь, что у вас есть актуальная резервная копия конфигурации.
- [ ] Убедитесь, что существующие сетевые меры защиты продолжают действовать.
- [ ] Убедитесь, что `pid_file` задан в конфиге.
- [ ] Уточните, где будет создан или откуда будет загружен файл аутентификации.
- [ ] Убедитесь, что хранилище для паролей и токенов готово.
- [ ] Включайте аутентификацию в заранее запланированное технологическое окно.
- [ ] Проверить, что после включения аутентификации клиенты без учётных данных начинают получать отказ.
- [ ] Создайте первого администратора.
- [ ] Создайте пользователей и права для продакшена.
- [ ] Сохраняйте токены сразу после выдачи в защищённое хранилище секретов. Не храните токены в открытом виде ни в файлах, ни в истории команд, ни в логах.
- [ ] Обновите код подключения через SQL, чтобы он отправляли имена пользователей и пароли.
- [ ] Обновите код подключения через HTTP, чтобы он использовал Basic-аутентификацию или Bearer-токены.
- [ ] Выполните тесты на разрешение и запрет доступа из staging.
- [ ] Проверьте журнал аутентификации.
- [ ] Проведите стресс-тестирование приложения, охватывающее поиск, загрузку данных, дашборды и скрипты обслуживания.
- [ ] Смените любые временные учётные данные, использованные при внедрении.
- [ ] Не используйте учётные данные первого администратора в обычной работе приложений.

Когда аутентификация включена, события аутентификации пишутся в отдельный журнал. Если журнал демона — `/var/log/manticore/searchd.log`, то журнал аутентификации — `/var/log/manticore/searchd.log.auth`.

Значения `auth_log_level`:

- `disabled`
- `error`
- `warning`
- `info`
- `all`
- `trace`

По умолчанию — `info`. Начните с этого, если только нет причин делать логи ещё тише или, наборот, детальнее. Используйте `trace` только для диагностики; в него попадает в том числе весь успешный внутренний трафик аутентификации.

Полезные команды для очистки и обслуживания:
```sql
SET PASSWORD 'NewReadPass#2026' FOR 'app_read';
REVOKE read ON 'products' FROM 'app_read';
DROP USER 'app_read';
```

`SET PASSWORD` меняет пароль, используемый для SQL/MySQL и HTTP Basic-аутентификации. Эта команда не отзывает существующие Bearer-токены. Чтобы сменить Bearer-токен, создайте новый с помощью `TOKEN` или `POST /token` и обновите клиента.

## Этап 5. Откат и разбор проблем

Если вдруг что-то пошло не так, то откат должен быть скучным:
- восстановите прежнюю конфигурацию
- перезапустите Manticore
- восстановите старые способы ограничения доступа, которые были до внедрения аутентификации
- также будьте готовы откатить конфигурацию приложений, если клиентов уже перевели на новые учётные данные.

Не удаляйте заметки о внедрении. Обычно это самый быстрый способ понять, какого клиента обновили, какой токен где сохранили и какие права создали.

| Симптом | Вероятная причина | Что проверить |
|---|---|---|
| Отказ в доступе по SQL | Неверный пользователь, неверный пароль или несовпадение способа аутентификации клиента | Проверьте настроенного пользователя и убедитесь, что клиент умеет `mysql_native_password`. |
| HTTP 401 | Отсутствующие или неверные учётные данные | Проверьте заголовок `Authorization` и то, использует ли клиент Basic-аутентификацию или аутентификацию по Bearer-токену. |
| HTTP 403 | Пользователь прошёл аутентификацию, но ему не хватает прав | Проверьте `SHOW PERMISSIONS FOR '<user>'`. |
| Bearer-токен больше не работает | Токен утерян, скопирован с ошибкой или уже отозван | Выполните `TOKEN '<user>'`, сохраните возвращённый токен и обновите клиента. |
| Пользователь может меньше, чем ожидалось | Не выдано право на действие | Проверьте, какое действие нужно операции: `read`, `write`, `schema`, `replication` или `admin`. |
| Пользователь может больше, чем ожидалось | Слишком широкая цель или отсутствие явного запрета | Проверьте права, выданные по маскам и на конкретные цели, а также любые правила `WITH ALLOW 0`. |

Правила доступа определяются по типу действия. При конфликте явный запрет всегда имеет приоритет над разрешением, даже если разрешение более специфично. Если подходящего разрешения нет, доступ запрещается.

## Особенности аутентификации в репликации

Если вы используете репликацию, то планируйте отдельное внедрение аутентификации. Чек-лист выше для одного узла по-прежнему полезен, но кластеры добавляют сценарии сбоев, которые легко упустить.

Запросы к распределённым удалённым агентам проходят аутентификацию от имени текущего пользователя сессии. Удалённому демону нужны совпадающие данные аутентификации этого пользователя и необходимое право на удалённую целевую таблицу.

Операции репликации используют действие `replication`. Выдавайте его только тому пользователю, который должен запускать операции репликации и отвечать за них.

Когда аутентификация включена, присоединение к кластеру может заменить локальные данные аутентификации данными кластера, к которому вы присоединяетесь. Перед присоединением убедитесь, что пользователь репликации и данные аутентификации согласованы между узлами. Относитесь к `searchd.log.auth` как к чувствительным данным во время работы с кластером, поскольку резервные копии аутентификации могут содержать соли и хеши учётных данных.

Полную процедуру миграции кластера вынесите в отдельный документ: здесь важно лишь обозначить риски, связанные с аутентификацией в кластере.

## Финальная проверка

Прежде чем считать внедрение завершённым убедитесь, что:

- [ ] У каждой обособленной части системы, использущей Manticore Search есть свой пользователь.
- [ ] У каждого пользователя — только те действия, которые ему нужны.
- [ ] Bearer-токены хранятся в защищённом хранилище секретов; токены в открытом виде не сохраняются вне контролируемой среды.
- [ ] Команда эксплуатации знает, что `SHOW TOKEN` не возвращает токен в открытом виде, а показывает его хеш; для получения нового токена нужно использовать `TOKEN` или HTTP-эндпоинт.
- [ ] SQL и HTTP-клиенты обновлены.
- [ ] Ожидаемые отказы проверены.
- [ ] Логи аутентификации доступны для просмотра.
- [ ] Процедура отката понятная и описана.

Желаем вам лёгкого внедрение аутентификации и авторизации!