Проведение идентификации и аутентификации пользователей#

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

Интеграция сайта с развернутым и настроенным ПО ESIA-Bridge включает в себя:

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

  2. разработку обработчика получения результатов идентификации от ESIA-Bridge.

Обработчик состоит из веб-части и серверной части:

  • веб-часть срабатывает, когда после успешной идентификации ESIA-Bridge осуществляет перенаправление пользователя на URL обработчика;

  • веб-часть обработчика должна считать специальную cookie со своего домена, установленную ESIA-Bridge, и передать ее своей серверной части;

  • серверная часть с использованием полученного значения из cookie может обращаться к REST-сервису ESIA-Bridge по HTTP/HTTPs и получать необходимые ей данные о прошедшем идентификацию и аутентификацию пользователе.

Далее подробно описаны все эти шаги. При интеграции сайта также можно воспользоваться доступной open source библиотекой.

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

Запрос на проведение аутентификации пользователя

Запрос на проведение аутентификации пользователя через ЕСИА предполагает перенаправление пользователя на точку обработки запроса ESIA-Bridge (https://esia.client.testcase.ru/blitz/bridge/entrance, где esia.client.testcase.ru – домен, на который установлен ESIA-Bridge). При реализации запрещено использовать фреймы, т.е. страницу аутентификации ЕСИА запрещено открывать во фрейме сайта.

В запросе указываются следующие url-параметры:

  • redirect_url – URL для возврата после проведения аутентификации (например, https://user.testcase.ru/cb); данный URL должен соответствовать домену, на который получена лицензия;

  • state – набор случайных символов, имеющий вид 128-битного идентификатора запроса, генерируется по стандарту UUID (например, a68fdb9e-c4df-d136-a484-b286471f4e2c);

  • mode – режим получения данных пользователя (опциональный параметр). Указывается значение online, если системе достаточно получать данные о пользователе на момент его аутентификации (режим по умолчанию). Значение offline позволяет в последующем получать актуальные данные о пользователе независимо от того, когда была произведена аутентификация. Также в режиме offline в составе получаемых данных будет возвращен маркер доступа от ЕСИА.

  • display – способ отображения страницы входа ЕСИА (опциональный параметр). Для отображения страницы входа ЕСИА в виде модального окна параметр должен иметь значение popup. Параметр не указывается, если страница входа должна быть открыта в обычном режиме.

Внимание

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

Пример запроса:

https://esia.client.testcase.ru/blitz/bridge/entrance?redirect_url=https://user.testcase.ru/cb&state=a68fdb9e-c4df-d136-a484-b286471f4e2c

Пример запроса при offline-режиме получения данных о пользователе:

https://esia.client.testcase.ru/blitz/bridge/entrance?redirect_url=https://user.testcase.ru/cb&state=a68fdb9e-c4df-d136-a484-b286471f4e2c&mode=offline

Пример запроса для открытия страницы в модальном окне:

https://esia.client.testcase.ru/blitz/bridge/entrance?redirect_url=https://user.testcase.ru/cb&state=a68fdb9e-c4df-d136-a484-b286471f4e2c&display=popup

Для открытия страницы входа ЕСИА в модальном окне необходимо открыть указанную страницу ESIA-Bridge в режиме popup. Пример фрагмента javascript для открытия страницы во всплывающем окне:

var w = 800;
var h = 600;
var left = ($(window).width()/2)-(w/2);
var top = ($(window).height()/2)-(h/2);
var popup = window.open("request_url", "Request popup", "width=" + w + ",height=" + h + ",top=" + top +
",left=" + left + ",location=1,status=0,menubar=0,resizable=0,scrollbars=0");

Request_url должен быть заменен на URL, указанный выше. После получения ответа от ESIA-Bridge порталу нужно обеспечить закрытие модального окна и передачу результатов аутентификации в основную веб-страницу портала.

Получение ответа на запрос

При успешно выполненной аутентификации пользователя через ЕСИА ESIA-Bridge:

  1. Возвращает пользователя на redirect_url и передает URL-параметр result`, имеющий значение AUTHORIZED. Пример сообщения об успешной аутентификации:

    http://user.testcase.ru/cb?result=AUTHORIZED

  2. Устанавливает сессионную cookie с именем “tokenSCS”, которую необходимо использовать для получения данных пользователя. Пример cookie:

    kAAVPt..F2stFT..|U0gx..kM|vT3X6Q..|Z0uBP4w6J..jZsg

При возникновении ошибки ESIA-Bridge возвращает пользователя на redirect_url и передает следующие URL-параметры:

  • result – параметр, принимающий значение FAILED;

  • error – параметр, содержащий код ошибки;

  • error_description – параметр, содержащий описание ошибки.

Пример ответа:

http://user.testcase.ru/cb?result=FAILED&error=access_denied&error_description=ESIA-007004%3A+The+resource+owner+or+authorization+server+denied+the+request.

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

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

Для получения данных пользователя необходимо обратиться к сервису ESIA-Bridge, возвращающему данные пользователя. Для этого необходимо выполнить HTTP-запрос методом POST на адрес точки получения данных пользователя . Особенности запроса:

  • в теле (body) запроса необходимо указать параметр “token”, имеющий значение полученной сессионной cookie tokenSCS или ключа доступа (при повторных обращениях в случае использования offline-режима доступа к данным пользователя);

  • в заголовке (http header) необходимо указать параметр Content-Type со значением application/x-www-form-urlencoded.

Пример запроса:

POST https://esia.client.testcase.ru/blitz/bridge/user
Content-Type: application/x-www-form-urlencoded
token=MIrS8LUZNHHh-8gBjzoBbHaI5qvsCIF3I3qDjh7mOMif5L90z2SAYYO9UN2talPmqiavxzjfE5CpAhV4S2t_kWyV6UHqskUIIT1B-EFFJmLAYEYnUbuD60ehbydOJVYsGmrjvaLzSwY6oqI3GKxgZaROq-9qwafgw5bgSdjCI18NU_QJHr2oRzumxwTEbLO5QKeQNekSVZeM_71q8t7l8Lh8PonOFl9Kiz2__00HT73QKIi_alE6qdzytPeS0tv68bcRdiUU2w6pzW6oIyQ6EJgpdn6zj3ff2dPiJ9pJE0oOVqcgzQHdq7_1UezpFw9qoQPEJSpAGrIH5ewhG8__k8mtz_EASApmjK20stkBdqeyFS9s21unHDmlvd13yh7Fk0ijm0vWl_iNAeCai-H_tozj7YH65L8eXqiq5sdkl2HmQHiEPOwWsmS1JivjgdqGHiaqVEiu5oXT_fEm6hrFj7nsxeedDVUGJ14FBYGgGU_Sgpf5ql2rHrJyz9hVr3MR|MTQxODMxMjc2Mg|U0gxQVMxMjhDQkM|6dkboBYuF4Y7ZtlHztSkjg|4n9D_efCPLv3fFl_JLTz5YgENWc

Ответ с данными пользователя (online-режим)

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

  • oid – уникальный идентификатор пользователя ЕСИА;

  • firstName – имя;

  • lastName – фамилия;

  • middleName – отчество;

  • birthDate – дата рождения в формате ДД.ММ.ГГГГ;

  • gender – пол (M – мужской, F – женский);

  • trusted – признак подтвержденной учетной записи (true / false);

  • birthPlace – место рождения;

  • citizenship – гражданство (RUS для России);

  • snils – СНИЛС (в формате ХХХ-ХХХ-ХХХ ХХ);

  • inn – ИНН (в формате ХХХХХХХХХХХХ);

  • passport – данные паспорта, включают в себя:

    • id – идентификатор документа в ЕСИА;

    • type – тип документа (имеет значение “RF_PASSPORT”);

    • series – серия;

    • number – номер;

    • issueDate – дата выдачи в формате ДД.ММ.ГГГГ;

    • issueId – код подразделения;

    • issuedBy – кем выдан;

    • status – статус документа (“VERIFIED” для проверенного документа);

  • drivingLicense – водительское удостоверение пользователя:

    • id – идентификатор документа в ЕСИА;

    • type – тип документа (имеет значение “RF_DRIVING_LICENSE”);

    • series – серия;

    • number – номер;

    • issueDate – дата выдачи в формате ДД.ММ.ГГГГ;

    • expiryDate – дата окончания действия в формате ДД.ММ.ГГГГ;

    • status – статус документа (“NOT_VERIFIED” для непроверенного документа);

  • mobile – мобильный телефон пользователя; включает в себя:

    • id – идентификатор в ЕСИА;

    • type – тип контакта (имеет значение “MBT”);

    • value – значение (в формате +7(ХХХ)ХХХХХХХ);

    • vrfStu – признак подтверждения контакта (<VERIFIED> для проверенного контакта);

  • phone – домашний телефон пользователя; включает в себя:

    • id – идентификатор в ЕСИА;

    • type – тип контакта (имеет значение “PHN”);

    • value – значение (в формате +7(ХХХ)ХХХХХХХ);

    • vrfStu – признак подтверждения контакта (передается <NOT_VERIFIED>, поскольку этот контакт — непроверенный);

  • email – адрес электронной почты пользователя; включает в себя:

    • id – идентификатор в ЕСИА;

    • type – тип контакта (имеет значение “EML”);

    • value – значение;

    • vrfStu – признак подтверждения контакта (<VERIFIED> для проверенного контакта);

  • liveAddress – адрес места проживания; включает в себя:

    • id – идентификатор в ЕСИА;

    • type – тип адреса (имеет значение “PLV”);

    • fiasCode – код ФИАС;

    • addressStr – адрес в виде строки;

    • zipCode – индекс;

    • countryId – идентификатор страны, для России принимает значение RUS;

    • region – регион;

    • city – город;

    • district – внутригородской район;

    • area – район;

    • settlement – поселение;

    • additionArea – доп. территория;

    • additionAreaStreet – улица на доп. территории;

    • street – улица;

    • house – дом;

    • building – строение;

    • frame – корпус;

    • flat – квартира.

  • registerAddress – адрес регистрации; включает в себя те же параметры, что и адрес места проживания. Разница заключается только в том, что атрибут type принимает значение PRG.

  • roles – список организаций пользователя, т.е. организаций, к которым пользователь присоединен в качестве сотрудника. По каждой организации возвращаются следующие данные:

    • oid – уникальный идентификатор организации в ЕСИА;

    • fullName – полное название организации;

    • ogrn – ОГРН организации (или ОГРНИП для индивидуальных предпринимателей);

    • chief – признак, является ли пользователь руководителем организации (значение true) или нет (значение false);

    • branchName – имя филиала организации (передается только в том случае, если пользователь – сотрудник организации).

  • state – набор случайных символов, который был изначально направлен в запросе на проведение аутентификации пользователя.

Пример ответа:

{
   "oid":1000081291,
   "firstName":"Иван",
   "lastName":"Иванов",
   "middleName":"Иванович",
   "birthDate":"26.04.1964",
   "gender":"M",
   "trusted":true,
   "birthPlace":"Москва",
   "citizenship":"RUS",
   "snils":"044-743-665 76",
   "inn":"774396995270",
   "passport":{
      "id":3542,
      "type":"RF_PASSPORT",
      "series":"0000",
      "number":"000003",
      "issueDate":"11.11.2010",
      "issueId":"111111",
      "issuedBy":"ОВД",
      "status":"VERIFIED"
   },
   "mobile":{
      "id":1640,
      "type":"MBT",
      "value":"+7(925)1234567",
      "vrfStu":"VERIFIED"
   },
   "phone": {
      "id": 66145019,
      "type": "PHN",
      "value": "+7(495)4376843",
      "vrfStu": "NOT_VERIFIED"
   },
   "email": {
      "id": 35493567,
      "type": "EML",
      "value": "mail@example.com",
      "vrfStu": "VERIFIED"
   },
   "liveAddress": {
      "id": 20357641,
      "type": "PLV",
      "fiasCode": "74-0-037-000-000-001-0000-0000-000",
      "addressStr": "Челябинская область, Октябрьский район, Октябрьское село",
      "area": "Октябрьский Район",
      "settlement": "Октябрьское Село",
      "region": "Челябинская Область",
      "countryId": "RUS",
      "zipCode": "457170",
      "house": "1",
      "flat": "1"
    },
    "registerAddress": {
      "id": 20168761,
      "type": "PRG",
      "fiasCode": "59-0-000-001-000-000-1705-0000-000",
      "addressStr": "Пермский край, Пермь город, сдт Пермстройпуть сад",
      "city": "Пермь Город",
      "region": "Пермский Край",
      "countryId": "RUS",
      "zipCode": "614000",
      "street": "сдт Пермстройпуть Сад",
      "house": "1",
      "flat": "1"
    },
   "state":"17c3078b-8751-e595-86d6-256d47855bc5" },
   "roles": [
      {
        "oid": 1000323157,
        "fullName": "ОБЩЕСТВО С ОГРАНИЧЕННОЙ ОТВЕТСТВЕННОСТЬЮ \"ТЕСТ\"",
        "ogrn": "1147746123433",
        "chief": true
      },
      {
        "oid": 1000343519,
        "fullName": "ОБЩЕСТВО С ОГРАНИЧЕННОЙ ОТВЕТСТВЕННОСТЬЮ \"ТЕСТ2\"",
        "ogrn": "1147543211733",
        "chief": false,
        "branchName": "Ромашка",
      }
   ]
}

Ответ с данными пользователя (offline-режим)

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

  • scsToken – новое значение ключа доступа, которое необходимо использовать при следующем доступе к данным пользователя;

  • accessToken – текущий маркер доступа, полученный от ЕСИА;

  • person – данные пользователя, имеющие ту же структуру, что и при online-режиме получения данных.

Пример ответа:

{
  "scsToken": "HX3hpfUlZw8uUFDaQGpOybwwVSmVC9bf9sqAPxJ4v2Mlj6GB5q_QlvkotMhSmkYLd10MNUFjM2hPufSqUia8dqzuuzNhXCceWQtzpykYbl-nxiWEuF5VeypO0claxgz2_Chx_hT6ska0nkG94Tazo3ca5a8RP6kDdi3yI9qrIY4|MTYxODQwODI5Nw|U0gxQVMxMjhDQkM|0mnD4UQcX289MYd8ihFxDQ|9ovLPSj1HWXKbhr7IsGAZAG0wxs",
  "accessToken": "eyJ2ZXIiOjEsInR5cCI6IkpXVCIsInNidCI6ImFjY2VzcyIsImFsZyI6IlJTMjU2In0.eyJuYmYiOjE2MTg0MDgyOTgsInNjb3BlIjoibW9iaWxlP29pZD0xMDAwMzQ3NjAxIGZ1bGxuYW1lP29pZD0xMDAwMzQ3NjAxIGlkX2RvYz9vaWQ9MTAwMDM0NzYwMSBvcGVuaWQgZW1haWw_b2lkPTEwMDAzNDc2MDEgZHJpdmVyc19saWNlbmNlX2RvYz9vaWQ9MTAwMDM0NzYwMSIsImlzcyI6Imh0dHA6XC9cL2VzaWEtcG9ydGFsMS50ZXN0Lmdvc3VzbHVnaS5ydVwvIiwidXJuOmVzaWE6c2lkIjoiNmNlMmFlZWMtMjExYy00MzM1LWFjNzgtZDY1ZDBkN2M4Mjk0IiwidXJuOmVzaWE6c2JqX2lkIjoxMDAwMzQ3NjAxLCJleHAiOjE2MTg0MTE4OTgsImlhdCI6MTYxODQwODI5OCwiY2xpZW50X2lkIjoiQUxGQVNUUkFIIn0.kmWG8J6S3E4b_wptPzjbbdHAA47LyZybiPh0MIA2Fc8NHsf_U-j8kVN-2vPHezBmvdrtKevakPmD6o2cJmp46zmVz5cKTAjC7Pz9KnniudPoOIykbblVufveBmwKbtAnhdNK4wBmtsZAMQEcxsxk0QLTxwk9lOQv7QFkSZJcRw2xnzrxB4-INvWNOVXiPU28PTjehfMz3jHfqzZYAV1J-ba9mpCu3b0YmOTUh6a5bmRuIaUC5OxSmbdR-MFnY2EzmLrERQSNFufO5KFb4AxIvdbf_7NGfT64-tqqFXa9Wd-0EHJkB7AM5JRczMSh6NdH5b7CD90bTH41rX5OPctPww",
  "person": {
    "oid": 1000347601,
    "firstName": "Иван",
    "lastName": "Иванов",
    "middleName": "Иванович",
    "trusted": true,
    "citizenship": "RUS",
    "passport": {
      "id": 38374,
      "type": "RF_PASSPORT",
      "series": "3333",
      "number": "889999",
      "issueDate": "18.03.2016",
      "issueId": "111001",
      "issuedBy": "РУВД г.Москвы",
      "status": "VERIFIED"
    },
    "drivingLicense": {
      "id": 109388,
      "type": "RF_DRIVING_LICENSE",
      "series": "77МХ",
      "number": "125252",
      "issueDate": "04.03.2020",
      "expiryDate": "04.03.2030",
      "status": "NOT_VERIFIED"
    },
    "state": "c4604f97-b897-5692-68aa-acb94c6f67da"
  }
}

Необходимо сохранить ключ доступа scsToken из ответа и при следующем запросе данных пользователя указывать именно его. После каждого запроса данных пользователя нужно обновлять значение scsToken и при следующем запросе указывать новое значение.

Ответ при ошибке

При возникновении ошибки ESIA-Bridge возвращает json, содержащий следующие параметры:

  • error – параметр, содержащий код ошибки;

  • error_description – параметр, содержащий описание ошибки.