© 2014 - 2024 esia.pro

Библиотека авторизации через ЕСИА (PHP)

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

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

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

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

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

• RndsEsiaOAuth2.php - файл, который необходимо подключить в своем проекте для использования классов библиотеки;
• Keys - директория, в которой должны размещаться ключ и сертификат ИС (генерируются на стороне клиента ЕСИА);
• Temp - директория, в которую записываются временные файлы;
• Log - директория лог-файлов;
• OAuth2 - директория, в которой содержатся файлы библиотеки, распределенные по следующим директориям:
  • Init - директория, содержащая модули классов, выполняющих автозагрузку классов библиотеки авторизации;
  • Creators - директория, содержащая модули классов, выполняющих формирование объектов данных, запрашиваемых из защищенного хранилища ЕСИА;
  • Services - директория, содержащая модули классов, реализующих сервисы взаимодействия с ЕСИА;
  • Utils - директория, содержащая модули утилитарных классов, реализующих вспомогательные функции для сервисов.

3 Основные функции

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

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

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

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

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

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

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

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

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

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

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

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

Шаг 5. Добавить раздел (для MVC необходимо добавить метод в контроллер) для передачи запроса авторизации в ЕСИА. Разместить в данном разделе обработчик (для MVC метод контроллера) для формирования и передачи ЕСИА запроса на авторизацию. Обработчик должен содержать следующий код:

// регистрирует все классы библиотеки
require_once '[путь к рабочей директории]/RndsEsiaOAuth2.php'; 

// подключаем необходимые для авторизации классы
use OAuth2\Utils\OAuth2Configuration;
use OAuth2\Services\OAuth2RequestLogin;

// код формирующий объект конфигурации библиотеки
$arrayConf = array (
   'OAuth2Site'      => "https://esia-portal1.test.gosuslugi.ru",
   'OAuth2LogoutUri' => "http://besia.d.rnds.pro/auth_module/Testing/testLogin.php",
   'OAuth2AuthUri'   => "http://besia.d.rnds.pro/auth_module/Testing/testLogin.php",
   'OAuth2RefreshTokenUri'   => "http://besia.d.rnds.pro/auth_module/Testing/testLogin.php?refresh=true",
   'OAuth2ClientId'  => "RSKL02611",
   'OAuth2Scope'     => "openid fullname id_doc",
   'OAuth2IsDebug'   => TRUE
); //массив с основными параметрами библиотеки (подробнее в приложении А)

$objConf = new OAuth2Configuration($arrayConf);

// код формирующий запрос на авторизацию и выполняющий его передачу ЕСИА
$objLogin = new OAuth2RequestLogin($objConf);
$state_code = $objLogin->getStateCode();
$_SESSION['ESIA_STATE_CODE'] = $state_code; // ВАЖНО! Код идентификации запроса сохраняется 
                                            // в пользовательской сессии 
$objLogin->SendRequestLogin();

Шаг 6. Добавить раздел (для MVC необходимо добавить метод в контроллер) для перехода, после авторизации на стороне ЕСИА (это может быть тот же раздел, что и для передачи запроса на авторизацию). Разместить в данном разделе код обработчика ответа от ЕСИА получаемого в результате авторизации:

require_once '[путь к рабочей директории]/RndsEsiaOAuth2.php'; // регистрирует все классы

// подключаем классы, необходимые для получения данных
use OAuth2\Services\OAuth2RequestInfo;
use OAuth2\Services\OAuth2RequestToken;
use OAuth2\Services\OAuth2SecurityPolicies;
use OAuth2\Utils\OAuth2Configuration;
use OAuth2\Utils\Exceptions\OAuth2AuthPolicyException;
use OAuth2\Utils\Exceptions\OAuth2RequestInfoException;
use OAuth2\Utils\Exceptions\OAuth2TokenRequestException;
use OAuth2\Utils\Exceptions\OAuth2SetParameterException;

// код формирующий объект конфигурации библиотеки
$arrayConf = array (
   'OAuth2Site'       => "https://esia-portal1.test.gosuslugi.ru",
   'OAuth2LogoutUri' => "http://besia.d.rnds.pro/auth_module/Testing/testLogin.php",
   'OAuth2AuthUri'   => "http://besia.d.rnds.pro/auth_module/Testing/testLogin.php",
   'OAuth2RefreshTokenUri'   => "http://besia.d.rnds.pro/auth_module/Testing/testLogin.php?refresh=true",
   'OAuth2ClientId'  => "RSKL02611",
   'OAuth2Scope'     => "openid fullname id_doc",
   'OAuth2IsDebug'   => TRUE
); //массив с основными параметрами библиотеки (подробнее в приложении А)

$objConf = new OAuth2Configuration($arrayConf);

// код обработки ответа ЕСИА после авторизации
if ( isset($_GET['code']) && isset($_GET['state']) ) {
   // ВАЖНО! Полученный код идентификации запроса должен совпадать с 
   // ранее сохраненным в сессии значением 
   if ($_GET['code'] != '' && $_SESSION['ESIA_STATE_CODE'] == $_GET['state']) {

      try {

         $objToken = new OAuth2RequestToken( $objConf, $_GET['code']);         
         $objARE = $objToken->SendRequestToken();
         $objConf->setObjARE($objARE);

         $objInfo = new OAuth2RequestInfo($objConf);
         $objGeneralnfo = $objInfo->getPersonGeneralInfo(); // получение основной 
                                                            // информации о пользователе
         $objSecurityPolicies = new OAuth2SecurityPolicies($objConf);
         $objSecurityPolicies->SecurityPoliciesProcessing($objGeneralnfo);
      }
      catch (OAuth2TokenRequestException $objEx) {

         echo $objEx;
      }
      catch (OAuth2SetParameterException $objEx) {

         echo $objEx;
      }
      catch (OAuth2AuthPolicyException $objEx) {
          echo 'User can not be auth!'  . '<br>'; // or redirect to specific URL
      }
   }
   else {

      echo 'Authorization code or state not valid!'  . '<br>';
   }
}
else {

   echo 'Authorization code or state not defined in $_GET!'  . '<br>';
}

//далее Ваш код обработки данных, полученных от ЕСИА

Шаг 7. Добавить раздел для логаута на стороне ЕСИА. Разместить в данном разделе код для запроса логаута:

// регистрирует все классы библиотеки
require_once '[путь к рабочей директории]/RndsEsiaOAuth2.php'; 

// подключаем необходимые для логаута классы
use OAuth2\Utils\OAuth2Configuration;
use OAuth2\Services\OAuth2RequestLogout;

// код формирующий объект конфигурации библиотеки
$arrayConf = array (
   'OAuth2Site'      => "https://esia-portal1.test.gosuslugi.ru",
   'OAuth2LogoutUri' => "http://besia.d.rnds.pro/auth_module/Testing/testLogin.php",
   'OAuth2AuthUri'   => "http://besia.d.rnds.pro/auth_module/Testing/testLogin.php",
   'OAuth2RefreshTokenUri'   => "http://besia.d.rnds.pro/auth_module/Testing/testLogin.php?refresh=true",
   'OAuth2ClientId'  => "RSKL02611",
   'OAuth2Scope'     => "openid fullname id_doc",
   'OAuth2IsDebug'   => TRUE
); //массив с основными параметрами библиотеки (подробнее в приложении А)

$objConf = new OAuth2Configuration($arrayConf);

// код формирующий запрос на авторизацию и выполняющий его передачу ЕСИА
$objLogout = new OAuth2RequestLogout($objConf);
$objLogout->SendRequestLogout();

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

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

Библиотека авторизации предъявляет следующие языковые требования

PHP 5.5 или выше

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

OpenSSL v.1.1.x

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

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

Gost-engine

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

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

Grep

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

• наличие активной компоненты openssl (только при использовании алгоритма подписания запросов RSA);
  

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

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

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

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

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

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

$arrayConf = array(
                  'OAuth2LogoutUri'            => "http://yoursite.ru/logout_call_back",
                  'OAuth2AuthUri'              => "http://yoursite.ru/auth_call_back",
		              'OAuth2RefreshTokenUri'      => "http://yoursite.ru/refresh_token",
                  'OAuth2ClientId'             => "YOURID123"
                  );

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

$arrayConf = array(
		              'OAuth2IsTestEnvironment'    => false,
                  'OAuth2LogoutUri'            => "http://yoursite.ru/logout_call_back",
                  'OAuth2AuthUri'              => "http://yoursite.ru/auth_call_back",
		              'OAuth2RefreshTokenUri'      => "http://yoursite.ru/refresh_token",
                  'OAuth2ClientId'             => "YOURID123"
                  );

ПРИЛОЖЕНИЕ Б.
Перечень запрашиваемых областей доступа

Таблица Б.1 - Перечень запрашиваемых областей доступа