Перейти к содержанию

Настройка хеширования паролей операторов (password_hashers)

Параметр password_hashers позволяет задать список поддерживаемых алгоритмов хеширования паролей операторов и управлять миграцией на новый алгоритм без принудительного сброса всех паролей.

Механика рассчитана на сценарий «прозрачной миграции»: сервер продолжает принимать старые хэши, а после успешного входа оператора пароль автоматически перехешируется по «новому» алгоритму и будет сохранён в базе.

Где настраивается

Настройки читаются из конфигураций Webim Server:

  • main.ini и файлы в /etc/webim/main.ini.d/*.ini

  • main.json и файлы в /etc/webim/main.json.d/*.json

Используемые параметры:

  • password_salt (в main.ini) — «наследуемая» соль для md5 по умолчанию, если список хешеров не задан.

  • password_hashers (в main.json) — список конфигураций хеширования.

Важно про merge main.json

В ряде компонентов (включая Admin Backend) JSON-настройки из main.json и main.json.d/*.json объединяются, при этом списки конкатенируются.
Поэтому password_hashers рекомендуется задавать ровно в одном файле и одним списком, чтобы не получить дубликаты/«двойные» конфигурации.

Параметр password_hashers

password_hashers — это список объектов, порядок элементов в списке имеет значение:

  • первый элемент используется для проверки хэшей без префикса {id} (наследуемые значения);

  • последний элемент считается «актуальным» и используется для хеширования новых паролей и перехеширования при успешном входе.

Формат элемента списка

Поле Тип Обязательно Описание
id string да Идентификатор конфигурации хеширования. Используется как префикс в БД: {id}<hash>.
algo string да Алгоритм хеширования.
salt string да Соль. Для md5/sha256 используется как префикс: salt + password. Для argon2 не применяется (рекомендуется оставить пустой строкой).

Требования к id

  • id должен быть уникальным в пределах списка.

  • Рекомендуемый набор символов: A–Z, a–z, 0–9, _, -.

  • Скобки {} в id указывать не нужно — они добавляются системой при сохранении хэша.

Поддерживаемые значения algo

  • md5

  • sha256

  • argon2

Совместимость по компонентам

Перед включением argon2 убедитесь, что в вашем контуре аутентификация операторов выполняется компонентами, которые его поддерживают. Если есть компоненты, которые проверяют пароль через стандартные md5/sha256 (без argon2-проверки), вход операторов может перестать работать.
Универсальный вариант для миграции — md5 → sha256.

Требования к salt

  • Для md5/sha256 хэш вычисляется от строки salt + password.

  • Рекомендуется использовать ASCII-строку (чтобы исключить проблемы с кодировками между компонентами).

  • Если соль не нужна — задайте пустую строку: "salt": "".

Формат хранения хэша в БД

Пароль оператора хранится в таблице chatoperator, поле password (в hosted-окружениях часто используется схема webim_hosted_meta).

Возможные форматы значения:

  • без идентификатора (наследуемый формат):

    • 82e8fe7e1194b8ce42addb5374ccb047

  • с идентификатором хешера:

    • {md5-default}82e8fe7e1194b8ce42addb5374ccb047

    • {new-default}62d045c783245ca1ce9e98b21f67825005110adca59a8f36e5dab731cc4b422c

Как работает миграция и перехеширование

  1. При входе система определяет, какой хешер применить:

    • если пароль в БД имеет префикс {id}, используется конфигурация с этим id;

    • если префикса нет — используется первый элемент списка password_hashers.

  2. Если вход успешен и текущий хешер не является актуальным (обычно не последний в списке), пароль будет перехеширован по актуальному алгоритму и сохранён обратно в БД (с префиксом {id} для актуального хешера).

Пример: переход с md5 на sha256

Ниже — практический сценарий миграции по схеме «сохраняем поддержку md5, добавляем sha256 как актуальный».

1. Предусловие: текущие пароли — md5

Пример md5: - pazzword → 82e8fe7e1194b8ce42addb5374ccb047

Перед применением конфигурации рекомендуется убедиться, что текущие значения действительно соответствуют md5 (32 hex-символа) и не содержат префиксов {id}.

PostgreSQL (пример):

SELECT operatorid, email, password
FROM webim_hosted_meta.chatoperator
WHERE password !~ '^[0-9a-fA-F]{32}$';

MySQL (пример):

SELECT operatorid, email, password
FROM webim_hosted_meta.chatoperator
WHERE password NOT REGEXP '^[0-9a-fA-F]{32}$';

Если запрос возвращает строки — разберите причины до миграции (часть паролей уже могла быть в другом формате).

2. Определите текущую соль md5 (password_salt)

Соль берётся из /etc/webim/main.ini и/или файлов в /etc/webim/main.ini.d/*.ini (в hosted-контуре часто встречается /etc/webim/main.ini.d/hosted-main.ini).

Пример проверки:

grep -R "^[[:space:]]password_salt" /etc/webim/main.ini /etc/webim/main.ini.d/.ini

Соль может быть пустой:

  • password_salt = ""

3. Добавьте список хешеров в main.json

Создайте/измените файл /etc/webim/main.json.d/main.json и задайте список password_hashers.

Пример: соль была и осталась пустой:

{
"partner_settings": {
"default": {
"domain": ""
}
},
"password_hashers": [
{"algo": "md5", "salt": "", "id": "md5-default"},
{"algo": "sha256", "salt": "", "id": "new-default"}
]
}

Если у вас уже задан password_salt, то для md5 укажите ту же соль, чтобы старые пароли продолжили проверяться корректно:

"password_hashers": [
{"algo": "md5", "salt": "<текущая_соль_password_salt>", "id": "md5-default"},
{"algo": "sha256", "salt": "<новая_соль>", "id": "new-default"}
]

Если у вас версия, где параметр называется password_hashing

В некоторых версиях параметр в main.json мог называться password_hashing. Если в вашем релизе password_hashers не применяется, используйте аналогичную структуру под ключом password_hashing.

4. Перезапустите сервисы, читающие конфигурацию

После сохранения изменений перезапустите сервисы и проверьте статус:

systemctl restart webim-tornado
systemctl restart webim-admin-backend

systemctl status webim-admin-backend
systemctl status webim-tornado

5. Проверьте перехеширование после входа

После первого успешного логина оператором его пароль будет сохранён по актуальному алгоритму (sha256) и, как правило, с префиксом {new-default}.

Пример sha256:

  • pazzword → 62d045c783245ca1ce9e98b21f67825005110adca59a8f36e5dab731cc4b422c

  • в БД: {new-default}62d045c...

Проверка «остались ли md5 без префикса» (PostgreSQL пример):

SELECT count(*)
FROM webim_hosted_meta.chatoperator
WHERE password ~ '^[0-9a-fA-F]{32}$';

Рекомендации эксплуатации

  • Не удаляйте md5-хешер из списка, пока не убедитесь, что все пароли мигрировали на новый формат (или пока не выполните принудительную смену пароля всем операторам).

  • Не меняйте id уже используемого хешера: иначе система не сможет сопоставить {id} в БД с конфигурацией.

  • Для миграции между md5 и sha256 используйте разные id (например, md5-default и new-default).

  • Соль храните как секрет (как минимум ограничьте доступ к файлам /etc/webim/main.ini* и /etc/webim/main.json*).