© 2014 - 2024 esia.pro

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

1 Общее описание

Модуль авторизации для CMS Bitrix реализует набор функций написанных на языке программирования PHP и позволяющих организовывать взаимодействие с сервисами Единой системы идентификации и аутентификации (ЕСИА) по протоколу OAuth 2.0. Подробную информацию о данном протоколе и принципах взаимодействия с ЕСИА можно получить в методических рекомендациях по использованию ЕСИА

Важно учесть, что модуль авторизации поставляется в 2-х версиях базовой и расширенной. Основным отличием расширенной версии от базовой является возможность получения дополнительного набора сведений о пользователе (см. Приложение Б - Перечень запрашиваемых областей доступа). Условия поставки базовой или расширенной версии необходимо обговаривать заранее с Вашим персональным менеджером.

2 Перечень поставляемых файлов

В состав файлов, поставляемых с модулем, входят следующие:

• RndsEsiaOAuth2.php – модуль инициализации библиотеки авторизации через ЕСИА;
• component.php – модуль, реализующий основную логику работы компоненты Битрикс;
• fns – директория, содержащая модули реализующие функциональность компоненты;
• lib – директория библиотеки авторизации через ЕСИА;
• lib/OAuth2 – директория, в которой содержатся файлы библиотеки авторизации;
• lib/Keys – директория, в которой должны размещаться ключ и сертификат ИС (генерируются на стороне клиента ЕСИА);
• lib/Temp – директория, в которую модуль кладет временные файлы;
• lib/Log – директория лог-файлов.

3 Функции модуля

Основными функциями модуля авторизации являются:

• получение авторизационного кода ЕСИА;
• обмен авторизационного кода на маркер доступа;
• обмен маркера обновления на маркер доступа (без запроса авторизации пользователя на стороне ЕСИА);
• получение данных пользователя из ЕСИА (в приложении Б перечислены скоупы, которые может получать базовая и расширенная версии модуля);
• выход (логаут) на стороне ЕСИА;
• подписание запросов к ЕСИА на основе криптографических средств, установленных на удалённом сервере.

Дополнительными функциями модуля авторизации являются:

• объединение учётных записей пользователей Bitrix с учётными записями пользователей ЕСИА;
• авторизация пользователей в Bitrix без получения данных из защищённого хранилища ЕСИА;
• получение данных пользователей из защищённого хранилища ЕСИА без авторизации на стороне Bitrix;
• создание сессионного пользователя на стороне Bitrix;
• редирект пользователей с неподтверждённой УЗ в специальный раздел без авторизации;
• обновление данных пользователя авторизуемого через ЕСИА;
• добавление только подтверждённых данных в профиль пользователя авторизуемого через ЕСИА;
• авторизация пользователей ЕСИА с разными видами учётных записей (стандартная, подтверждённа);
• определение группы или групп пользователей, в которые будет добавлен пользователь после создания его УЗ на стороне Bitrix;
• использование разных средств подписания запросов направляемых в адреса сервисов ЕСИА. К таким средствам относятся openssl (установленный как локально, так и на удалённом сервере), Сайнер (сервис подписания запросов).

4 Интеграция библиотеки

Перед началом интеграции необходимо:

• выполнить конфигурирование OpenSSL, подключив gost-engine с поддержкой алгоритмов ГОСТ Р 34.10-2012 и ГОСТ Р 34.11- 2012. Если подписание происходит на стороне сервиса Signer (Jigner), то OpenSSL настраивать не нужно;
• настроить для вашей системы HTTPS (это обязательное требование, поскольку данные между вашей системой и ЕСИА передаются в открытом виде);
• выполнить экспорт ключевой пары (сформированной по ГОСТ2012) из криптоконтейнера (экспорт можно сделать с помощью нашей утилиты);
• настроить систему на технологическом портале тестовой/промышленной ЕСИА. На технологическом портале в окне редактирования параметров системы (см. рисунок 1) указать URL возврата после авторизации и логаута, а также установить алгоритм подписания запросов GOST3410_2012_256.

Для интеграции библиотеки необходимо выполнить следующие шаги описанные ниже.

Шаг 0. Установить необходимые зависимости, описанные в разделе 5.

Шаг 1. Распаковать архив с модулем в рабочей директории, в которую он должен быть установлен. Например, это может быть bitrix/components/rnds

Шаг 2. В директорию по умолчанию lib/Keys/GOST3410_2012_256 в рабочем каталоге библиотеки авторизации положить ключ и сертификат (с именами secret.key и cert.crt соответственно) в PEM формате (для извлечения ключа и сертификата из криптоконтейнера можно воспользоваться нашей утилитой), сформированные по ГОСТ2012 с длиной ключа 256 бит, и удостовериться, что тот же сертификат загружен на технологическом портале тестовой/промышленной ЕСИА. Если имена и директория файлов ключа и сертификата не соответствуют значениям по-умолчанию необходимо указать полный путь для них в параметрах OAuth2PkeyPath и OAuth2CertPath.

Шаг 3. В директорию по умолчанию lib/Keys/GOST3410_2012_256 в рабочем каталоге компоненты положить файл сертификата ЕСИА в PEM формате с именем esia-test.crt или esia-prod.crt в зависимости от окружения (тестовое/промышленное), в котором запускается код. Окружение устанавливается с помощью параметра OAuth2IsTestEnvironment. Если имя или директория файла сертификата не соответствуют значениям по-умолчанию необходимо указать полный путь в параметре OAuth2EsiaCertPath.

Поля в окне редактирования параметров системы

Шаг 4. ВАЖНО!!! Настроить доступ к директориям для размещения файлов сертификата, ключа и логов компоненты таким образом, чтобы их файлы нельзя было получить извне.

Шаг 5. При необходимости создать группу для пользователей авторизуемых через ЕСИА. Группа может называться, например, “Пользователи ЕСИА”. В дальнейшем, при настройке компоненты, понадобиться ID группы. Если создавать отдельную группу для пользователей авторизуемых через ЕСИА необходимости нет, то нужно выбрать какую-либо группу пользователей из списка существующих и при настройке компоненты использовать ее ID.

Шаг 6. Добавить раздел для передачи запроса на авторизацию в ЕСИА. В данном разделе подключить компоненту, используя следующий код:

$APPLICATION->IncludeComponent(
	"rnds",
	".default", 
	Array(/*параметры компоненты см. в приложении А*/),
	False
);

Если подключение компоненты прошло успешно, то должна появиться кнопка “Войти”.

Шаг 7. Добавить раздел для передачи логаут запроса (выход) в ЕСИА. В данном разделе подключить компоненту, используя следующий код:

$APPLICATION->IncludeComponent(
	"rnds",
	".default", 
	Array(/*параметры компоненты см. в приложении А*/),
	False
);

В случае, если необходимости выполнения логаута из отдельного раздела (отличного от раздела, из которого была выполнена авторизация) нет, то такой раздел создавать не нужно.

Если планируется, что возврат после выполнения процедуры логаута на стороне ЕСИА, будет происходить в строго заданный раздел, то необходимо, чтобы URL этого раздела соответствовал значению поля “URL системы”, указанному в личном кабинете или был его подстрокой. В случае когда URL возврата после авторизации и после логаута разные необходимо оба добавить на технологическом портале.

5 Зависимости

Модуль авторизации предъявляет следующие требования к среде исполнения требования к версии CMS Bitrix

Bitrix 14.5 или выше

языковые требования

PHP 5.5 или выше

В окружении модуля авторизации должна присутствовать утилита

OpenSSL v.1.1.x

которую можно вызвать посредством системного вызова.

OpenSSL должна поддерживать алгоритмы ГОСТ2012. Для этого необходимо установить расширение

Gost-engine

Необходимо наличие

Grep

В случае использования сервиса подписания запросов Signer (Jigner) его необходимо развернуть и настроить к нему доступ со стороны системы, в которую интегрируется библиотека.

Для работы модуля авторизации необходимо:

• наличие активной компоненты openssl;
  

• наличие активной компоненты json;
  

• наличие активной компоненты curl;
  

• наличие активной компоненты posix;
  

Модуль авторизации принимает на вход набор параметров, описанных в таблице А.1.

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

Для тестовой среды ЕСИА:

$APPLICATION->IncludeComponent(
"rnds:rnds.esia.oauth",
".default",
Array(
   'OAuth2UserGroupsId'	=> array(7),
   'OAuth2LogoutUri'    	=> "http://besia.d.rnds.pro/OAUTH2/ACS/",
   'OAuth2AuthUri'           => "http://besia.d.rnds.pro/OAUTH2/SLO/",
   'OAuth2RefreshTokenUri'   => "http://besia.d.rnds.pro/OAUTH2/ACS?refresh_token=true",
   'OAuth2UnTrustedUserRedirectURI' => 'http://besia.d.rnds.pro/OAUTH2/UNAUTH/',
   'OAuth2ClientId'     	=> "RNDS",
   'OAuth2Scope'        	=> "openid fullname id_doc",
   'OAuth2IsDebug'      	=> TRUE,
   'OAuth2UseCurl'	       => TRUE,
   'OAuth2CreateSessionUser' => 'N',
   'OAuth2UpdateAuthUser'    => 'Y',
   'OAuth2ShowInterface'	=> 'Y',
   'OAuth2OnlyVerifyedData'  => 'Y'
),
false);

Для промышленной среды ЕСИА:

$APPLICATION->IncludeComponent(
"rnds:rnds.esia.oauth",
".default",
Array(
   'OAuth2UserGroupsId'	=> array(7),
   'OAuth2IsTestEnvironment' => FALSE,
   'OAuth2LogoutUri'    	=> "http://besia.d.rnds.pro/OAUTH2/ACS/",
   'OAuth2AuthUri'           => "http://besia.d.rnds.pro/OAUTH2/SLO/",
   'OAuth2RefreshTokenUri'   => "http://besia.d.rnds.pro/OAUTH2/ACS?refresh_token=true",
   'OAuth2UnTrustedUserRedirectURI' => 'http://besia.d.rnds.pro/OAUTH2/UNAUTH/',
   'OAuth2ClientId'     	=> "RNDS",
   'OAuth2Scope'        	=> "openid fullname id_doc",
   'OAuth2IsDebug'      	=> TRUE,
   'OAuth2UseCurl'	       => TRUE,
   'OAuth2CreateSessionUser' => 'N',
   'OAuth2UpdateAuthUser'    => 'Y',
   'OAuth2ShowInterface'	=> 'Y',
   'OAuth2OnlyVerifyedData'  => 'Y'
),
false);