При выполнении очередного госзаказа наша команда столкнулась с проблемой интеграции сайта с ЕСИА. Инструкции по решению этой задачи в сети нет, кроме информации в официальных документах МинКомСвязи (примерно 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 для подключения к тестовой среде ЕСИА

Для интеграции необходимы сертификат (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 с таблицей с полученными данными от ЕСИА.

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

//в аттрибуте 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. При обновлении регламента возможны некоторые изменения во взаимодействии ИС с ЕСИА.