Справочник

ESIA-Adapter : 9. Справочник


[ Эндпоинты адаптера ] [ Способы аутентификации и выхода ] [ Структура id_token ] [ Шаги конвейера userInfoPipeline ] [ Функции шаблонов ] [ Коды возврата genguids ] [ Сокращения ]

Эндпоинты адаптера

ЭндпоинтНазначение
/oauth2/authorizeзапрос аутентификации
/oauth2/tokenзапрос токена
/oauth2/logoutвыход
/oauth2/userinfoJSON с данными пользователя (для старых клиентов)
/extidp/esiaперенаправление в ЕСИА
/extidp/esia/callbackприём перенаправления от ЕСИА
/extidp/esia/logoutперенаправление в ЕСИА для выхода
/health/live, /health/readyпроверки состояния

Маршруты /extidp/esia, /extidp/esia/callback и /extidp/esia/logout соответствуют значению synonym, равному esia.

Способы аутентификации и выхода

Аутентификация

  • Authorization code с PKCE: code_challenge и code_challenge_method передаются в /oauth2/authorize, code_verifier — в /oauth2/token.
  • Authorization code с client_secret: клиент использует секрет из clients.json.

Выход

  • По sid — завершается сессия адаптера и выполняется перенаправление в ЕСИА для завершения сессии ЕСИА.
  • По id_token_hint — завершается сессия по id_token, перенаправление в ЕСИА не выполняется.

Структура id_token

{
  "iss": "issuer",
  "sub": "internal_user_id",
  "aud": ["client_id"],
  "userinfo": {
    "fn": "firstname",
    "ln": "lastname",
    "mn": "middlename",
    "un": "login",
    "e": "example@email",
    "p": "+79999999999",
    "l": "ru",
    "xid": "external_id",
    "x": { "customAttr1": "attr1 value", "customAttr2": "attr2 value" }
  }
}

sub — внутренний идентификатор пользователя адаптера; описание userinfo — в разделе «Атрибуты пользователя» страницы Конфигурация.

Шаги конвейера userInfoPipeline

tТипДанные в d
0HTTP-запрос (m метод, u адрес, h заголовки)параметры запроса: query для GET, application/x-www-form-urlencoded для остальных
1шаблон Goключ → шаблон
2JavaScript (до 10 с)ключ → скрипт

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

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

ФункцияЧто делает
joinсклеивает строки
fail "текст"прерывает вход с ошибкой
base64, debase64кодирование
timeFormatформатирование времени
emailUsernameчасть email до @
cryptoSign context данные провайдерподпись, возвращает байты
cryptoVerify, cryptoVerifyJWTпроверка подписи / JWT (пусто — успех, иначе ошибка прерывает вход)
cryptoHashSumхеш-сумма в base64

cryptoProvider: {name: cprocsp_cms | cprocsp_raw, details: {...}}. Для cprocsp_cms (API ЕСИА v1): sha1Thumbprint, containerPIN. Для cprocsp_raw (API v2): containerName, containerPIN, hashAlg (GOST3411, GOST3411_2012_256, GOST3411_2012_512).

Коды возврата genguids

0 — успех, 1 — ошибка аргумента, 2 — ошибка инициализации КриптоПро, 3 — ошибка генерации случайных чисел.

Сокращения

ЕСИА, СКЗИ, ЗПС, МДЗ, НСД, ЭП, OIDC, PKCE, IdP, JWT, CMS, CRL — по Руководству администратора, раздел 1.

Обсуждение