ESIA-Adapter : 4. Конфигурация

Настройки задаются переменными окружения и двумя JSON-файлами: списком OIDC-клиентов и конфигурацией внешнего провайдера (ЕСИА). Ключ подписи токенов (RSA, PEM) задаётся переменной KEY.

Обязательные переменные

Пути к файлам конфигурации задаются переменными окружения службы:

EXTIDP=/opt/esia-idp/config/extidp.json
CLIENTS=/opt/esia-idp/config/clients.json

Без этих файлов служба не запускается. По умолчанию используются extidp.json и clients.json в рабочем каталоге службы.

Переменные окружения

Пример:

{
  "DEBUG": "false", "BASE_URL": "https://esia-adapter.corp:4010",
  "HOST": "0.0.0.0", "PORT": 4010, "KEY": "key.pem",
  "CLIENTS": "/opt/esia-idp/config/clients.json", "EXTIDP": "/opt/esia-idp/config/extidp.json",
  "EXTIDP_REQUEST_TTL": "1h", "USERINFO_TTL": "1h",
  "SESSION_COOKIE_NAME": "sid", "SESSION_COOKIE_LIFETIME": 3600,
  "SESSION_COOKIE_SECURE": "true", "SESSION_EXPIRED": 3600,
  "CPROCSP_BIN_DIR": "/opt/cprocsp/bin/amd64"
}

clients.json — доверенные OIDC-клиенты

[
  { "ID": "pkce-only-client", "Domain": "localhost:9094" },
  { "ID": "client-with-secret", "Secret": "<секрет>", "Domain": "example.com" }
]

• ID — идентификатор клиента.
• Secret — секрет клиента; клиент без Secret работает только с PKCE.
• Domain — хост для проверки redirect_uri клиента.

Конфигурация внешнего провайдера (ЕСИА)

Готовый JSON можно взять в административной консоли Avanpost FAM 1.16 или, для более ранних версий, из DevTools браузера при просмотре настроек внешнего IdP. Значение synonym должно быть равно esia. Три готовых шаблона в поставке: extidp.esia.v1.example.json (API ЕСИА v1), extidp.esia.v2.example.json (v2) и extidp.esia.v2.pkce.example.json (v2 с PKCE).

Основные поля провайдера: id, type (всегда esia), name, synonym (всегда esia), authorizeUri, redirectMethod (0 — редирект 307, 1 — HTML-форма), logoutUri, logoutForm, typeDetails, redirectForm, userInfoPipeline, attrMapping, isActive.

• typeDetails — строка с JSON: baseUrl ЕСИА, clientID (мнемоника ИС), cryptoProvider (cprocsp_cms для API v1, cprocsp_raw для API v2), scope, scopeOrg. Значения доступны в шаблонах как .extidp_details.<поле>.
• redirectForm — параметры, отправляемые в ЕСИА при запросе аутентификации.
• userInfoPipeline — шаги получения данных о пользователе. Тип шага t: 0 — HTTP-запрос, 1 — шаблон Go, 2 — JavaScript (лимит времени 10 с). r — имя переменной результата, d — данные, m/u/h — метод, адрес, заголовки.
• attrMapping — отображение данных, полученных от ЕСИА, в атрибуты пользователя, которые адаптер передаёт приложению. Подробнее — в разделе «Атрибуты пользователя (attrMapping)» ниже.

Атрибуты пользователя (attrMapping)

В attrMapping для каждого атрибута задаётся шаблон Go. Адаптер выполняет шаблон после завершения шагов userInfoPipeline; в шаблоне доступны все переменные, сохранённые шагами (поле r), например {{.person.firstName}} или {{.main_email}}. Результат — строка, которая записывается в атрибут. Пустой шаблон оставляет атрибут пустым, пустые атрибуты в ответ не включаются. Ошибка выполнения шаблона прерывает вход.

Пример:

"attrMapping": {
  "fn": "{{.person.firstName}}",
  "ln": "{{.person.lastName}}",
  "mn": "{{.person.middleName}}",
  "e": "{{.main_email}}",
  "p": "{{.main_phone}}",
  "xid": "{{printf \"%.0f\" .id_token_claims.sub}}",
  "rid": "state",
  "x": { "snils": "{{.snils}}", "inn": "{{.inn}}" }
}

Куда попадают атрибуты. Значения (кроме rid) собираются в объект userinfo, который адаптер:

• помещает в выдаваемый приложению id_token в claim userinfo (fn, ln, mn, un, e, p, l, xid, x);
• отдаёт приложению в ответе /oauth2/userinfo.

Структура userinfo

Все поля необязательные и строковые; незаполненные поля не передаются.

Пример claim userinfo в id_token и ответа /oauth2/userinfo:

{
  "fn": "Иван",
  "ln": "Иванов",
  "mn": "Иванович",
  "e": "ivanov@example.com",
  "p": "+7(900)0000000",
  "xid": "1000123456",
  "x": { "snils": "123-456-789 00", "inn": "770000000000" }
}

Данные хранятся в памяти адаптера в течение USERINFO_TTL. Идентификатор пользователя в claim sub — служебный идентификатор записи адаптера, он не равен идентификатору в ЕСИА; для связи с учётной записью применяется xid.

Функции шаблонов

join, fail (прервать вход с ошибкой), base64, debase64, timeFormat, emailUsername, cryptoSign, cryptoVerify, cryptoVerifyJWT, cryptoHashSum. В JavaScript-шагах доступна jwt(token).

Эндпоинты

См. Справочник.