Разработка скрипта ЕСИА

[ ] [ Общие сведения ] [ Процесс выполнения скрипта ] [ Методика разработки скрипта ] [ Сценарии использования ] [ Загрузка информации о ФЛ ЕСИА и формирование одной УЗ ] [ Загрузка информации об организациях, в которых состоит ФЛ ЕСИА, и формирование нескольких УЗ в системе ] [ Приложение 1. Спецификация дополнительных функций ] [ Приложение 2. Сопоставление атрибутов учётной записи с атрибутами в скрипте ]

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

Avanpost FAM предоставляет возможность выполнить интеграцию с ЕСИА в качестве источника информации о пользователях.

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

• загрузка и обработка контактных, адресных и других сведений ФЛ ЕСИА;
• загрузка и обработка информации о документах ФЛ ЕСИА;
• загрузка и обработка информации об организациях ФЛ ЕСИА;
• загрузка и обновление данных о членстве УЗ в группах на основе членства в группах ЕСИА.

Текущая инструкция описывает методику разработки сценария загрузки данных из ЕСИА.

Сценарий (скрипт) загрузки информации об аккаунтах разрабатывается на языке ECMAScript 5.1. На языке базируется язык JavaScript, поэтому опыт разработки на языке JavaScript является предпочтительным для решения задачи разработки скрипта чтения данных. 

Предполагается, что разработчик сценария загрузки информации из ЕСИА обладает следующими компетенциями:

• владение языком программирования ECMAScript 5.1 или JavaScript;
• понимание механики взаимодействия с ЕСИА и знание «Методических рекомендаций по использованию Единой системы идентификации и аутентификации».

Процесс выполнения скрипта

Сценарий выполняется после получения необходимых токенов (ID Token, Access Token) и является заменой стандартного запроса на Userinfo Endpoint ЕСИА в терминологии OAuth 2.0. При этом сценарий может быть разработан как для однократного выполнения, так и для конвейерной загрузки данных сотрудника (например, при необходимости динамического изменения scopes в составе ряда запросов к Authorization Endpoint ЕСИА).

Схема аутентификации при реализации скрипта загрузки информации из ЕСИА выглядит следующим образом:

1. Пользователь инициирует аутентификацию в целевое веб-приложение. Пользователь выбирает аутентификацию через ЕСИА.
2. Avanpost FAM перенаправляет пользователя на Authorization Endpoint ЕСИА с использованием scopes, заданных в соответствующем параметре в настройках провайдера аутентификации ЕСИА.
3. Пользователь выполняет аутентификацию на стороне ЕСИА, после чего ЕСИА перенаправляет пользователя на Callback Endpoint Avanpost FAM с передачей Code.
4. Avanpost FAM получает Code и выполняет обмен Code на токены (ID Token, Access Token).

Выполнится сценарий загрузки информации из ЕСИА, настроенный для провайдера. По результатам выполнения сценария анализируется структура, заполненная через вызовы к SetAccounts. Если имеется одна УЗ, связанная с текущим ФЛ ЕСИА, то Avanpost FAM выполняет аутентификацию в эту УЗ. Если УЗ несколько – Avanpost FAM предложит пользователю выбрать одну из имеющихся УЗ. После выбора УЗ пользователь считается аутентифицированным посредством ЕСИА.

Методика разработки скрипта

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

Скрипт должен содержать в себе как минимум вызовы функции context.SetAccounts() с целью установки информации о создаваемом или обновляемом аккаунте. Если context.SetAccounts() не установил ни одной УЗ, то пользователь получит сообщение об ошибке аутентификации. Если в context.SetAccounts() установлена одна или несколько УЗ, то будет выполнена их идентификация на основе ключевого атрибута username.  Остальные атрибуты описаны в Приложении 2 текущей инструкции.

Остальные вызовы, которые могут быть реализованы из скрипта, могут содержать в себе вызовы стандартных функций из ECMAScript 5.1 и дополнительных функций, описанных в Приложении 1. Импорт сторонних ES/JS-скриптов из сетевых источников или файлов в рамках сценария недоступен.

После ввода сценария в поле «Скрипт управления пользовательскими данными и разрешениями» осуществляется его отладка. Отладка выполняется посредством выполнения процесса аутентификации через ЕСИА, оценки получаемого с точки зрения пользователя результата и просмотра отладочного журнала. Журнал выполнения аутентификации посредством сценария ЕСИА выводится в стандартный журнал системы, доступный через программу journalctl на сервере системы (например, с помощью bash-команды journalctl -ru idp). При необходимости вывода дополнительных сведений или содержимого переменных можно использовать функцию console.log(), результат выполнения которой будет выведен в системный журнал.

Сценарии использования

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

1. Загрузка информации о ФЛ ЕСИА и формирование одной УЗ.

2. Загрузка информации об организациях, в которых состоит ФЛ ЕСИА, и формирование нескольких УЗ в системе.

3. Загрузка информации об организациях, в которых состоит ФЛ ЕСИА, включая ИНН и КПП, и формирование нескольких УЗ в системе.

Загрузка информации о ФЛ ЕСИА и формирование одной УЗ

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

• ФИО;
• E-mail адрес;
• СНИЛС.

В редакторе атрибутов системы создан дополнительный атрибут snils.

Для этого на вкладке «Подключение» провайдера ЕСИА настроены параметры:

• Scopes – openid fullname email snils.

Разработан и настроен в параметрах интеграции ЕСИА следующий скрипт:

// Загружаем токены
var tokens = context.GetTokens();
var accessToken = tokens.AccessToken;
var sub = tokens.Sub;

// Загружаем профиль ФЛ ЕСИА
var profileUrl = "https://esia-portal1.test.gosuslugi.ru/rs/prns/" + sub;
var profileResponse = context.Send(
    {
        url: profileUrl,
        method: 'GET',
        headers: {
            Accept: ['*/*'],
            Authorization: ['Bearer ' + accessToken]
        }
    });
var profile = JSON.parse(profileResponse.body);

// Загружаем контактные сведения ФЛ ЕСИА (для примера использован URL тестовой ЕСИА)
var contactsUrl = "https://esia-portal1.test.gosuslugi.ru/rs/prns/" + sub + '/ctts' + '?embed=(elements)';
var contactsResponse = context.Send(
    {
        url: contactsUrl,
        method: 'GET',
        headers: {
            Accept: ['*/*'],
            Authorization: ['Bearer ' + accessToken]
        }
    });
var contacts = JSON.parse(contactsResponse.body);

// Обрабатываем контактные сведения ФЛ ЕСИА
for (var contact in contacts.elements) {
    var contactType = contacts['elements'][contact]['type'];
    if (contactType == 'EML') {
        var contactPersonMail = contacts['elements'][contact]['value'];
    }
}

// Создаём или обновляем УЗ в системе, сформированную на основе данных ЕСИА
context.SetAccounts([{
    username: profile.snils, // Формируем логин, используя СНИЛС ФЛ
    firstname: profile.firstName, // Имя
    lastname: profile.lastName, // Фамилия
    middlename: profile.middleName, // Отчество
    email: contactPersonMail, // E-mail
    attributes: {
        "СНИЛС": profile.snils, // СНИЛС
    }
}]);

Загрузка информации об организациях, в которых состоит ФЛ ЕСИА, и формирование нескольких УЗ в системе

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

В редакторе атрибутов системы создан дополнительный атрибут orgFullName.

Для этого на вкладке «Подключение», провайдера ЕСИА настроены параметры:

• Scopes – openid fullname snils usr_org.

Разработан и настроен в параметрах интеграции ЕСИА следующий скрипт:

// Заполняем переменные значениями полученных токенов
var tokens = context.GetTokens();
var accessToken = tokens.AccessToken;
var sub = tokens.Sub;

// Загружаем профиль ФЛ ЕСИА
var profileUrl = "https://esia-portal1.test.gosuslugi.ru/rs/prns/" + sub;
var profileResponse = context.Send(
    {
        url: profileUrl,
        method: 'GET',
        headers: {
            Accept: ['*/*'],
            Authorization: ['Bearer ' + accessToken]
        }
    });
var profile = JSON.parse(profileResponse.body);

// Загружаем список организаций, в которых состоит ФЛ ЕСИА
var orgUrl = "https://esia-portal1.test.gosuslugi.ru/rs/prns/" + sub + '/roles';
var orgResponse = context.Send(
    {
        url: orgUrl,
        method: 'GET',
        headers: {
            Accept: ['*/*'],
            Authorization: ['Bearer ' + accessToken]
        }
    });
var org = JSON.parse(orgResponse.body);

// Проходимся по коллекции организаций, в которых числится ФЛ ЕСИА
for (var element in org.elements) {
	var orgFullName = org['elements][element]['fullName']

    // Создаём или обновляем аккаунт сотрудника оргнизации (для каждой организации - отдельный аккаунт)
    context.SetAccounts([{
        username: profile.snils,
        firstname: profile.firstName,
        lastname: profile.lastName,
        middlename: profile.middleName,
        attributes: {
            "orgFullName": orgFullName
        }
    }]);
}

Приложение 1. Спецификация дополнительных функций

var tokens = context.GetTokens();
var idToken = tokens.IdToken;
var accessToken = tokens.AccessToken;
var sub = tokens.Sub;

var signedMessage = context.SignString(message)

var idVerified = context.VerifyString(message)

context.SetAccounts([{
    username: "userLogin",
	firstname: "FirstName",
	lastname: "LastName",
	middlename: "MiddleName",
	email: "userlogin@mail.it",
	mobile: "8999232"
	attributes: {
		"name1":"value1",
		"name2":"value2"
	},
	groups:["group1","group2"],
	roles: ["role1", "role2"]
}]);

var tokens = context.GetTokens()
var accessToken = tokens.AccessToken
var profileResponse = context.Send({
    url: "https://esia-portal1.test.gosuslugi.ru/rs/prns/" + tokens.Sub,
    method: 'GET',
    headers: {
        Accept: ['*/*'],
        Authorization: ['Bearer ' + accessToken]
    }
});
var profile = JSON.parse(profileResponse.body);

context.SetError("script error message");

Приложение 2. Сопоставление атрибутов учётной записи с атрибутами в скрипте