Esia “хабр и SAML” запрашивает генерацию подписи

Esia "хабр и SAML" запрашивает генерацию подписи pos gosuslugi

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

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

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

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

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

Сделать это оказалось не так просто. Нужно было выполнить ряд требований и процедур, решить технические трудности.

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

Надеемся, наш опыт поможет Java-разработчикам (и не только) сэкономить массу времени при разработке и ознакомлении с методическими рекомендациями Минкомсвязи.

Esia "хабр и SAML" запрашивает генерацию подписи

Введение

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

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

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

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

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

  1. Пользователь нажимает на веб-странице системы-клиента кнопку «Войти через ЕСИА»
  2. Система-клиент отправляет в ЕСИА запрос на аутентификацию
  3. ЕСИА осуществляет аутентификацию пользователя посредством логина-пароля
  4. После успешной аутентификации ЕСИА возвращает ответ системе с кодом аутентификации.
  5. Используя код аутентификации система получает доступ к данным пользователя

Возможно кому-то приходилось проводить интеграцию с данным сервисом ЕСИА. Вопрос возникает в формировании сигнатуры к запросу, т.к. используется протокол SSO SAML: после формирования запроса на аутентификацию требуется поместить в GET-запрос ряд параметров: SamlAuth, AlgSig, relayState и Signature.

  • Вопрос 1: Что такое relayState и как оно формируется?

задан 24 июл 2015 в 6:49

dzrock's user avatar

16 бронзовых знаков

Рекомендую копать в сторону spring-saml, у меня оно отлично привинтилось.
Приложу свой конфиг saml-security.xml

<?xml version="1.0" encoding="UTF-8" ?>
<beans xmlns="http://www.springframework.org/schema/beans"
   xmlns:security="http://www.springframework.org/schema/security"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.springframework.org/schema/security http://www.springframework.org/schema/security/spring-security.xsd
                       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.2.xsd">

<bean id="samlFilter" class="org.springframework.security.web.FilterChainProxy">
    <security:filter-chain-map request-matcher="ant">
        <security:filter-chain pattern="/user/saml/login/**" filters="samlEntryPoint"/>
        <security:filter-chain pattern="/user/saml/authnrequestresponselistener/**"
                               filters="samlWebSSOProcessingFilter"/>
    </security:filter-chain-map>
</bean>

<!-- Handler deciding where to redirect user after successful login -->
<bean id="successRedirectHandler"
      class="org.springframework.security.web.authentication.SavedRequestAwareAuthenticationSuccessHandler">
    <property name="defaultTargetUrl" value="/user/login/esia/"/>
</bean>

<!-- Register authentication manager with SAML provider -->
<!--<security:authentication-manager alias="samlAuthenticationManager">-->
    <!--<security:authentication-provider ref="samlAuthenticationProvider"/>-->
<!--</security:authentication-manager>-->

<bean id="samlAuthenticationManager" class="org.springframework.security.authentication.ProviderManager">
    <constructor-arg>
        <list>
            <!-- SAML Authentication Provider responsible for validating of received SAML messages -->
            <bean id="samlAuthenticationProvider" class="org.springframework.security.saml.SAMLAuthenticationProvider">
                <!-- OPTIONAL property: can be used to store/load user data after login -->
                <!--<property name="userDetails" ref="samlUserDetailsService" />-->
            </bean>
        </list>
    </constructor-arg>
</bean>

<!-- Logger for SAML messages and events -->
<bean id="samlLogger" class="org.springframework.security.saml.log.SAMLDefaultLogger">
    <property name="logMessages" value="true"/>
</bean>

<!-- Central storage of cryptographic keys -->
<bean id="keyManager" class="org.springframework.security.saml.key.JKSKeyManager">
    <constructor-arg value="classpath:esia/esia.jks"/>
    <constructor-arg type="java.lang.String" value="******"/>
    <constructor-arg>
        <map>
            <entry key="entryKey" value="******"/>
        </map>
    </constructor-arg>
    <constructor-arg type="java.lang.String" value="someValue"/>
</bean>

<!-- Entry point to initialize authentication, default values taken from properties file -->
<bean id="samlEntryPoint" class="org.springframework.security.saml.SAMLEntryPoint">
    <property name="defaultProfileOptions">
        <bean class="org.springframework.security.saml.websso.WebSSOProfileOptions">
            <property name="includeScoping" value="false"/>
            <property name="binding" value="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"/>
        </bean>
    </property>
</bean>

<!-- Filter automatically generates default SP metadata -->
<bean id="metadataGeneratorFilter" class="org.springframework.security.saml.metadata.MetadataGeneratorFilter">
    <constructor-arg>
        <bean class="org.springframework.security.saml.metadata.MetadataGenerator"/>
    </constructor-arg>
</bean>

<!-- IDP Metadata configuration - paths to metadata of IDPs in circle of trust is here -->
<!-- Do no forget to call iniitalize method on providers -->
<bean id="metadata" class="org.springframework.security.saml.metadata.CachingMetadataManager">
    <constructor-arg>
        <list>
            <bean class="org.springframework.security.saml.metadata.ExtendedMetadataDelegate">
                <constructor-arg>
                    <bean class="org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider">
                        <constructor-arg>
                            <value type="java.io.File">classpath:esia/esia_edu_metadata.xml</value>
                        </constructor-arg>
                        <property name="parserPool" ref="parserPool"/>
                    </bean>
                </constructor-arg>
                <constructor-arg>
                    <bean class="org.springframework.security.saml.metadata.ExtendedMetadata">
                    </bean>
                </constructor-arg>
            </bean>
            <bean class="org.springframework.security.saml.metadata.ExtendedMetadataDelegate">
                <constructor-arg>
                    <bean class="org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider">
                        <constructor-arg>
                            <value type="java.io.File">classpath:esia/esia_prod_metadata.xml</value>
                        </constructor-arg>
                        <property name="parserPool" ref="parserPool"/>
                    </bean>
                </constructor-arg>
                <constructor-arg>
                    <bean class="org.springframework.security.saml.metadata.ExtendedMetadata">
                    </bean>
                </constructor-arg>
            </bean>
            <bean class="org.springframework.security.saml.metadata.ExtendedMetadataDelegate">
                <constructor-arg>
                    <bean class="org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider">
                        <constructor-arg>
                            <value type="java.io.File">classpath:esia/shibboleth.xml</value>
                        </constructor-arg>
                        <property name="parserPool" ref="parserPool"/>
                    </bean>
                </constructor-arg>
                <constructor-arg>
                    <bean class="org.springframework.security.saml.metadata.ExtendedMetadata">
                    </bean>
                </constructor-arg>
            </bean>
        </list>
    </constructor-arg>
    <!-- Set provider edu or prod -->
    <property name="hostedSPName" value="hostname.ru"/>
</bean>

<!-- Provider of default SAML Context -->
<bean id="contextProvider" class="org.springframework.security.saml.context.SAMLContextProviderImpl"/>

<!-- Processing filter for WebSSO profile messages -->
<bean id="samlWebSSOProcessingFilter" class="org.springframework.security.saml.SAMLProcessingFilter">
    <constructor-arg>
        <value type="java.lang.String">/user/saml/authnrequestresponselistener</value>
    </constructor-arg>
    <property name="authenticationManager" ref="samlAuthenticationManager"/>
    <property name="authenticationSuccessHandler" ref="successRedirectHandler"/>
</bean>

<!-- Class loading incoming SAML messages from httpRequest stream -->
<bean id="processor" class="org.springframework.security.saml.processor.SAMLProcessorImpl">
    <constructor-arg>
        <list>
            <ref bean="redirectBinding"/>
            <ref bean="postBinding"/>
        </list>
    </constructor-arg>
</bean>

<!-- SAML 2.0 WebSSO Assertion Consumer -->
<bean id="webSSOprofileConsumer" class="org.springframework.security.saml.websso.WebSSOProfileConsumerImpl"/>

<!-- SAML 2.0 Holder-of-Key WebSSO Assertion Consumer -->
<bean id="hokWebSSOprofileConsumer" class="org.springframework.security.saml.websso.WebSSOProfileConsumerHoKImpl"/>

<!-- SAML 2.0 Web SSO profile -->
<bean id="webSSOprofile" class="org.springframework.security.saml.websso.WebSSOProfileImpl"/>

<!-- SAML 2.0 Holder-of-Key Web SSO profile -->
<bean id="hokWebSSOProfile" class="org.springframework.security.saml.websso.WebSSOProfileConsumerHoKImpl"/>

<!-- SAML 2.0 ECP profile -->
<bean id="ecpprofile" class="org.springframework.security.saml.websso.WebSSOProfileECPImpl"/>

<!-- Bindings, encoders and decoders used for creating and parsing messages -->
<bean id="redirectBinding" class="org.springframework.security.saml.processor.HTTPRedirectDeflateBinding">
    <constructor-arg ref="parserPool"/>
</bean>

<bean id="postBinding" class="org.springframework.security.saml.processor.HTTPPostBinding">
    <constructor-arg ref="parserPool"/>
    <constructor-arg ref="velocityEngine"/>
</bean>

<!-- Initialization of OpenSAML library-->
<bean class="org.springframework.security.saml.SAMLBootstrap"/>

<!-- Initialization of the velocity engine -->
<bean id="velocityEngine" class="org.springframework.security.saml.util.VelocityFactory"
      factory-method="getEngine"/>

<!-- XML parser pool needed for OpenSAML parsing -->
<bean id="parserPool" class="org.opensaml.xml.parse.StaticBasicParserPool" init-method="initialize"/>
<bean id="parserPoolHolder" class="org.springframework.security.saml.parser.ParserPoolHolder"/>

ответ дан 24 июл 2015 в 9:09

Namelles.One's user avatar

relayState – можно не указывать.
Signature в ЕСИА надо указать ‘-‘ примерно так на Ruby:

params[:SAMLRequest]= Base64.strict_encode64(Zlib::Deflate.deflate(signed_request, 9)[2..-5])
params[:Signature]  = '-'
params[:SigAlg]     = 'http://www.w3.org/2000/09/xmldsig#rsa-sha1'

Подписание дело тонкое: ищите как подписываются xml, куда вставляются блоки, ds:Signature, каноникализация и пр.

Можете посмотреть информацию здесь: http://esia.pro

ответ дан 27 июл 2015 в 10:56

Samoilenko Yuri's user avatar

Исходя из нашего опыта работы могу добавить:

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

  2. Порядок формировании подписи:

1) выполняется deflate строки запроса – получается byte

2) выполняется подпись полученного на шаге 1 – получается byte

3) выполняется кодирование в base64 полученного на шаге 2

В дополнение могу порекомендовать посмотреть не только готовое решение, упомянутое Samoilenko Yuri, но и ESIA-Bridge.

ответ дан 3 фев 2016 в 12:52

Kirill's user avatar

2 бронзовых знака

У нас подпись заработала как-то так:

public static byte[] Sign(X509Certificate2 certificate, byte[] data)
{
    if (data == null)
        throw new ArgumentNullException("data");
    if (certificate == null)
        throw new ArgumentNullException("certificate");

    // setup the data to sign
    ContentInfo content = new ContentInfo(data);
    SignedCms signedCms = new SignedCms(content, true);
    CmsSigner signer = new CmsSigner(certificate);
    var sha256 = new Oid("2.16.840.1.101.3.4.2.1", "sha256");
    signer.DigestAlgorithm = sha256;

    // create the signature
    signedCms.ComputeSignature(signer);
    var signature = signedCms.Encode();

    return signature;
}

С base64 там всё не очевидно: Convert.ToBase64String не подходит, не достаточно точно реализует стандарт.
Использовал вот такой метод:

public static string Base64UrlEncode(byte[] arg)
{
    string s = Convert.ToBase64String(arg); // Regular base64 encoder
    s = s.Split('=')[0]; // Remove any trailing '='s
    s = s.Replace('+', '-'); // 62nd char of encoding
    s = s.Replace('/', '_'); // 63rd char of encoding
    return s;
}

Проверка их подписи – это очередной ребус. Можно предположить, что это процесс обратный процессу подписания, т.е. как-то так:

public static bool ValidateCmsSignature(byte[] data, byte[] signature, X509Certificate2 certificate)
{
    bool result = false;

    if (data == null)
        throw new ArgumentNullException("data");
    if (signature == null)
        throw new ArgumentNullException("signature");
    if (certificate == null)
        throw new ArgumentNullException("certificate");

    // setup the data to sign
    ContentInfo content = new ContentInfo(data);
    SignedCms signedCms = new SignedCms(content, true);

    try
    {
        signedCms.Decode(signature);
        signedCms.CheckSignature(new X509Certificate2Collection(certificate), true);
        result = true;
    }
    catch (Exception ex)
    {
        var msg = ex.Message;
    }

    return result;
}

И этот метод работает для проверки нашей подписи, но не подходит для их подписи. А почему?

Читайте также:  Все про ЕСИА

Если мы сначала формируем текстовую строку, потом создаем отсоединенную подпись по ней, и потом всё это кодируем в base64, то они формируют два JSON’а: HEADER и PAYLOAD, потом кодируют их по отдельности в base64, и вот потом формируют подпись по строке HEADERbase64.PAYLOADbase64. А потом уже и подпись кодируют в base64.

Итого, метод для проверки их подписи выглядит как-то так:

public static bool ValidateSignature(byte[] data, byte[] signature, X509Certificate2 certificate)
{
    bool result = false;
    using (var csp = (RSACryptoServiceProvider) certificate.PublicKey.Key)
    {
        using (var hasher = new SHA256Managed())
        {
            var hash = hasher.ComputeHash(data);
            string id = CryptoConfig.MapNameToOID("SHA256");
            bool isDataok = csp.VerifyData(data, id, signature);
            bool isHashOk = csp.VerifyHash(hash, id, signature);

            //  можно ещё так
            //RSAPKCS1SignatureDeformatter rsaDeformatter = new RSAPKCS1SignatureDeformatter(csp);
            //rsaDeformatter.SetHashAlgorithm("SHA256");
            //bool isHashOk2 = rsaDeformatter.VerifySignature(hash, signature);

            result = isDataok && isHashOk;
        }
    }
    return result;
}

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

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

В целом система ЕСИА служит для:

  1. Создания физическими лицами, ИП или юридическими лицами единой учётной записи, которая даёт доступ к различным информационным системам, сайтам и порталам, использующим такой способ регистрации, авторизации и (или) идентификации пользователя.
  2. Взаимодействия различных информационных систем на уровне средств подтверждения личности пользователя (идентификации), проверки его данных (аутентификации) и предоставления разрешения на доступ (авторизации).
  3. Авторизации пользователей на государственных, региональных и муниципальных ресурсах для получения соответствующих услуг в электронном виде. Например, для запроса и получения информации, справок, оформления документов, совершения регистрационных действий, записи на приём в то или иное ведомство.
  4. Авторизации пользователей на негосударственных ресурсах (сайтах, порталах, системах), которые подключены к ЕСИА и используют учётные записи в этой системе (с согласия их владельцев) для разрешения доступа.

Что делать и как?

Сначала нам показалось, что в интеграции с ЕСИА нет ничего особенного с технической точки зрения — стандартная задача, связанная с получением данных посредством REST API. Однако, при ближайшем рассмотрении стало понятно, что не всё так просто. Например, выяснилось, что у нас нет представления о том, как работать с сертификатами, необходимыми для подписи нескольких параметров. Пришлось тратить время и разбираться. Но обо всем по порядку.

Для начала важно было наметить план действий. Наш план включал следующие основные шаги:

  1. зарегистрироваться на технологическом портале ЕСИА;
  2. подать заявки на использование программных интерфейсов ЕСИА в тестовой и промышленной среде;
  3. самостоятельно разработать механизм взаимодействия с ЕСИА (в соответствии с действующим документом «Методические рекомендации по использованию ЕСИА»);
  4. протестировать работу механизма в тестовой и промышленной среде ЕСИА.

Обычно мы разрабатываем наши проекты на Java. Поэтому для программной реализации выбрали:

  • IntelliJ IDEA;
  • КриптоПро JCP (или КриптоПро Java CSP);
  • Java 8;
  • Apache HttpClient;
  • Lombok;
  • FasterXML/Jackson.

Как организации подключиться к ЕСИА

Процедура подключения занимает около месяца. Это время включает регистрацию необходимых аккаунтов, получение данных от Минцифры, работы по интеграции ИС.

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

2. Зарегистрируйте вашу организацию.

a. Получите квалифицированную электронную подпись (КЭП) на руководителя организации.

b. Зарегистрируйте юридическое лицо в профиле ЕСИА.

c. Оформите КЭП для юридического лица.

Оформлением КЭП занимаются аккредитованные удостоверяющие центры. Подробная инструкция по этому процессу здесь.

3. Зарегистрируйте информационную систему в ЕСИА.

Регистрация системы происходит через технологический портал. Доступ к нему может получить один из сотрудников компании – действовать через аккаунт представителя уже не обязательно. Этот процесс подробно расписан в Руководстве пользователя технологического портала ЕСИА. В результате регистрации информационная система заносится в реестр ИС и получает мнемонический буквенно-цифровой код.

4. Доработайте систему для обмена данными с ЕСИА.

Аутентификация пользователей в ЕСИА происходит по OAuth 2.0 и OpenID Connect 1.0. Компании необходимо сгенерировать закрытый ключ и сертификат открытого ключа, зарегистрировать его на технологическом портале. Стоит отметить, что ЕСИА поддерживает только российские алгоритмы шифрования ГОСТ Р 34.10-2012 и ГОСТ Р 34.11-2012.

Стоит отдельно отметить, что если в компании уже используются средства верификации пользователей посредством Single Sign-On, то особых технических трудностей при подключении к ЕСИА не будет.

5. Подключитесь к тестовой среде ЕСИА

6. Подключитесь к промышленной среде ЕСИА

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

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

{EsiaAuthUrl}?client_id={ClientId}&scope={Scope}&response_type=code&state={State}& timestamp={Timestamp}&access_type=online&redirect_uri={RedirectUri}&client_secret={ClientSecret}

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

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

В нашем случае необходимо получить ФИО, дату рождения, паспортные данные и контакты.
Используем функциональный интерфейс, который поможет получать данные пользователя:

Function<String, String> esiaPersonDataFetcher = (fetchingUri) -> {
  try {
    URI getDataUri = new URIBuilder(fetchingUri).build();
    HttpGet dataHttpGet = new HttpGet(getDataUri);
       dataHttpGet.addHeader("Authorization", requestDto.getTokenType() + " " + tokenResponseDto.getAccessToken());
    try (CloseableHttpResponse dataResponse = httpClient.execute(dataHttpGet)) {
      HttpEntity dataEntity = dataResponse.getEntity();
      return EntityUtils.toString(dataEntity);
    }
  } catch (Exception e) {
    throw new UndeclaredThrowableException(e);
  }
};

Получение данных пользователя:

String personDataEntityString = esiaPersonDataFetcher.apply(ESIA_REST_API_URL + "/prns/" + esiaAccountId);

Получение контактов выглядит уже не таким очевидным, как получение данных пользователя. Для начала следует получить список ссылок на контакты:

String contactsListEntityString = esiaPersonDataFetcher.apply(ESIA_REST_API_URL + "/prns/" + esiaAccountId + "/ctts");
EsiaListDto esiaListDto = objectMapper.readValue(contactsListEntityString, EsiaListDto.class);

Десериализуем этот список и получим объект esiaListDto. Поля из методички ЕСИА могут различаться, поэтому стоит проверить опытным путем.

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

for (String contactUrl : esiaListDto.getElementUrls()) {
  String contactEntityString = esiaPersonDataFetcher.apply(contactUrl);
  EsiaContactDto esiaContactDto = objectMapper.readValue(contactEntityString, EsiaContactDto.class);
}

С получением списка документов та же ситуация. Вначале получаем список ссылок на документы:

String documentsListEntityString = esiaPersonDataFetcher.apply(ESIA_REST_API_URL + "/prns/" + esiaAccountId + "/docs");

Затем десериализуем его:

EsiaListDto esiaDocumentsListDto = objectMapper.readValue(documentsListEntityString, EsiaListDto.class);
Переходим по каждой ссылке и получаем документы:
for (String documentUrl : esiaDocumentsListDto.getElementUrls()) {
  String documentEntityString = esiaPersonDataFetcher.apply(documentUrl);
  EsiaDocumentDto esiaDocumentDto = objectMapper.readValue(documentEntityString, EsiaDocumentDto.class);
}

Предисловие

Esia "хабр и SAML" запрашивает генерацию подписи

Какие возможности открывает такая идентификация

1. Клиент может подписывать юридически значимые электронные документы, получать защищённый доступ к конфиденциальной информации, медицинским данным и т.д.

2. Появляется возможность автоматически заполнять в анкетах и заявках персональные данные клиента: ФИО, данные паспорта, ИНН, информация о детях и др. При этом компания может быть уверена, что эти данные абсолютно верны и правдивы.

3. Страховые компании и банки могут продавать через приложение свои продукты. И никаких расходов, которые связаны с традиционными, оффлайновыми каналами продаж – не нужно собирать документы, приглашать человека в офис, достаточно разработать скрипт для колл-центра.

4. Для пользователя верификация с ЕСИА повышает доверие к сервису и делает саму процедуру удобнее – не нужно помнить дополнительные пароли, просто нажимаешь знакомую кнопку и всё.

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

Хотя сейчас к ЕСИА могут подключиться не все организации, можно ожидать, что такая авторизация скоро станет де-факто стандартом для пользовательских сервисов. Просто потому, что это надёжно и удобно для клиентов – вместо отдельной учётной записи для каждого ресурса можно использовать единый аккаунт «Госуслуг» и бесшовно пользоваться любыми нужными услугами. Поэтому задумываться об интеграции стоит всем компаниям.

Как информационная система работает с ЕСИА

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

Технически процесс выглядит так:

1. Пользователь обращается к защищённому ресурсу информационной системы (например, при онлайн-покупке полиса ОСАГО).

Читайте также:  Россияне считают самой важной национальной целью здоровье и благополучие людей

2. Информационная система направляет в ЕСИА запрос на аутентификацию.

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

5. На основании этой информации система открывает пользователю доступ.

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

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

/// <summary>
/// Получить токен доступа
/// </summary>
/// <param name="code">Код доступа для получения кода доступа</param>
/// <param name="callbackUrl">Коллбек адрес для редиректа после автризации</param>
/// <param name="certificate">Сертификат для подписи запросов</param>
/// <returns>Токен доступа</returns>
public async Task<EsiaAuthToken> GetAccessToken(
	string code,
	string callbackUrl = null,
	X509Certificate2 certificate = null)
{
	var timestamp = DateTime.UtcNow.ToString("yyyy.MM.dd HH:mm:ss +0000");
	var state = Guid.NewGuid().ToString("D");

	// Create signature in PKCS#7 detached signature UTF-8
	var clientSecret = GetClientSecret(
		certificate,
		Configuration.Scope,	// Скоуп запроса
		timestamp,
		Configuration.ClientId,	// Идентификатор ИС
		state);

	var requestParams = new List<KeyValuePair<string, string>>
	{
		new KeyValuePair<string, string>("client_id", Configuration.ClientId),
		new KeyValuePair<string, string>("code", code),
		new KeyValuePair<string, string>("grant_type", "authorization_code"),
		new KeyValuePair<string, string>("state", state),
		new KeyValuePair<string, string>("scope", Configuration.Scope),
		new KeyValuePair<string, string>("timestamp", timestamp),
		new KeyValuePair<string, string>("token_type", "Bearer"),
		new KeyValuePair<string, string>("client_secret", clientSecret),
		new KeyValuePair<string, string>("redirect_uri", callbackUrl)
	};
	using (var client = new HttpClient())
	using (var response = await client.PostAsync(Configuration.EsiaTokenUrl, new FormUrlEncodedContent(requestParams)))
	{
		response.EnsureSuccessStatusCode();
		var tokenResponse = await response.Content.ReadAsStringAsync();

		var token = JsonConvert.DeserializeObject<EsiaAuthToken>(tokenResponse);

		Argument.NotNull(token?.AccessToken, "Не найден токен доступа");
		Argument.Require(state == token.State, "Идентификатор запроса некорректный");

		return token;
	}
}

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

/// <summary>
/// Ответ от ЕСИА с токеном доступа
/// </summary>
public class EsiaAuthToken
{
	/// <summary>
	/// Токен доступа
	/// </summary>
	[JsonProperty("access_token")]
	public string AccessToken { get; set; }

	/// <summary>
	/// Идентификатор запроса
	/// </summary>
	public string State { get; set; }

	/// <summary>
	/// Хранилище данных в токене
	/// </summary>
	public EsiaAuthTokenPayload Payload
	{
		get
		{
			if (string.IsNullOrEmpty(AccessToken))
			{
				return null;
			}

			string[] parts = AccessToken.Split('.');
			if (parts.Length < 2)
			{
				throw new System.Exception($"При расшифровке токена доступа произошла ошибка. Токен: {AccessToken}");
			}

			var payload = Encoding.UTF8.GetString(Base64UrlEncoder.Decode(parts[1]));
			return JsonConvert.DeserializeObject<EsiaAuthTokenPayload>(payload);
		}
	}
}

/// <summary>
/// Данные из токена доступа
/// </summary>
public class EsiaAuthTokenPayload
{
	/// <summary>
	/// Идентификатор токена
	/// </summary>
	[JsonProperty("urn:esia:sid")]
	public string TokenId { get; set; }

	/// <summary>
	/// Идентификатор пользователя
	/// </summary>
	[JsonProperty("urn:esia:sbj_id")]
	public string UserId { get; set; }
}

Как работает ЕСИА

Чтобы получить доступ ко всем возможностям учётной записи ЕСИА, нужно подтвердить личность. Проще всего это сделать через партнёров оператора единой системы идентификации. Например, клиенты Сбербанка могут пройти идентификацию по СберID в режиме онлайн. Подобные сервисы есть и у других банков-партнёров. Подтвердить личность дистанционно также можно с помощью квалифицированной электронной подписи. Если эти варианты недоступны, то идентификацию проходят в центрах обслуживания (нужен паспорт и СНИЛС). Ближайший офис можно найти на карте на портале Госуслуги. И ещё один вариант — заказать в личном кабинете код подтверждения, который придёт заказным письмом Почтой России.

Получите сертификат ЭЦП

Пройдите идентификацию и получите сертификат удалённо с помощью смартфона и биометрического загранпаспорта.

Получить консультацию по оформлению электронной подписи
Облако – лого
Облако – лого

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

  1. Пользователь хочет получить доступ к какой-либо информационной системе (ресурсу), которая использует авторизацию через ЕСИА, и выбирает этот способ.
  2. Ресурс направляет в ЕСИА соответствующий электронный запрос.
  3. Для подтверждения подлинности пользователя система перенаправляет его с ресурса на свою страницу входа в систему. Если вход прошёл успешно, система запрашивает у пользователя разрешение на предоставление ресурсу доступа к личным данным.
  4. Если пользователь был успешно проверен и разрешил стороннему ресурсу доступ к своим данным, система передаёт ресурсу необходимую информацию для авторизации пользователя.
  5. После поступления данных ресурс даёт пользователю доступ в свою систему.

На практике весь процесс занимает несколько секунд.

Получение токена

Следующий шаг ― получение маркера доступа (он же токен) в обмен на авторизационный код, который был получен в качестве параметра при успешной авторизации пользователя на портале Госуслуг.

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

URI getTokenUri = new URIBuilder(ESIA_TOKEN_API_URL)
        .addParameters(Arrays.asList(
          new BasicNameValuePair(RequestEnum.CLIENT_ID.getParam(), requestDto.getClientId()),
          new BasicNameValuePair(RequestEnum.CODE.getParam(), code),
          new BasicNameValuePair(RequestEnum.GRANT_TYPE.getParam(), requestDto.getGrantType()),
          new BasicNameValuePair(RequestEnum.CLIENT_SECRET.getParam(), requestDto.getClientSecret()),
          new BasicNameValuePair(RequestEnum.STATE.getParam(), requestDto.getState()),
          new BasicNameValuePair(RequestEnum.REDIRECT_URI.getParam(), requestDto.getRedirectUri()),
          new BasicNameValuePair(RequestEnum.SCOPE.getParam(), requestDto.getScope()),
          new BasicNameValuePair(RequestEnum.TIMESTAMP.getParam(), requestDto.getTimestamp()),
          new BasicNameValuePair(RequestEnum.TOKEN_TYPE.getParam(), requestDto.getTokenType())
        ))
        .build();
HttpUriRequest getTokenPostRequest = RequestBuilder.post()
        .setUri(getTokenUri)
        .setHeader(HttpHeaders.CONTENT_TYPE, "application/x-www-form-urlencoded")
        .build();

Получив ответ, распарсим его и получим токен:

try (CloseableHttpResponse response = httpClient.execute(getTokenPostRequest)) {
  HttpEntity tokenEntity = response.getEntity();
  String tokenEntityString = EntityUtils.toString(tokenEntity);
  tokenResponseDto = extractEsiaGetResponseTokenDto(tokenEntityString);
}

Токен представляет собой строку, состоящую из трёх частей и разделённых точками: HEADER.PAYLOAD.SIGNATURE, где:

  • HEADER ― это заголовок, имеющий в себе свойства токена, в том числе алгоритм подписи;
  • PAYLOAD ― это информация о токене и субъекте, которую запрашиваем у Госуслуг;
  • Signature ― это подпись HEADER.PAYLOAD.

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

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

/// <summary>
/// Получить данные пользователя
/// </summary>
/// <param name="userId">Идентификатор пользователя</param>
/// <param name="accessToken">Токен доступа</param>
/// <returns>Данные пользователя</returns>
public async Task<EsiaUser> GetUser(string userId, string accessToken)
{
	using (var client = new HttpClient())
	{
		client.DefaultRequestHeaders.Clear();
		client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

		var response = await client.GetStringAsync($"{Configuration.EsiaRestUrl}/prns/{userId}?embed=(organizations)");
		var user = JsonConvert.DeserializeObject<EsiaUser>(response);
		user.Id = user.Id ?? userId;

		return user;
	}
}

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

/// <summary>
/// Пользователь ЕСИА
/// </summary>
public class EsiaUser
{
	/// <summary>
	/// Идентификатор
	/// </summary>
	[JsonProperty("oid")]
	public string Id { get; set; }

	/// <summary>
	/// Фамилия
	/// </summary>
	[JsonProperty("firstName")]
	public string FirstName { get; set; }

	/// <summary>
	/// Имя
	/// </summary>
	[JsonProperty("lastName")]
	public string LastName { get; set; }

	/// <summary>
	/// Отчество
	/// </summary>
	[JsonProperty("middleName")]
	public string MiddleName { get; set; }

	/// <summary>
	/// Подтвержден ли пользователь
	/// </summary>
	[JsonProperty("trusted")]
	public bool Trusted { get; set; }

	/// <summary>
	/// Ссылки на организации
	/// </summary>
	[JsonProperty("organizations")]
	public EsiaUserOrganizations OrganizationLinks { get; set; }
}

/// <summary>
/// Ссылки на организации
/// </summary>
public class EsiaUserOrganizations
{
	[JsonProperty("elements")]
	public List<string> Links { get; set; }
}

Как организации подключиться к ЕСИА

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

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

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

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

Чтобы получить электронную подпись, оставьте заявку. Наши специалисты помогут вам оформить электронную подпись для физических и юридических лиц — удалённо, быстро и по выгодной цене.

Валидация токена

public static boolean isEsiaSignatureValid(String data, String dataSignature) throws Exception {
  InputStream inputStream = EsiaUtil.class.getClassLoader().getResourceAsStream(CERTIFICATE); // Публичный ключ ЕСИА, представленный как поток
  CertificateFactory certFactory = CertificateFactory.getInstance("X.509"); // Создание объекта фабрики с указанием стандарта открытого ключа X.509
  X509Certificate certificate = (X509Certificate) certFactory.generateCertificate(inputStream);
  Signature signature = Signature.getInstance(certificate.getSigAlgName(), new JCP()); // Создание экземпляра класса Signature с указанием алгоритма подписи и провайдера JCP от КриптоПро
  signature.initVerify(certificate.getPublicKey()); // Инициализация открытого ключа для верификации
  signature.update(data.getBytes()); // Загрузка байтового массива строки, которую нужно верифицировать 
  return signature.verify(Base64.getUrlDecoder().decode(dataSignature));
}

В соответствии с методическими указаниями необходимо проверять срок действия маркера. Если срок действия истек, то нужно создать новую ссылку с дополнительными параметрами и сделать запрос с помощью http-клиента:

URI refreshTokenUri = new URIBuilder(ESIA_TOKEN_API_URL)
        .addParameters(Arrays.asList(
                new BasicNameValuePair(RequestEnum.CLIENT_ID.getParam(), requestDto.getClientId()),
                new BasicNameValuePair(RequestEnum.REFRESH_TOKEN.getParam(), tokenResponseDto.getRefreshToken()),
                new BasicNameValuePair(RequestEnum.CODE.getParam(), code),
                new BasicNameValuePair(RequestEnum.GRANT_TYPE.getParam(), EsiaConstants.REFRESH_GRANT_TYPE),
                new BasicNameValuePair(RequestEnum.STATE.getParam(), requestDto.getState()),
                new BasicNameValuePair(RequestEnum.SCOPE.getParam(), requestDto.getScope()),
                new BasicNameValuePair(RequestEnum.TIMESTAMP.getParam(), requestDto.getTimestamp()),
                new BasicNameValuePair(RequestEnum.TOKEN_TYPE.getParam(), requestDto.getTokenType()),
                new BasicNameValuePair(RequestEnum.CLIENT_SECRET.getParam(), requestDto.getClientSecret()),
                new BasicNameValuePair(RequestEnum.REDIRECT_URI.getParam(), requestDto.getRedirectUri())
        ))
        .build();

Получение URL для переадресации

Первый шаг ― это получение авторизационного кода. В нашем случае это делает отдельный сервис с переадресацией на страницу авторизации портала Госуслуг (расскажем об этом немного подробнее).

Сначала мы инициализируем переменные ESIA_AUTH_URL (адрес ЕСИА) и API_URL (адрес, на который происходит редирект в случае успешной авторизации). После этого создаем объект EsiaRequestParams, который содержит в своих полях параметры запроса к ЕСИА, и сформируем ссылку esiaAuthUri.

public Response loginByEsia() throws Exception {
  final String ESIA_AUTH_URL = dao.getEsiaAuthUrl(); // Адрес ЕСИА
  final String API_URL = dao.getApiUrl(); // Адрес, на который произойдет редирект с случае успешной авторизации
  EsiaRequestParams requestDto = new EsiaRequestParams(API_URL);
  URI esiaAuthUri = new URIBuilder(ESIA_AUTH_URL)
          .addParameters(Arrays.asList(
            new BasicNameValuePair(RequestEnum.CLIENT_ID.getParam(), requestDto.getClientId()),
            new BasicNameValuePair(RequestEnum.SCOPE.getParam(), requestDto.getScope()),
            new BasicNameValuePair(RequestEnum.RESPONSE_TYPE.getParam(), requestDto.getResponseType()),
            new BasicNameValuePair(RequestEnum.STATE.getParam(), requestDto.getState()),
            new BasicNameValuePair(RequestEnum.TIMESTAMP.getParam(), requestDto.getTimestamp()),
            new BasicNameValuePair(RequestEnum.ACCESS_TYPE.getParam(), requestDto.getAccessType()),
            new BasicNameValuePair(RequestEnum.REDIRECT_URI.getParam(), requestDto.getRedirectUri()),
            new BasicNameValuePair(RequestEnum.CLIENT_SECRET.getParam(), requestDto.getClientSecret())
          ))
          .build();
  return Response.temporaryRedirect(esiaAuthUri).build();
}

Для наглядности покажем, как может выглядеть класс EsiaRequestParams:

public class EsiaRequestParams {

  String clientId;
  String scope;
  String responseType;
  String state;
  String timestamp;
  String accessType;
  String redirectUri;
  String clientSecret;
  String code;
  String error;
  String grantType;
  String tokenType;

  public EsiaRequestParams(String apiUrl) throws Exception {
    this.clientId = CLIENT_ID;
    this.scope = Arrays.stream(ScopeEnum.values())
            .map(ScopeEnum::getName)
            .collect(Collectors.joining(" "));
    responseType = RESPONSE_TYPE;
    state = EsiaUtil.getState();
    timestamp = EsiaUtil.getUrlTimestamp();
    accessType = ACCESS_TYPE;
    redirectUri = apiUrl + RESOURCE_URL + "/" + AUTH_REQUEST_ESIA;
    clientSecret = EsiaUtil.generateClientSecret(String.join("", scope, timestamp, clientId, state));
    grantType = GRANT_TYPE;
    tokenType = TOKEN_TYPE;
  }
}

Каждый запрос к ЕСИА имеет параметр client_secret, который представляет собой откреплённую электронную подпись в формате PKCS7 (Public Key Cryptography Standard). В нашем случае для подписи используется сертификат, который был получен удостоверяющим центром перед началом работ по интеграции с ЕСИА. Как работать с хранилищем ключей хорошо описано в этом цикле статей.

Читайте также:  Когда будет новое пособие от путина

Для примера покажем, как выглядит хранилище ключей, предоставляемое компанией КриптоПро:

Esia "хабр и SAML" запрашивает генерацию подписи

Вызов приватного и публичного ключей в этом случае будет выглядеть так:

KeyStore keyStore = KeyStore.getInstance("HDImageStore"); // Создание экземпляра хранилища
keyStore.load(null, null);
PrivateKey privateKey = (PrivateKey) keyStore.getKey(esiaKeyStoreParams.getName(), esiaKeyStoreParams.getValue().toCharArray()); // Получение приватного ключа
X509Certificate certificate = (X509Certificate) keyStore.getCertificate(esiaKeyStoreParams.getName()); // Получение сертификата, он же – открытый ключ.

Где JCP.HD_STORE_NAME ― имя хранилища в КриптоПро, esiaKeyStoreParams.getName() ― имя контейнера и esiaKeyStoreParams.getValue().toCharArray() ― пароль контейнера.
В нашем случае не нужно загружать данные в хранилище методом load(), так как ключи уже будут там при указании имени этого хранилища.

Здесь важно помнить, что получения подписи в виде

final Signature signature = Signature.getInstance(SIGN_ALGORITHM, PROVIDER_NAME);
signature.initSign(privateKey);
signature.update(data);
final byte[] sign = signature.sign();

нам недостаточно, так как ЕСИА требует откреплённую подпись формата PKCS7. Поэтому следует создать подпись формата PKCS7.

Пример нашего метода, возвращающего откреплённую подпись, выглядит следующим образом:

public String generateClientSecret(String rawClientSecret) throws Exception {
    if (this.localCertificate == null || this.esiaCertificate == null) throw new RuntimeException("Signature creation is unavailable");
    return CMS.cmsSign(rawClientSecret.getBytes(), localPrivateKey, localCertificate, true);
  }

Здесь мы проверяем наличие нашего открытого ключа и открытого ключа ЕСИА. Так как метод cmsSign() может содержать конфиденциальную информацию, мы не будем его раскрывать.

Укажем лишь некоторые детали:

  • rawClientSecret.getBytes() ― байтовый массив scope, timestamp, clientId и state;
  • localPrivateKey ― приватный ключ из контейнера;
  • localCertificate ― публичный ключ из контейнера;
  • true ― булево значение параметра подписи ― открепленная или нет.

Пример создания подписи можно найти в java-библиотеке КриптоПро, там стандарт PKCS7 называется CMS. А также в руководстве программиста, которое лежит вместе с исходниками скаченной версии КриптоПро.

Зачем нам нужна интеграция с ЕСИА?

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

Esia "хабр и SAML" запрашивает генерацию подписи

Кроме того, интеграция с ЕСИА позволила Русфинанс Банку:

  • сократить время заполнения онлайн-анкет;
  • уменьшить количество отказов пользователей при попытке заполнить большое количество полей вручную;
  • обеспечить поток более «качественных», верифицированных клиентов.

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

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

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

  • .Net Framework 4.8
  • КриптоПро 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»))

private string GetClientSecret(
	X509Certificate2 certificate, 
	string scope, 
	string timestamp, 
	string clientId, 
	string state)
{
	var signMessage = Encoding.UTF8.GetBytes($"{scope}{timestamp}{clientId}{state}");

	byte[] encodedSignature = SignatureProvider.Sign(signMessage, certificate);
 
	return Base64UrlEncoder.Encode(encodedSignature);
}

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

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

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

http://esia.gosuslugi.ru/org_shortname/?org_oid={organizationId} http://esia.gosuslugi.ru/ org_fullname/?org_oid={organizationId}

/// <summary>
/// Получить токен для доступа к организациям пользователя
/// </summary>
/// <param name="organizationId">Идентификатор организации</param>
/// <param name="code">Код доступа</param>
/// <param name="state">Идентификатор запроса</param>
/// <param name="callbackUrl">Коллбек адрес для редиректа после авторизации</param>
/// <param name="certificate">Сертификат для подписи запросов</param>
/// <returns>Токен для доступа к организациям пользователя</returns>
public async Task<EsiaAuthToken> GetOrganizationAccessToken(
	string organizationId,
	string code,
	string state,
	string callbackUrl = null,
	X509Certificate2 certificate = null)
{
	var timestamp = DateTime.UtcNow.ToString("yyyy.MM.dd HH:mm:ss +0000");
	var scope = string.Join(" ", Configuration.OrganizationScope.Split(new char[] { ' ' }, StringSplitOptions.RemoveEmptyEntries)
		.Select(orgScope => $"{Configuration.EsiaBaseUrl}/{orgScope}?org_oid={organizationId}"));

	// Create signature in PKCS#7 detached signature UTF-8
	var clientSecret = GetClientSecret(
		certificate,
		scope,
		timestamp,
		Configuration.ClientId,
		state);

	var requestParams = new List<KeyValuePair<string, string>>
	{
		new KeyValuePair<string, string>("client_id", Configuration.ClientId),
		new KeyValuePair<string, string>("code", code),
		new KeyValuePair<string, string>("grant_type", "client_credentials"),
		new KeyValuePair<string, string>("state", state),
		new KeyValuePair<string, string>("scope", scope),
		new KeyValuePair<string, string>("timestamp", timestamp),
		new KeyValuePair<string, string>("token_type", "Bearer"),
		new KeyValuePair<string, string>("client_secret", clientSecret),
		new KeyValuePair<string, string>("redirect_uri", callbackUrl)
	};
	using (var client = new HttpClient())
	using (var response = await client.PostAsync(Configuration.EsiaTokenUrl, new FormUrlEncodedContent(requestParams)))
	{
		response.EnsureSuccessStatusCode();
		var tokenResponse = await response.Content.ReadAsStringAsync();

		var token = JsonConvert.DeserializeObject<EsiaAuthToken>(tokenResponse);

		Argument.NotNull(token?.AccessToken, "Не найден токен доступа");
		Argument.Require(state == token.State, "Идентификатор запроса некорректный");

		return token;
	}
}

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

/// <summary>
/// Получить данные организации
/// </summary>
/// <param name="organizationLink">Ссылка на организацию</param>
/// <param name="accessToken">Токен доступа</param>
/// <returns>Данные организации</returns>
public async Task<EsiaOrganization> GetOrganization(string organizationLink, string accessToken)
{
	using (var client = new HttpClient())
	{
		client.DefaultRequestHeaders.Clear();
		client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

		var response = await client.GetStringAsync(organizationLink);
		var organization = JsonConvert.DeserializeObject<EsiaOrganization>(response);
		return organization;
	}
}

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

// Получим токен доступа по коду доступа
var accessToken = await IntegrationService.GetAccessToken(request.Code, request.CallbackUrl);

// Получим информацию о пользователе из ЕСИА
var user = await IntegrationService.GetUser(accessToken.Payload.UserId, accessToken.AccessToken);

// Если у пользователя есть организации - полезем в ЕСИА за ними
if (user.OrganizationLinks?.Links?.Any() == true)
{
	// Новый токен доступа - чисто для организаций
	var link = user.OrganizationLinks.Links.First();
	var organizationId = link.Split('/').Last();
	var organizationAccessToken = await IntegrationService.GetOrganizationAccessToken(organizationId, request.Code, accessToken.State, request.CallbackUrl);

	user.Organization = await IntegrationService.GetOrganization(link, organizationAccessToken.AccessToken);
}

return user;

Что теперь делать со всеми этими данными?

Мы можем сделать парсинг данных и получать объекты с требуемыми полями. Здесь каждый разработчик может оформлять классы как ему необходимо, в соответствии с техническим заданием.

Пример получения объекта с необходимыми полями:

final ObjectMapper objectMapper = new ObjectMapper()
	.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

String personDataEntityString = esiaPersonDataFetcher
	.apply(ESIA_REST_API_URL + "/prns/" + esiaAccountId);

EsiaPersonDto esiaPersonDto = objectMapper
	.readValue(personDataEntityString, EsiaPersonDto.class);

Заполняем объект esiaPersonDto необходимыми данными, например, контактами:

for (String contactUrl : esiaListDto.getElementUrls()) {
  String contactEntityString = esiaPersonDataFetcher.apply(contactUrl);
  EsiaContactDto esiaContactDto = objectMapper.readValue(contactEntityString, EsiaContactDto.class); // Десериализация контакта
  if (esiaContactDto.getType() == null) continue;
  switch (esiaContactDto.getType().toUpperCase()) {
    case EsiaContactDto.MBT: // Если это номер мобильного телефона, то заполним поле mobilePhone
      esiaPersonDto.setMobilePhone(esiaContactDto.getValue());
      break;
    case EsiaContactDto.EML: // Если это адрес электронной почты, то заполним поле email
      esiaPersonDto.setEmail(esiaContactDto.getValue());
  }
}

Класс EsiaPersonDto выглядит следующим образом:

@Data
@FieldNameConstants(prefix = "")
public class EsiaPersonDto {

  private String firstName;
  private String lastName;
  private String middleName;
  private String birthDate;
  private String birthPlace;
  private Boolean trusted;  // тип учетной записи - подтверждена (“true”) / не подтверждена (“false”)
  private String status;    // статус УЗ - Registered (зарегистрирована) /Deleted (удалена)
  // Назначение полей непонятно, но они есть при запросе /prns/{oid}
  private List<String> stateFacts;
  private String citizenship;
  private Long updatedOn;
  private Boolean verifying;
  @JsonProperty("rIdDoc")
  private Integer documentId;
  private Boolean containsUpCfmCode;
  @JsonProperty("eTag")
  private String tag;
  // ----------------------------------------
  private String mobilePhone;
  private String email;

  @javax.validation.constraints.Pattern(regexp = "(\\d{2})\\s(\\d{2})")
  private String docSerial;

  @javax.validation.constraints.Pattern(regexp = "(\\d{6})")
  private String docNumber;

  private String docIssueDate;

  @javax.validation.constraints.Pattern(regexp = "([0-9]{3})\\-([0-9]{3})")
  private String docDepartmentCode;

  private String docDepartment;

  @javax.validation.constraints.Pattern(regexp = "\\d{14}")
  @JsonProperty("snils")
  private String pensionFundCertificateNumber;

  @javax.validation.constraints.Pattern(regexp = "\\d{12}")
  @JsonProperty("inn")
  private String taxPayerNumber;

  @JsonIgnore
  @javax.validation.constraints.Pattern(regexp = "\\d{2}")
  private String taxPayerCertificateSeries;

  @JsonIgnore
  @javax.validation.constraints.Pattern(regexp = "\\d{10}")
  private String taxPayerCertificateNumber;
}

Работа по усовершенствованию сервиса будет продолжаться, ведь ЕСИА не стоит на месте.

Заключение

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

Оцените статью