Интеграция с ЕСИА

При выполнении очередного госзаказа наша команда столкнулась с проблемой интеграции сайта с ЕСИА. Инструкции по решению этой задачи в сети нет, кроме информации в официальных документах МинКомСвязи (примерно 300 страниц в трех регламентах). Также есть компании, которые оказывают платные услуги по интеграции ЕСИА. Мы реализовали, описали процесс интеграции и решили поделиться с сообществом habrahabr.


Что такое ЕСИА


Единая Система Идентификации и Аутентификации — российская информациия система, обеспечивающая доступ (регистрация, аутентификация) на сайты государтсвенных структур и некоторых коммерческих организаций. Подробнее на википедии


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


Сценарий авторизации выглядит примерно так:


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

Содержание


  1. Общие сведения
  2. Установка SimpleSAMLphp
  3. Настройка SimpleSAMLphp для подключения к тестовой среде ЕСИА
  4. Конфигурация файла метаданных
  5. Отправка заявки в адрес МинКомСвзяи на подключение ИС к тестовой среде ЕСИА
  6. Функциональная интеграция с ЕСИА и получение данных авторизированных пользователей через ЕСИА
  7. Отправка заявки на подключение ИС к продуктивной среде ЕСИА

Общие сведения


На сайте МинКомСвязи размещен документ, именуемый «Методические рекомендации по использованию Единой системы идентификации и аутентификации», последнюю актуальную версию всегда можно найти на сайте МинКомСвязи. Документ сам по себе немаленький — почти 200 страниц, и, конечно же мало кто захочет его подробно изучать, да и понятен он будет не всем желающим, поэтому опишу тут процесс в сухом остатке.


Подключить ИС к ЕСИА возможно двумя способами:


  • Посредством стандарта SAML 2.0
  • На базе подхода REST

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


Но для подавляющего большинста случаев первый подход охватывает все необходимые функции. Поэтому расскажу о внедрении ЕСИА посредством SAML 2.0


Установка SimpleSAMLphp


Для интеграции будем использовать SimpleSAMLphp. Если система, которую вы ��астраиваете написана не на PHP, то все равно можно использовать этот модуль, просто на вашем сайте будет функция аутентификации реализована на php, данные от ЕСИА вы получите в xml формате.


Последняя официальная версия SimplSAMLphp доступна на официальном сайте SimpleSamlPHP. Скачиваете архив, распаковываете модуль в папку /var.В целях безопасности для папки с разархивированным модулем необходимо настроить права доступа только для root пользователя. В конфигурации сервера необходимо добавить алиас и следующие правила:


<VirtualHost *>
ServerName service.example.com
    DocumentRoot /var/www/service.example.com
    SetEnv SIMPLESAMLPHP_CONFIG_DIR /var/simplesamlphp/config
    Alias /simplesaml /var/simplesamlphp/www
    <Directory /var/simplesamlphp/www>
        <IfModule !mod_authz_core.c>
        # For Apache 2.2:
        Order allow,deny
        Allow from all
        </IfModule>
        <IfModule mod_authz_core.c>
        # For Apache 2.4:
        Require all granted
        </IfModule>
    </Directory>
</VirtualHost>

Суть в том, чтобы по запросу ServerName/simplesaml открывалась приветственная страница simplesaml. Если вы все сделали правильно, то по запросу ServerName/simplesaml вы увидите такую страничку



SimpleSamlPHP

Настройка SimpleSAMLphp для подключения к тестовой среде ЕСИА


Для интеграции необходимы сертификат (cert.crt) и ключ (key.key). Важно(!) с ГОСТовским сертфикатом ничего не выйдет, можно получить бесплатный сертификат, погуглив как это делается, либо выпустить сертификат самому. Ключ и сертификат кладем в папку simplesamlphp/cert


Для конфигурации SimpleSAMLphp необходимо отредактировать следующие файлы:


  • simplesamlphp/config/config.php
  • simplesamlphp/config/authsources.php
  • simplesamlphp/metadata/saml20-idp-remote.php

Важное замечание — время на сервере не должно отличаться от времени ЕСИА больше 1 минуты.


simplesamlphp/config/config.php:


//путь к папке с сертификатом и ключом относительно директории simplesamlphp
'certdir' => 'cert/'

// соль
'secretsalt' => 'defaultsecretsalt',
//Контакты администратора
'technicalcontact_name' => 'Familiya Imya',
'technicalcontact_email' => 'po4ta@domen.zone',

Важно знать, есть ли у системы entityID, если его нет, то в поле 'entityID' необходимо указать адрес системы


simplesamlphp/config/authsources.php:



esia' => array (
	'saml:SP',
	'name' => 'Esia',
//файл закрытого ключа
	'privatekey' => 'key.key',
//пароль ключа
	'privatekey_pass' => '12345678',
//сертификат открытого ключа
	'certificate' => 'cert.crt',
//идентификатор системы,
	'entityID' => 'ServerName',
	'discoURL' => NULL,
	'redirect.sign' => TRUE,
	'redirect.validate' => TRUE,
	'validate.logout' => FALSE,
//idp поставщика услуг для тестовой среды
	'idp' => 'https://esia-portal1.test.gosuslugi.ru/idp/shibboleth',
//idp поставщика услуг для продуктивной среды
//	'idp' => 'https://esia.gosuslugi.ru/idp/shibboleth',
//Наименование организации
	'OrganizationName' => 'Organization Name',
//url организации
	'OrganizationURL' => 'ServerName',

Теперь надо получить подпись для нашего сертификата (fingerprint). Это можно сделать в терминале одной из команд


  • openssl x509 -noout -fingerprint -in "cert.crt" SHA1
  • sha1sum cert.crt

simplesamlphp/metadata/saml20-idp-remote.php:



// idp поставщика услуг для тестовой среды
$metadata['https://esia-portal1.test.gosuslugi.ru/idp/shibboleth'] = array(
	'name' => array(
		'en' => 'Esia',
		'no' => 'ESIA',
	),
//idp SignOn поставщика услуг
	'SingleSignOnService' => 'https://esia-portal1.test.gosuslugi.ru/idp/profile/SAML2/Redirect/SSO',
//idp LogOut поставщика услуг
	'SingleLogoutService' => 'https://esia-portal1.test.gosuslugi.ru/idp/profile/SAML2/Redirect/SLO',
//Fingerprint сертификата
	'certFingerprint' => 'f17393ae5927293ae5927261b6515c44501e4450',
);

Конфигурация файла метаданных


Теперь необходимо сгонфигурировать файл метаданных для того, чтобы его отправить вместе с заявкой в ЕСИА


Файл метаданных доступен по ссылке: ServerName/simplesaml/module.php/saml/sp/metadata.php/esia?output=xhtml


Пример файла метаданных:


<?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="ServerName">
  <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.1:protocol urn:oasis:names:tc:SAML:2.0:protocol" AuthnRequestsSigned="true">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>
		//Сертификат
	  </ ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:KeyDescriptor use="encryption">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>
		//Сертификат
	  </ ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="ServerName/simplesaml/module.php/saml/sp/saml2-logout.php/esia"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="ServerName/simplesaml/module.php/saml/sp/saml2-acs.php/esia" index="0"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post" Location="ServerName/simplesaml/module.php/saml/sp/saml1-acs.php/esia" index="1"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="ServerName/simplesaml/module.php/saml/sp/saml2-acs.php/esia" index="2"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01" Location="ServerName/simplesaml/module.php/saml/sp/saml1-acs.php/esia/artifact" index="3"/>
  </md:SPSSODescriptor>
  <md:Organization>
    <md:OrganizationName xml:lang="en">Organization Name</md:OrganizationName>
    <md:OrganizationDisplayName xml:lang="en">Organization Name</md:OrganizationDisplayName>
    <md:OrganizationURL xml:lang="en">ServerName</md:OrganizationURL>
  </md:Organization>
  <md:ContactPerson contactType="technical">
    <md:GivenName>Imya</md:GivenName>
    <md:SurName>Familiya</md:SurName>
    <md:EmailAddress>po4ta@domen.zone</md:EmailAddress>
  </md:ContactPerson>
</md:E</ntityDescriptor>

Но, к сожалению, SimpleSaml формирует файл метаданных, который немного отличается от требования ЕСИА, поэтому необходимо его подкорретировать в соотвествии с рекомендациями пункт А.6 Шаблон файла метаданных


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


Отправка заявки в адрес МинКомСвзяи на подключение ИС к тестовой среде ЕСИА


Теперь формируем заявку по форме «E» Регламента информационного взаимодействия Участников с Оператором ЕСИА. Форму заявки в формате docx можете скачать с нашего сайта по ссылке.


Теперь необходимо отправить заявку на почту esia@minsvyaz.ru с темой «Интеграция тестовой ЕСИА» и к письму необходимо приложить три файла:


  • скан заявки в формате pdf,
  • сертификат в формате crt
  • файл метаданных xml

После получения ответа от поставщика услуг (ЕСИА) со статусом «Решен» и приложенными файлами для тестирования, переходим к следующему шагу.


Возможно Вам придет ответ с темой «Требуется дополнительная информация по запросу #», в этом случае в письме будет информация о том, что необходимо исправить.


Функциональная интеграция с ЕСИА и получение данных авторизированных пользователей через ЕСИА


Проверить подключения ИС к тестовой среде можно по ссылке
ServerName/simplesaml/module.php/core/authenticate.php?as=esia.


При корректном выполнении всех предыдущих пунктов по ссылке откроется страница с тестовой средой ЕСИА. Для аутентификации в тестовой среде используются данные, полученные от ЕСИА в письме со статусом «Решен». После аутентификации произойдет переход на страницу SimpleSAML с таблицей с полученными данными от ЕСИА.


xml ответ ЕСИА

Теперь напишем скрипт, который будет обрабатывать данные. Для начала добавим кнопку для авторизации на сайт.



//в аттрибуте action указываем путь к файлу с будущим обработчиком данных
<form action="inc/esia.php" method="POST">
	<input name="esia" type="submit" value="Войти через Госуслуги"/>
</form>

Обработчик inc/esia.php. Тут мы получаем данные и можем записать их в базу, добавить в сессию и т.д. Вообще надо правильно парсить xml. Сейчас просто выведем данные на экран. 



if (isset($_POST['esia'])){
//Настраиваем путь до simplesamlphp/lib/_autoload.php
	require_once('../../simplesamlphp/lib/_autoload.php');
	$as = new SimpleSAML_Auth_Simple('esia');
	$as->requireAuth();
	$attributes = $as->getAttributes();
	foreach($attributes as $key => $value) {
		echo ($key . ' ' . $value . '<br/>');
	}
}

Отправка заявки на подключение ИС к продуктивной среде ЕСИА


Теперь формируем заявку по форме «М» Регламента информационного взаимодействия Участников с Оператором ЕСИА. Она не сильно отличается от формы Е, но внимательно изучите форму, необходимо в форме добавить запрашиваемые данные и уже не надо прикреплять файл сертификата.


В файлах simplesamlphp/config/authsources.php, simplesamlphp/metadata/saml20-idp-remote.php необходимо заменить idp поставщика услуг с Тестовой среды на продуктивную:



//idp поставщика услуг для тестовой среды
//	'idp' => 'https://esia-portal1.test.gosuslugi.ru/idp/shibboleth',
//необходимо заменить на idp поставщика услуг для продуктивной среды
	'idp' => 'https://esia.gosuslugi.ru/idp/shibboleth',

Теперь формируем новый файл метаданных, по факту меняются только ссылки в полях Service


По адресу esia@minsvyaz.ru отправляем письмо и прикрепляем 2 файла:


  • Новый файл метаданных
  • Заявку по форме М

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


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