Интеграция с ЕСИА для проще, чем кажется

Время на прочтение

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

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

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

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

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

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

Введение

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

• Регистрация ИС в регистре информационных систем ЕСИА
• Регистрация ИС в тестовой среде
• Выполнение доработки системы для взаимодействия с ЕСИА

В данной статье будет описан только 3 пункт, предыдущие 2 – бюрократия, оставим ее за рамками Хабра. В методичке предлагают реализовать интеграцию 2 способами: SAML или OpenID Connect. Говорят,

с 01.01.2018 г. взаимодействие по протоколу SAML 2.0 больше не будет разрешено (только для действующих систем). Для подключения к ЕСИА необходимо будет использовать протокол OAuth 2.0 / OpenID Connect (сейчас доступны оба варианта).

Поэтому мы выбрали красную таблетку второй вариант. Согласно методичке, базовый сценарий аутентификации представляет собой примерно следующие шаги:

• Система-клиент отправляет в ЕСИА запрос на аутентификацию
• После успешной аутентификации ЕСИА возвращает ответ системе с кодом аутентификации.
• Используя код аутентификации система получает доступ к данным пользователя

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

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

Минкомсвязь России в рамках инфраструктуры электронного правительства создала и развивает Единую систему идентификации и аутентификации (ФГИС ЕСИА), цель которой — упорядочить и централизовать процессы регистрации, идентификации, аутентификации и авторизации пользователей.

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

Достоверность достигается за счет того, что:

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

2. Является ориентированной на пользователя и предоставляет возможности:

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

Основные функциональные возможности ЕСИА:

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

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

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

Люди, не знакомые с ситуацией, при слове «государственная» сразу представляют себе каналы связи, которые необходимо защитить при помощи отечественных криптоалгоритмов со всеми вытекающими затратами, лицензиями и оборудованием. Но, как бы смешно это не было (или печально), главная площадка для идентификации в стране – работает с иностранной криптографией (а куда деваться).

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

Что же может получить коммерческая организация из ЕСИА?

Перечень доступных к получению сведений зависит от:

• Категории организации, подключающейся к ЕСИА
• Использованного способа подключения к ЕСИА

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

Государственные организации могут получать из ЕСИА полный набор данных о пользователе и его организациях. Это следующие сведения:

• личные данные (ФИО, пол, дата и место рождения, гражданство)
• данные идентификационных документов (СНИЛС, ИНН, общегражданский и заграничный паспорт, свидетельство о рождении, водительское удостоверение, военный билет, полис ОМС)
• контактная информация (email, мобильный и домашний телефон, адреса регистрации и проживания)
• сведения о детях (личные данные и документы)
• сведения о транспортных средствах (номер и свидетельство о регистрации)
• сведения об организациях и ИП (наименование, ОГРН, ИНН/КПП, организационно-правовая форма, юридический адрес, контакты, филиалы, списки сотрудников, полномочия сотрудников, транспортные средства организации)
• данные учетной записи (идентификатор аккаунта в ЕСИА, признак «подтвержденности» аккаунта)

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

Как подключиться?

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

В общих чертах для подключения к ЕСИА нужно:

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

  Назначенному ответственному сотруднику организации нужно с помощью веб-приложения «Технологический портал ЕСИА»:

• Зарегистрировать учетную запись системы в ЕСИА. Мнемонику для системы придумать, либо использовать существующую мнемонику точки подключения к СМЭВ, если подключаемая к ЕСИА система раньше уже была подключена к СМЭВ.
• Загрузить в карточку системы ее сертификат.

  Ответственному сотруднику организации нужно:

• Поочередно подать по электронной почте заполненные в соответствии с регламентом заявки на использование программных интерфейсов ЕСИА в тестовой и промышленной среде.

  Разработчикам подключаемой системы:

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

Здесь нужно заметить, что с 01.01.2018 г. взаимодействие по протоколу SAML 2.0 больше не будет разрешено (только для действующих систем). Для подключения к ЕСИА необходимо будет использовать протокол OAuth 2.0 / OpenID Connect (сейчас доступны оба варианта).

Аутентификация пользователя в системе

Рекомендуемый сценарий аутентификации пользователя при интеграции по OpenID Connect 1.0 в его базовом виде происходит по следующему сценарию:

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

Подключаться или нет?

За операторов, в связи со вступлением в действие закона о мессенджерах данный вопрос практически решен.

Напомним, в соответствии с Федеральным законом №245 «О внесении изменений в Федеральный закон «О связи» от 29 июля 2017 года, операторы связи обязаны проверять достоверность сведений об абоненте. В законе закреплен перечень способов проверки, одним из которых является использование Единого портала государственных и муниципальных услуг или информационных систем госорганов при наличии подключения к ним у операторов через СМЭВ.

Поправки в ФЗ «О связи» вступают в силу 1 июня 2018. До этого времени операторы связи смогут протестировать работу своих систем со СМЭВ и ЕСИА.

Становится ли чебурнет всё ближе? Официальных заявлений о планах сделать выход в Интернет возможным только через ЕСИА нами не найдено. На данный момент, по официальным данным, в ЕСИА зарегистрировано около 50 миллионов пользователей (физических лиц) и около 300 000 организаций.

Базовая информация

Мы реализовали сервис интеграции с ЕСИА под Windows, используя КриптоПро CSP. В теории скорее всего можно это все аккуратно упаковать в docker и положить в Linux-образные системы, оставим это на откуп читателю. Для нас же актуальным стеком был следующий:

• КриптоПро CSP, КриптоПро .Net
• Сертификат с закрытым ключом, полученный при регистрации ИС в реестре ИС ЕСИА (на пункте 1 из Введения)

Каждый запрос в ЕСИА по соображениям безопасности дополняется полем client_secret, которое формируется как открепленная подпись 4 полей запроса в формате UTF-8:

• Scope (Скоуп запроса, перечень данных, которые нужно получить из ЕСИА). Например, «fullname gender email mobile usr_org»
• Timestamp (Текущие дата и время в формате «yyyy.MM.dd HH:mm:ss +0000»)
• ClientId (Идентификатор ИС, который выдается при регистрации системы в ЕСИА)
• State (Идентификатор текущего запроса, каждый раз генерируется как Guid.NewGuid().ToString(«D»))

Тут SignatureProvider – класс для реализации работы с сертификатами, он довольно просто реализуется. Для подписи использовался алгоритм ГОСТ – импортозамещение и все такое.

Часто задаваемые вопросы (FAQ) по ЕСИА

• Необходимы ли административные привилегии для установки плагина?Административные привилегии при установке плагина не требуются, если плагин устанавливается для использования текущим пользователем. Если же в процессе установки плагина выбрана опция установки плагина для всех пользователей компьютера, то для продолжения установки будет необходимо ввести пароль администратора.
• Необходимо ли перезапускать браузер после установки плагина?Нет, при установке плагина не требуется перезапускать браузер и операционную систему. Если плагин корректно встроен на ваш веб-сайт, то веб-страница может проверить, установлен ли плагин, а также подсказать пользователю о необходимых действиях, связанных с его установкой.
• Мы хотели бы использовать ваш плагин на своем сайте. Можем ли мы предоставлять пользователям плагин для загрузки с нашего сайта? Возможно ли для нашей версии изменить название и логотип плагина?Да, если вы купили лицензию, вы можете использовать и распространять плагин с вашего веб-сайта. Вы также можете заказать выпуск специальной версии плагина, брендированной для вашей компании или вашего сайта. Свяжитесь с нами для получения дополнительной информации.
• Можно ли с вашим плагином использовать электронную подпись на смартфонах и планшетах?К сожалению, наш плагин работает только на компьютерах под управлением операционных систем Windows, macOS и Linux (Linux Ubuntu 14/16, Linux Fedora 23, Linux Mint 17/18, CentOS и др.). Операционные системы мобильных устройств, такие как IOS и Android, не поддерживаются.
• Ваш плагин не поддерживает мой тип ключей. Можно ли добавить мой токен в число поддерживаемых?Пожалуйста, обратитесь к нами с использованием формы обратной связи. Сообщите нам имя токена и его производителя. Мы сообщим, сможем ли поддержать запрошенный тип ключей.
• Будет ли плагин работать со старыми версиями браузера Firefox, в том числе действующим ESR-релизом?Да, Blitz Smart Card Plugin совместим как со старыми версиями Firefox, использующими NPAPI, так и новыми версиями Firefox (версия 52 и новее), работающими через Native Messaging API. Поставляющийся с плагином JavaScript проверяет версию Firefox, установленного у пользователя, и использует актуальный способ взаимодействия с плагином.
• Какие требования предъявляются к веб-сайту, чтобы он мог использовать функции подписания документов?Blitz Smart Card Plugin — это клиентское программное обеспечение. Это означает, что браузер сможет вызывать функции работы с электронной подписью только после установки на машину пользователя специального плагина. Вместе с плагином предоставляется JavaScript, который должен быть встроен на сайт для возможностей использования функций электронной подписи.

Единая система идентификации и аутентификации

• Нужно ли приобретать отдельные лицензии для тестовых сред?Не нужно. В зависимости от приобретенного пакета лицензий вам доступна возможность использовать Blitz Identity Provider не только на доменах ПРОД‑среды, но и на определенном количестве ТЕСТ‑сред.
• Ограничивается ли срок действия приобретенных лицензий?Приобретаемые лицензии бессрочны — приобретаются один раз и на все время. Также при желании можно отдельно приобрести услуги годовой технической поддержки программного обеспечения.
• Можно ли добавить в продукт необходимую нам функцию?Да, мы развиваем Blitz Identity Provider, ориентируясь прежде всего на пожелания наших клиентов и пользователей. Напишите нам, какая функция вам необходима. Возможно что решение вашей задачи уже предусмотрено иным способом, и мы подскажем, как это можно настроить и использовать, либо мы включим нужную вам функцию в план разработки.
• Сколько лицензий необходимо в случае подключения сайта и мобильного приложения?Если сайт и мобильное приложение архитектурно представляют собой одну систему, то они могут использовать общие параметры подключения и регистрироваться в Blitz Identity Provider как одно приложение (использовать общую лицензию). Если же сайт и мобильное приложение представляют собой архитектурно две разные системы, то они должны регистрироваться в Blitz Identity Provider как два разных приложения, каждое со своими настройками подключения, и использовать в этом случае две лицензии.

Получение данных организации

Полученный токен доступа для запроса данных по организации мы использовать не можем, т.к. он завязан на определенный scope. Поэтому нужно получить отдельный токен. По сути методы получения токена доступа для организации и информации по ней не сильно отличаются от рассмотренных ранее. Для получения токена доступа мы используем идентификатор организации, код аутентификации, State предыдущего запроса на токен доступа. Новый scope формируется как список scope’ов организации, разделенных через пробел, например:

Метод получения информации по организации использует новый токен доступа и ссылку на организацию, полученную ранее вместе с данными о пользователе.

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

Предисловие

Получение данных пользователя из ЕСИА

Имея токен доступа и идентификатор пользователя можно получить данные о пользователе из ЕСИА. Рассмотрим пример получения ФИО пользователя и его организации. Для этого формируем GET запрос в REST API ЕСИА, для тестового контура базовый url (EsiaRestUrl) будет таким: https://esia-portal1.test.gosuslugi.ru/rs. Токен доступа передается в заголовке запроса, сам код выглядит следующим образом:

Этот метод принимает на вход идентификатор пользователя в ЕСИА и токен доступа – оба эти параметра мы получили на предыдущем этапе. Заметьте, запрос можно расширить и наряду с ФИО пользователя получить список его организаций. В этом случае мы получим список ссылок на организации пользователя, по которым можно будет получить данные в свою очередь. Таким образом, у нас получилась такая модель пользователя ЕСИА:

Перенаправление в ЕСИА и аутентификация

Начнем пошаговую реализацию с пунктов 1-4: нам нужно перенаправить пользователя на сервис аутентификации ЕСИА (EsiaAuthUrl). В зависимости от среды (тестовая или продуктив) различается базовый адрес url – для тестовой среды это https://esia-portal1.test.gosuslugi.ru/aas/oauth2/ac. Полный адрес получается таким:

где RedirectUri – адрес, на который будет направлен ответ от ЕСИА, а ClientSecret – результат выполнения функции GetClientSecret. Остальные параметры описаны ранее.

Получение токена доступа

Для получение каких-либо данных в ЕСИА нам нужно получить токен доступа. Для этого формируем POST запрос в ЕСИА (для тестовой среды базовый url такой: https://esia-portal1.test.gosuslugi.ru/aas/oauth2/te — EsiaTokenUrl). Основные поля запроса тут формируются аналогичным образом, в коде получается примерно следующее:

Некоторые статичные параметры запроса получаем из файла конфигурации (поле Configuration). Как мы можем видеть, поле code запроса заполняется значением кода аутентификации, полученным ранее. Для десериализации ответа используется следующие классы:

Заключение

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