Настройка внешнего провайдера ЕСИА

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

Настройка компонентов ЕСИА

Установка и настройка компонентов ЕСИА осуществляется в указанной последовательности:

Перейти на официальный сайт КриптоПРО в раздел загрузки дистрибутивов КриптоПро CSP по ссылке и загрузить сертифицированную версию КриптоПРО CSP.
Распаковать и установить КриптоПРО CSP (совместно с КриптоПро поставляются утилиты, необходимые для генерации сертификатов и создания подписей).
Установка КриптоПРО CSP в ОС семейства Debian (Ubuntu Server, Astra Linux) осуществлять при помощи консоли в следующем порядке:
1. Перейти в каталог со скачанным архивом.
2. Распаковать скачанный архив посредством команды
  sudo tar -xf linux-amd64_deb.tgz
3. Запустить установку КриптоПРО CSP посредством команды
  sudo ./linux-amd64_deb/install.sh
Установка КриптоПРО CSP в ОС Windows осуществлять в следующем порядке:
1. Запустить exe-файл из каталога со скачанным КриптоПРО CSP.
2. Дождаться окончания установки.
3. Перезагрузить компьютер.
Установка КриптоПРО CSP в ОС
Активировать лицензию КриптоПРО CSP.
Активацию лицензии в КриптоПРО CSP в ОС семейства Debian осуществлять в следующем порядке:
1. Перейти в папку с конфигурационным файлом посредством команды:
  cd /opt/cprocsp/sbin/amd64/
2. Ввести серийный номер (при вводе соблюдать регистр символов), например:
  ./cpconfig -license -set 1404B-70808-01QYN-MTZF3-0RWHH
3. Проверить лицензию посредством команды:
  ./cpconfig -license -view
Активацию лицензии в КриптоПРО CSP в ОС семейства Windows осуществлять в следующем порядке:
1. Перейти в окно управления КриптоПРО CSP (Пуск - Все приложения - КриптоПро - КриптоПро CSP).
2. Во вкладке "Общие" нажать кнопку "Ввод лицензии".
3. Ввести информацию о лицензии:
  1. Пользователь - ФИО пользователя;
  2. Организация - Наименование организации-держателя лицензии;
  3. Серийный номер - Серийный ключ лицензии.
Сгенерировать и установить сертификат (после активации сертификат действителен в течение 3 месяцев).
Установку сертификата в КриптоПРО CSP в ОС семейства Debian осуществлять в следующем порядке:
1. Сгенерировать сертификат посредством команды:
  /opt/cprocsp/bin/amd64/cryptcp -createcert -provtype 80 -hashalg 1.2.643.7.1.1.2.2 -rdn 'CN=esiacert' -exprt -cont '\\.\HDIMAGE\esiacert'
2. Если имеются просроченные сертификаты, удалить их при помощи команды:
  /opt/cprocsp/bin/amd64/certmgr -delete -cert
3. При необходимости просмотреть выпущенные сертификаты посредством команды:
  /opt/cprocsp/bin/amd64/certmgr -list -store uMy
4. В списке сертификатов найти сертификат, сгенерированный в пункте а (графа Subject со значением CN=esiacert) и скопировать значение параметра SHA1 Hash. Для этого выполнить следующие команды:
  openssl x509 -in /path/to/cert -inform der -text | grep 'Signature Algorithm' -m 1
  /opt/cprocsp/bin/amd64/cpverify /path/to/cert -mk -alg GR3411_2012_256 -inverted_halfbytes 0
5. Экспортировать сертификат в файл, чтобы затем загрузить его на технический портал ЕСИА (параметр clientCertHash шага "Основные настройки" провайдера идентификации). Для это выполнить команду (ставить в нее значение хэша SHA1 Hash, скопированное в пункте d):
  /opt/cprocsp/bin/amd64/certmgr -export -dest /opt/idp/esiacert.cer -thumbprint 667c16c1207295854aacdd429c503007baa1e11d
6. Установить сертификат в хранилище uMy, где u = User, My - имя хранилища:
  1. Найти пользователя, от имени которого работает Avanpost FAM:
    
    nano /etc/systemd/system/idp.service
  2. Перейти на данного пользователя и выполнить команду:
    
    sudo so "Имя_пользователя" /opt/cprocsp/bin/amd64/cetmgr -list -store uMy
  3. Если доверенный сертификат не найден, установить его, выполнив команду:
  4. cd "путь до доверенного сертификата" /opt/cprocsp/bin/amd64/certmgr -install -store -file certnew.cer
Активацию лицензии в КриптоПРО CSP в ОС Windows через раздел "Сертификаты в контейнере закрытого ключа" выполнить в следующем порядке:
1. Перейти в окно управления КриптоПРО CSP (Пуск - Все приложения - КриптоПро - КриптоПро CSP) во вкладку "Сервис".
2. Нажать кнопку “Просмотреть сертификаты в контейнере” в разделе "Сертификаты в контейнере закрытого ключа" и в открывшемся окне нажать кнопку "Обзор".
3. В открывшемся окне выбрать контейнер, нажать "ОК", а затем - "Далее".
4. В открывшемся окне нажмите на кнопку “Установить” (если кнопка “Установить” отсутствует, в окне “Сертификат для просмотра” нажать кнопку “Свойства" - "Установить сертификат").
5. В окне “Мастер импорта сертификатов” нажать “Далее”.
6. Рекомендуется выбрать "Автоматически выбрать хранилище на основе типа сертификата" и нажать "Далее" (Сертификат будет автоматически установлен в хранилище “Личные”).
7. В следующем окне нажать “Далее” и “Готово”, дождавшись сообщения об успешной установке сертификата.
Активацию лицензии в КриптоПРО CSP в ОС Windows через раздел "Личный сертификат" выполнить в следующем порядке:
1. Перейти в окно управления КриптоПРО CSP (Пуск - Все приложения - КриптоПро - КриптоПро CSP) во вкладку "Сервис".
2. В окне “Мастер установки личного сертификата” нажать “Далее” и затем выбрать файл сертификата с расширением .cer, нажав “Обзор” и указав путь.
3. В окне, отображающем данные о сертификате, нажать “Далее”.
4. Ввести или указать контейнер закрытого ключа, соответствующий выбранному сертификату. Для этого нажать “Обзор” и указать путь.
5. Выбрать хранилище, куда будет установлен сертификат, в окне “Выбор хранилища сертификатов” нажав кнопку “Обзор” и указав путь.
6. В качестве хранилища выбрать Личные, нажать "ОК" и дождаться окончания установки.
Загрузить сертификат в целевую ИС на техническом портале и выполнить настройки.

Настройка на стороне Avanpost FAM

Установка и настройка внешнего провайдера ЕСИА на стороне Avanpost FAM Server осуществляется следующим образом:

В административной консоли Avanpost FAM Server в разделе "Настройки внешних провайдеров идентификации (IdP)" режима "Сервис" нажать кнопку "Добавить".

На шаге "Основные настройки" задать значения параметров согласно таблице (более подробно о значениях параметров описано в Шаг 1. Основные настройки) и нажать "Далее".

Параметр	Значение
Тип	`ЕСИА`
Наименование	Задать произвольное наименование.
ЕСИА детали
baseUrl	Адрес, на который пользователь будет перенаправляться при переходе из личного кабинета.
clientCertHash	Параметр, содержащий хэш сертификата (fingerprint сертификата) системы-клиента в hex–формате.
clientID	`NSUD01`
cryptoProvider	JSON-токен c параметрами `sha1Thumbprint` (хэш-функция подписываемого контейнера), `containerPIN` (PIN-код подписываемого контейнера), `certPath` (путь к сертификату ЕСИА)(например, `{"details":{"certPath":"/opt/idp/TESIAGOST2012new.cer","containerPIN":"12345","sha1Thumbprint":"e075c6fc741528b9c0260037ffbec19fb651cff1"},"name":"cprocsp_cms"}`).
scope	Области доступа согласно требованиям Методических рекомендаций по использованию ЕСИА (например, `openid fullname email snils mobile`). Указываются через пробел.
scopeOrg	Области доступа к данным организации (при необходимости) согласно требованиям Методических рекомендаций по использованию ЕСИА (например, `shortname ogrn inn oktmo`). Указываются через пробел.

На шаге "Настройки перенаправления" задать значения параметров согласно таблице (более подробно о значениях параметров описано в Шаг 2. Настройки перенаправления) и нажать "Далее".

Параметр	Значение
URI авторизации	Задать значение `{{ .extidp_details.baseUrl }}/aas/oauth2/ac` для автоматической подстановки значения baseUrl с прошлого шага.
Метод перенаправления	Выбрать `Redirect` (рекомендуется).
Параметры перенаправления
access_type	`offline`
client_certificate_hash	Задать `{{ .extidp_details.clientCertHash }}` для автоматической подстановки значения clientCertHash с прошлого шага.
client_id	Задать `{{ .extidp_details.clientID }}` для автоматической подстановки значения clientID с прошлого шага.
client_secret	{{ $ts := timeFormat "2006.01.02 15:04:05 Z0700" .process_started }}{{ $clientSecretRaw := join .extidp_details.scope $ts .extidp_details.clientID .extidp_request.ID }}{{ cryptoSign .context $clientSecretRaw .extidp_details.cryptoProvider \| base64 }}
redirect_uri	Задать `{{ .extidp_request.CallbackURI }}` для автоматической подстановки значения CallbackURI на полученное от внешнего IdP (значение параметра должно быть предварительно указано в параметрах внешней ИС в ЕСИА).
response_type	`code`
scope	Задать `{{ .extidp_details.scope }}` для автоматической подстановки значения scope с прошлого шага.
scope_org	Задать `{{ .extidp_details.scopeOrg }}` для автоматической подстановки значения scopeOrg с прошлого шага.
state	`{{ .extidp_request.ID }}`
timestamp	`{{ timeFormat "2006.01.02 15:04:05 Z0700" .process_started }}`

На шаге "Настройки callback" задать значения раздела "Шаги для получения информации о пользователе" согласно таблице ниже (более подробно о значениях параметров описано в Шаг 3. Настройки callback) и нажать "Далее".

Шаг	Тип действия	Атрибут результата	Метод	URL	Данные	Заголовки	Назначение
1	HTTP Запрос	token	POST	`{{ .extidp_details.baseUrl }}/aas/oauth2/te`	Имя: `client_certificate_hash`; Значение: `{{ .extidp_details.clientCertHash }}`; Имя: `client_id`; Значение: `{{.extidp_details.clientID}}`; Имя: `client_secret`; Значение: `{{ $ts := timeFormat "2006.01.02 15:04:05 Z0700" .process_started }}{{ $clientSecretRaw := join .extidp_details.scope $ts .extidp_details.clientID .extidp_request.ID }}{{ cryptoSign .context $clientSecretRaw .extidp_details.cryptoProvider \| base64 }}`; Имя: `code`; Значение: `{{ .code }}`; Имя: `grant_type`; Значение: `authorization_code`; Имя: `redirect_uri`; Значение: `{{ .extidp_request.CallbackURI }}`; Имя: `scope`; Значение: `{{.extidp_details.scope}}` Имя: `state`; Значение: `{{.extidp_request.ID}}`; Имя: `timestamp`; Значение: `{{ timeFormat "2006.01.02 15:04:05 Z0700" .process_started }}`; Имя: `token_type`; Значение: `Bearer`.	-	Запрос и получение маркера доступа от ЕСИА. В теле запроса Avanpost FAM направляет внешнему провайдеру информацию, содержащуюся в столбце "Данные", и в случае успеха получает Access token.
2	Маппинг	-	-	-	Имя: `verify_id_token`; Значение: `{{ cryptoVerifyJWT .context .token.id_token .extidp_details.cryptoProvider }}`	-	Проверка подписи полученного маркера доступа при помощи криптопровайдера (криптопровайдер при этом используется указанный в разделе "Детали" на шаге "Основные настройки").
3	Скрипт	-	-	-	Имя: `id_token_claims`; Значение: `jwt(token.id_token)`	-	Парсинг claim'ов полученного токена с записью их в переменную `id_token_claims.`
4	Маппинг	-	-	-	Имя: `is_trusted`; Значение: `{{ with index .id_token_claims "urn:esia:sbj" "urn:esia:sbj:is_tru" }}{{ if not . }}{{ fail "user is not trusted" }}{{ end }}{{ end }}`	-	Проверка признака подтвержденности УЗ в ЕСИА.
5	HTTP Запрос	person	GET	`{{ .extidp_details.baseUrl }}/rs/prns/{{ printf "%.0f" .id_token_claims.sub }}`	-	Имя: `Authorization` Значение: `Bearer {{ .token.access_token }}`	Запрос у ЕСИА значения person (данные о сотруднике как физическом лице) пользователя с передачей в заголовке API-запроса к ЕСИА полученного токена.
6	HTTP Запрос	contacts	GET	`{{ .extidp_details.baseUrl }}/rs/prns/{{ printf "%.0f" .id_token_claims.sub }}/ctts`	Имя: `embed`; Значение: `(elements)`	Имя: `Authorization` Значение: `Bearer {{ .token.access_token }}`	Запрос у ЕСИА значения contacts (контактные данные) пользователя с передачей в заголовке API-запроса к ЕСИА полученного токена.
7	Скрипт	-	-	-	Имя: `main_email`; Значение: `email = ""; for (i = 0; i < contacts.elements.length; i++) {if (contacts.elements[i].type === "EML" && contacts.elements[i].vrfStu === "VERIFIED") {email = contacts.elements[i].value}} email`; Имя: `main_phone`; Значение: `phone = ""; for (i = 0; i < contacts.elements.length; i++) {if (contacts.elements[i].type === "MBT" && contacts.elements[i].vrfStu === "VERIFIED") {phone = contacts.elements[i].value}} phone`;	-	Скрипт, учитывающий случаи, когда у пользователя, загружаемого с ЕСИА, имеется несколько привязанных номеров телефона или email. Скрипт позволяет выбрать для использования в Avanpost FAM первый из них.

На шаге "Настройки callback" задать прочие значения значения согласно таблице ниже.

Параметр	Значение
Маппинг атрибутов	Имя	Значение
	Имя	{{ .person.firstName }}
	Фамилия	{{ .person.lastName }}
	Отчество	{{ .person.middleName }}
	Имя пользователя	Заполнять необязательно. При необходимости воспользоваться Методическими рекомендациями по использованию ЕСИА.
	Email	{{ .main_email }}
	Телефон	{{ .main_phone }}
	Язык	Заполнять необязательно. При необходимости воспользоваться Методическими рекомендациями по использованию ЕСИА.
	Внешний ID	{{ printf "%.0f" .id_token_claims.sub }}
	ID запроса	state
	ID Токен	Заполнять необязательно. При необходимости воспользоваться Методическими рекомендациями по использованию ЕСИА.
	Итератор	Заполнять необязательно. При необходимости воспользоваться Методическими рекомендациями по использованию ЕСИА.
Маппинг дополнительных атрибутов	Маппинг дополнительных атрибутов осуществляется по аналогии с маппингом основных атрибутов в случае если требуется сопоставить и связать атрибуты, полученные из внешнего IdP и дополнительные атрибуты на стороне Avanpost FAM. Выбирая значение атрибута на стороне внешнего IdP следует использовать Методические рекомендации по использованию ЕСИА.
Атрибут привязки	Выбрать атрибут привязки, по которому пользователь на стороне Avanpost FAM ассоциируется с пользователем на стороне внешнего IdP. По умолчанию выбран атрибут `Имя пользователя`.

На шаге "Завершение" задать значения параметров согласно таблицам ниже (более подробно о значениях параметров описано в Шаг 4. Завершение) и нажать "Сохранить".

Параметр	Значение
Настройки интеграции	Значения переключателей настраиваются в зависимости от потребностей конкретной эксплуатирующей организации. Доступна настройка следующих параметров: Создание пользователей при включенном переключателе () появление нового пользователя на стороне внешнего IdP приводит к автоматическому созданию пользователя на стороне Avanpost FAM (решение о создании принимается в результате поиска по значению атрибута привязки, выбранному в графе "Связывать по атрибуту" на Шаге 3 данной инструкции: если на стороне внешнего IdP найден пользователь с некоторым значением атрибута привязки, отсутствующим в Avanpost FAM, данный пользователь автоматически создается в Avanpost FAM); при включенном переключателе () автоматическое создание нового пользователя в Avanpost FAM, появившегося на стороне внешнего IdP, не осуществляется; Обновление пользователей при включенном переключателе () обновление связанных пользовательских атрибутов (указаны в графе Маппинг атрибутов на Шаге 3 данной инструкции) на стороне IdP приводит к автоматическому обновлению данных атрибутов на стороне Avanpost FAM; при включенном переключателе () автоматическое обновление пользовательских атрибутов на стороне Avanpost FAM не осуществляется; Подтверждение информации пользователем при включенном переключателе () после создания нового пользователя в момент первичной авторизации пользователю показываются значения его атрибутов для подтверждения; при включенном переключателе () новому пользователю не показываются его атрибуты для подтверждения при первой авторизации; Обогащение информации пользователем при включенном переключателе () после создания нового пользователя в момент первичной авторизации отображаемые значения атрибутов доступны пользователю для редактирования; при включенном переключателе () новому пользователю не доступно редактирование атрибутов при первичной авторизации; Подтверждение паролем при включенном переключателе () выполняется связывание пользователей Avanpost FAM и внешнего IdP посредством дополнительной аутентификации (например, если при авторизации посредством внешнего IdP в Avanpost FAM не находится пользователь, связанный с этим IdP, Avanpost FAM предлагает ввести логин-пароль и на основании введенных данных связывает УЗ в Avanpost FAM и во внешнем IdP) при включенном переключателе () связывание пользователей Avanpost FAM и внешнего IdP посредством дополнительной аутентификации недоступно; Множественная учетная запись при включенном переключателе () допускается использование нескольких учетных записей: пользователю будет предложен выбор учетной записи из списка найденных в Avanpost FAM/создаваемых при помощи внешнего IdP; при включенном переключателе () использование нескольких учетных записей недоступно пользователю. Параметр "Множественная учетная запись" рекомендуется использовать для IdP типа ЕСИА. В случае, когда из ЕСИА загружен пользователь, одновременно состоящий в нескольких разных организациях, в Avanpost FAM создаются учетные записи пользователя отдельно для каждой организации. При авторизации в Avanpost FAM у пользователя будет возможность выбрать в какую из учетных записей входить.
Группа по умолчанию	Ввести наименование группы, в которую по умолчанию будут добавляться новые пользователи.
Активный	Установить флаг чекбокс, чтобы запустить настроенный IdP без дополнительной интеграции.

Настройка внешнего провайдера ЕСИА

Настройка компонентов ЕСИА

Настройка на стороне Avanpost FAM

Обсуждение