Привет, Хабр!

Если ваша компания работает на российском рынке, то вы наверняка сталкивались с запросами клиентов на «вход через Госуслуги». В нашем BILLmanager за это отвечает модуль «Авторизация через ЕСИА». Он позволяет клиентам входить в BILLmanager через аккаунт на Госуслугах, упрощает регистрацию и проверку данных.

Сегодня мы рассмотрим, как настроить авторизацию через ЕСИА в BILLmanager 6. Разберём этот процесс шаг за шагом, чтобы сделать его максимально простым и понятным. Разложили все по полочкам — от установки самого модуля до работы с сертификатами. Сохраняйте, чтобы не потерять!

⚠️ Важно!

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

• Российский айпишник — наш лучший друг. Ваш сервер с BILLmanager должен находиться в РФ и иметь российский IP-адрес. Запросы из-за рубежа ЕСИА попросту блокирует.

• Для работы понадобится отечественный криптографический провайдер CryptoPro CSP, поскольку ЕСИА использует ГОСТ-шифрование. Не пугайтесь, мы подробно разберем и эту часть.

Начнем с самого простого — установки модуля прямо в интерфейсе BILLmanager.

Шаг 1. Установка модуля в BILLmanager 6

Начнем с самого простого — активации модуля прямо в интерфейсе BILLmanager. Хорошая новость в том, что в актуальных версиях BILLmanager 6 модуль «Авторизация через ЕСИА» уже входит в поставку. Нам не нужно ничего скачивать вручную — все делается в несколько кликов.

Как установить модуль:

1. Авторизуйтесь в панели BILLmanager под учетной записью с правами администратора.

2. Перейдите в раздел «Интеграция» → «Модули».

3. Найдите модуль «Авторизация через ЕСИА» (иногда он может называться Gosuslugi (ESIA)).

4. Нажмите кнопку «Установить».

Перед установкой рекомендуется создать резервную копию BILLmanager, так как при добавлении модуля платформа может обновиться до последней версии​. 

После успешной установки модуль нужно настроить. В том же разделе нажимаем на значок шестеренки напротив названия модуля — и перед нами откроется форма конфигурации.

Как заполнить форму и что вводить в полях:

• Госуслуги (ЕСИА) API URL – адрес API ЕСИА, по которому BILLmanager будет обращаться к Госуслугам. Для тестирования интеграции можно указать тестовый адрес https://esia-portal1.test.gosuslugi.ru/, а для боевой (промышленной) эксплуатации – https://esia.gosuslugi.ru/. Начните с тестового URL, если вы еще не получили одобрение на боевой доступ, и позже переключитесь на продуктивный адрес.

• Мнемоника ИС – это уникальный код вашей информационной системы, зарегистрированной в ЕСИА. Проще говоря, Мнемоника ИС – это идентификатор (набор букв и цифр), который присваивается вашей системе на стороне Госуслуг​. Вы получите этот код при подключении компании к ЕСИА (о процессе подключения поговорим в следующем шаге). Введите здесь свою мнемонику, например _BILLMGR или другой код, который вам выдадут.

• Сертификат – выберите сертификат вашей компании, который будет использоваться для электронной подписи запросов к ЕСИА. Этот сертификат мы установим на сервере позднее, на этапе настройки CryptoPro. После установки CryptoPro и загрузки сертификатов (этапы 3–4), в выпадающем списке здесь появится название вашего сертификата (например, по имени организации или выдавшего центра). Пока можно оставить поле пустым, если сертификат еще не установлен.

• Инвертировать подпись – опция, которую рекомендуется включить для корректной работы с ГОСТ-подписью. При активации этого флажка байты сформированной электронной подписи будут зеркально перевернуты. Эта тонкость связана с форматом ГОСТ; если не включить, ЕСИА может не принять вашу подпись. Поэтому ставим галочку «Инвертировать подпись» (если она не проставилась автоматически).

• Проверять подпись сообщений от Госуслуги (ЕСИА) – эта опция включает проверку цифровой подписи во входящих сообщениях от ЕСИА. Рекомендуется ее включить для безопасности: BILLmanager будет проверять, что ответы действительно подписаны действующим ключом Госуслуг и не были подделаны.

• Сертификат Госуслуги (ЕСИА) – в этом поле нужно выбрать публичный сертификат ЕСИА, которым подписываются ответы от Госуслуг​. Этот сертификат мы тоже установим на сервере вручную. После установки он отобразится в списке, и его следует указать здесь, чтобы BILLmanager знал, каким сертификатом проверять подпись ответов.   

Заполнив все поля, нажмите OK для сохранения настроек. Если на данном этапе у вас еще нет необходимых данных (например, сертификатов или мнемоники), вы можете вернуться к настройкам позже – модуль сохранит заполненные поля. Главное, чтобы к моменту боевого запуска все поля были корректно заполнены.

После установки модуля перейдите в настройки провайдера и установите галочку  «Авторизация через Госуслуги (ЕСИА)»

Шаг 2. Подключение к промышленной среде ЕСИА

Для работы модуля в реальной (продуктивной) среде необходимо официально подключить вашу организацию к системе ЕСИА. Это происходит вне самой панели BILLmanager – потребуется взаимодействие с Министерством цифрового развития, которое курирует ЕСИА. 

Давайте по порядку разберем, что нужно сделать.

1. Подайте заявку в Минцифры на подключение вашей информационной системы к ЕСИА (порталу «Госуслуги»).

В заявке необходимо указать сведения о вашей организации и системе. Обычно требуется, чтобы ваша организация относилась к числу уполномоченных (госучреждение, банк, страховая компания, оператор платежной или информационной платформы и т. д.) – это связано с регламентом допуска к ЕСИА​. 

В рамках заявки вам предоставят доступ к тестовой среде, а после проверок – разрешение на подключение к промышленной среде ЕСИА.

2. При оформлении заявки обязательно укажите требуемые области доступа (scope) – перечень данных пользователя, которые ваша система будет запрашивать у ЕСИА. 

Здесь важно соблюдать принцип разумной достаточности — запрашивать только то, что действительно необходимо для работы. Для интеграции BILLmanager, как правило, необходимы следующие scope: openid, email и fullname​.

Рекомендуем указывать только основные области для хостинг-провайдеров.

• openid – базовый идентификатор OpenID Connect, необходим для самой возможности единого входа;

• email – чтобы получать адрес электронной почты пользователя из его учетной записи Госуслуг;

• fullname – чтобы запросить ФИО пользователя.

Эти данные понадобятся, чтобы автоматически создавать или связывать учетную запись клиента в BILLmanager при входе через Госуслуги (например, подставить его имя и email, полученные из ЕСИА). Минцифры при рассмотрении заявки будет понимать, какие именно данные вашего клиента вы запросите у ЕСИА, поэтому указание scope – обязательная часть процесса.

3. Убедитесь, что вы выполняете все требования безопасности и регламенты при интеграции.

Существует официальный документ – «Регламент информационного взаимодействия участников с Оператором ЕСИА»​. Проще говоря, это свод правил и технических условий, которые ваша система должна соблюдать при работе с ЕСИА (защита данных, шифрование, процедуры идентификации и т.д.). Тщательно ознакомьтесь с этим регламентом и следуйте ему. Несоблюдение требований может привести к отказу в подключении или отключению интеграции.

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

• сертификат и ключи компании для работы с Госуслугами (ваши уникальные криптографические ключи);

• логин и пароль учетной записи компании в системе ЕСИА (для доступа к личному кабинету интегратора);

• мнемоника ИС (упомянутый ранее код информационной системы);

• публичные сертификаты ЕСИА для проверки подписи сообщений​.

Все эти компоненты понадобятся нам на следующих шагах для настройки CryptoPro и интеграции. Заметим, что на тестовой среде выдаются тестовые сертификаты и ключи, а для промышленной – боевые. Процесс их получения аналогичен, просто для боевой системы могут потребоваться дополнительные проверки и время.

Шаг 3. Установка серверного CryptoPro CSP 

Переходим к технической части – настройке криптографии на вашем сервере. Как уже упоминалось, для работы с электронными подписями по ГОСТ необходима платформа CryptoPro CSP. Без установленного CryptoPro модуль авторизации через ЕСИА работать не будет.

Установка CryptoPro CSP производится на уровне операционной системы (обычно на сервере Linux, где крутится BILLmanager).

1. Приобретите лицензию CryptoPro. CryptoPro CSP – коммерческий продукт, поэтому сначала нужно приобрести лицензию на его использование. Обычно достаточно базовой лицензии CSP для сервера. Установите лицензионный ключ согласно инструкции поставщика.

2. Установите компоненты LSB (Linux Standard Base). Перед установкой CryptoPro убедитесь, что в системе установлены пакеты LSB. LSB предоставляет стандартизированное окружение для программ – без него инсталлятор CryptoPro может выдать ошибку. Например, в Debian/Ubuntu достаточно выполнить команду:

apt-get install lsb-core

Эта команда установит необходимый пакет lsb-core (в дистрибутивах RedHat/CentOS аналогичным будет пакет redhat-lsb)​. 

3. Загрузите дистрибутив CryptoPro. Скачайте актуальную версию установочного пакета CryptoPro CSP с официального сайта компании КриптоПро​. На сайте доступна сертифицированная версия для Linux – обычно это архив.tar.gz или образ .rpm-пакетов, в зависимости от вашей ОС. Выберите дистрибутив, соответствующий вашей системе (например, для Debian/Ubuntu – DEB-пакеты, для CentOS/RedHat – RPM).

4. Установите ПО. Распакуйте скачанный архив и запустите установочный скрипт, который входит в поставку (обычно называется install.sh). Например, в каталоге с распакованным CryptoPro выполните:

sudo ./install.sh

Следуйте инструкциям скрипта: он скопирует необходимые библиотеки, спросит путь для установки (по умолчанию устанавливается в /opt/cprocsp) и зарегистрирует компоненты системы. После успешной инсталляции на сервере появятся утилиты CryptoPro. 

Нам особенно понадобятся csptest и certmgr (они устанавливаются в каталоге /opt/cprocsp/bin/amd64/).

Когда эти шаги выполнены, CryptoPro CSP будет готов к работе на сервере. Мы установили программное обеспечение, однако пока не загрузили наши ключи и сертификаты в систему.

Шаг 4. Установка сертификатов для работы с ЕСИА

Теперь у нас есть: полученные от ЕСИА данные – сертификат компании, ключи и публичный сертификат Госуслуг — и установленный CryptoPro CSP. 

Настало время импортировать эти ключи и сертификаты на сервер и связать их с нашим BILLmanager. Делается это с помощью утилит CryptoPro, через командную строку. 

1. Скопируйте на сервер файлы ключей и сертификатов, полученные от Минцифры/ЕСИА. 

Обычно это:

• файл сертификата вашей компании (в формате .cer);

• папка с закрытым ключом (название папки вида keys/XXXXXXXX.000/);

• файл публичного сертификата ЕСИА (например, esia.crt либо в формате .cer)​.

Поместите эти файлы в каталог, который использует CryptoPro для хранения ключей. Для суперпользователя (root) по умолчанию используется директория /var/opt/cprocsp/keys/root/​. 

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

bash

cp -r keys/XXXXXXXX.000/ /var/opt/cprocsp/keys/root/

Эта команда скопирует каталог с вашим закрытым ключом в хранилище CryptoPro для пользователя root​. Туда же скопируйте файлы .cer (сертификат компании и сертификат ЕСИА).

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

bash

/opt/cprocsp/bin/amd64/csptest -keyset -enum_cont -verifycontext -fqcn

В ответе должна появиться строка с именем вашего ключевого контейнера. Обычно она выглядит примерно так:

\\.\HDIMAGE\XXXXXXXX-0000-0000-0000-XXXXXXXXXXXX

Набор символов XXXXXXXX-... — это уникальный идентификатор, присвоенный вашему ключу CryptoPro. Запомните или скопируйте эту строку целиком – она понадобится для следующих команд. 

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

3. Снимите пароль с закрытого ключа. 

Вы получили закрытый ключ, защищенный паролем (его задают при выдаче сертификата; для тестовых сертификатов часто используется пароль по умолчанию, например 1234567890). Чтобы BILLmanager мог автоматически использовать ключ для подписи, необходимо убрать у ключа запрос пароля. 

Выполните команду:

bash

/opt/cprocsp/bin/amd64/csptest -passwd -change '' -cont '\\.\HDIMAGE\XXXXXXXX-0000-0000-0000-XXXXXXXXXXXX' -passwd 'ВАШ_ПАРОЛЬ'

• ВАШ_ПАРОЛЬ – текущий пароль от сертификата (например, 1234567890), 

• -change '' означает, что мы устанавливаем пустой пароль. 

• -cont должен содержать имя контейнера вашего ключа (тот самый идентификатор из предыдущего шага. 

После выполнения команды утилита должна сообщить об успешной смене пароля. Этот шаг крайне важен – если не снять пароль, авторизация через ЕСИА работать не будет​. BILLmanager не сможет использовать ключ, поскольку каждый раз потребуется ручной ввод пароля.

4. Установите публичный сертификат Госуслуг (ЕСИА). 

Это сертификат, которым ЕСИА подписывает свои ответы. Мы должны добавить его в доверенное хранилище, чтобы верифицировать подпись. Выполните команду:

bash

/opt/cprocsp/bin/amd64/certmgr -inst -file ESIA.cer

Замените ESIA.cer на имя файла публичного сертификата Госуслуг, который вы получили. Данная команда импортирует сертификат ЕСИА в хранилище CryptoPro как доверенный​. В случае успеха утилита certmgr вернет сообщение об успешной установке сертификата.

5. Установите сертификат вашей компании. Этот сертификат связывается с ранее загруженным закрытым ключом. Команда:

bash

/opt/cprocsp/bin/amd64/certmgr -inst -file Company.cer -cont '\\.\HDIMAGE\XXXXXXXX-0000-0000-0000-XXXXXXXXXXXX'

• Company.cer – имя файла сертификата вашей организации (в формате .cer);

• после -cont указываем идентификатор контейнера вашего ключа (как и в шаге 3)​. 

Этой командой мы устанавливаем сертификат и привязываем его к соответствующему закрытому ключу в хранилище CryptoPro. Если все сделано правильно, CryptoPro CSP теперь знает о вашем сертификате и связанном с ним ключе.

Возвращаемся в BILLmanager и финалим

На сервере теперь настроены все компоненты — установлен CryptoPro, импортированы ваш сертификат/ключ и доверенный сертификат ЕСИА. Мы на финишной прямой — модуль авторизации через ЕСИА практически готов к работе.

Самое время вернуться в BILLmanager и завершить настройку.

Снова открываем раздел «Интеграция» → «Модули», находим установленный модуль «Авторизация через ЕСИА» и жмем на шестеренку настроек. Перед нами — та самая форма, которую мы видели в начале. Теперь вы можете заполнить ее до конца, если не сделали этого на шаге 1.

В поле «Сертификат» выберите из списка ваш корпоративный сертификат (он должен отобразиться после установки в CryptoPro – обычно в формате «Название организации (даты валидности)»). В поле «Сертификат Госуслуги (ЕСИА)» выберите добавленный публичный сертификат ЕСИА (в списке он может отображаться по имени издателя или по дате). Убедитесь, что опции «Инвертировать подпись» и «Проверять подпись сообщений» включены (как мы ставили ранее). 

1. «Сертификат». Выберите из списка ваш корпоративный сертификат. Он должен отобразиться после установки в CryptoPro – обычно в формате «Название организации (даты валидности)».

2. «Сертификат Госуслуги (ЕСИА)». Выберите добавленный публичный сертификат ЕСИА. В списке он может отображаться по имени издателя или по дате.

3. Убедитесь, что опции «Инвертировать подпись» и «Проверять подпись сообщений» включены.

Жмем «ОК» и... вуаля! Настройка завершена.

Что увидит ваш клиент?

Теперь на странице входа в BILLmanager, рядом с полями для логина и пароля, появится кнопка «Войти через Госуслуги». После успешного входа через ЕСИА пользователь вернется в BILLmanager уже подтвержденным – система создаст ему аккаунт или привяжет к существующему (в зависимости от настроек), используя полученные от Госуслуг данные.

Сначала тестируем! 

Перед запуском интеграции в продакшн рекомендуем протестировать интеграцию в тестовой среде ЕСИА. Убедитесь, что авторизация проходит успешно, все данные подтягиваются корректно.

Если что-то пошло не так, ваш главный помощник — логи.

• BILLmanager ведет журнал обмена с ЕСИА в файле /usr/local/mgr5/var/omesia.log​.

• Установите максимальный уровень логирования и посмотрите сообщения в этом файле – там будут указаны ошибки или причины отказа. Это поможет выявить и устранить возможные неполадки.

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

А если вы еще не используете BILLmanager, но хотите познакомиться с возможностями платформы:

• скачайте бесплатный триал;

• получите доступ к демостенду;

• или запросите персональный показ.