Руководство по интеграции eID API: паттерны, код и безопасность

Последняя проверка: 5 октября 2026 · Не является юридической консультацией

Это руководство с упором на код предназначено для инженеров, которые подключают национальные eID к онбордингу.

Как работает eID API: пять шаблонов взаимодействия

Ваша система выступает доверяющей стороной (relying party, RP). Она никогда не видит само средство идентификации, только подписанный ответ о человеке.

Некоторые схемы работают через публичный шлюз: эстонский TARA представляет собой шлюз с потоком authorization code, через который подключаются ID-карта, Smart-ID, Mobile-ID и eID других стран ЕС.^[7] Какую модель использует каждая схема, см. в материале Схемы eID по странам.

Что разрабатываете вы и что берет на себя провайдер

Сначала доступ, потом код. В Дании каждый поставщик услуг обязан подключаться через сертифицированного брокера MitID.^[12] В Швеции BankID приобретают у банка или реселлера и заказывают сертификат доверяющей стороны.^[15] В Германии можно развернуть собственный eID-сервер, использовать размещенный у провайдера eID-сервис со своим сертификатом или работать через сервис идентификации и не иметь собственного сертификата.^[13] Для EUDI Wallet доверяющая сторона должна зарегистрироваться в государстве-члене, в котором она учреждена.^[1]

Сертифицированные брокеры есть для большинства северных и балтийских схем. При большом объеме по одной схеме подключайтесь напрямую; если пользователи приходят из нескольких стран, используйте один API.

Поток с перенаправлением, шаг за шагом

Это поток OIDC с кодом авторизации. Ваш бэкенд перенаправляет браузер со случайными state и nonce, затем обменивает полученный код на ID-токен и проверяет его.

Вход с перенаправлением. Брокеры и шлюзы добавляют промежуточные переходы на шаге 2, но не новые шаги для вас.

Важнее всего проверка после шага 5. Согласно документации Digdir по ID-porten, клиент «ОБЯЗАН проверить, что уровень безопасности (acr) достаточно высок».^[5] Понимайте acr как уровень доверия (LoA), который подтверждает схема, и отклоняйте всё, что ниже требований вашей политики.

Поток с push-уведомлением в приложении и кодом для сверки

При Smart-ID и Mobile-ID пользователь не покидает вашу страницу. Пользователь вводит личный идентификационный код (Mobile-ID также запрашивает номер телефона), ваша страница показывает короткий код, и тот же код появляется в приложении. Пользователь подтверждает операцию PIN-кодом на телефоне, только если коды совпадают.^[20] Smart-ID также может показать три кода и попросить пользователя выбрать правильный.^[10]

BankID Sweden устроен так же, только вместо ввода кода используется QR. Пользователь открывает приложение на том же устройстве с помощью autostart-токена или сканирует анимированный QR-код на другом устройстве. Ваш бэкенд опрашивает /collect, пока заказ не завершится. Завершенный заказ содержит персональный номер, полное имя, имя и фамилию, а также данные об устройстве, подпись и необязательные поля оценки риска.^[8] Smart-ID+ переводит Smart-ID на эту модель: динамический QR на десктопе, переход из приложения в приложение на мобильных устройствах. Пользователям больше не нужно вводить персональный код на сайте.^[11]

Вход через Smart-ID или Mobile-ID в том порядке, в котором его видит пользователь: персональный код, контрольный код на вашей странице, тот же код в приложении, затем PIN.^[20] В варианте BankID с QR шаг 1 исчезает, а на шаге 2 показывается QR-код.

Карта и NFC, а также EUDI Wallet через OpenID4VP

При использовании немецкой ID-карты с функцией eID пользователь прикладывает карту к телефону с NFC в приложении AusweisApp. По закону до ввода PIN приложение должно показать наименование и адрес поставщика услуги и запрашиваемые категории данных. Передаются только эти категории.^[14]

По данным OpenID Foundation, OpenID4VP 1.0 является финальной спецификацией.^[16] Architecture and Reference Framework (ARF) предусматривает следующие варианты удаленного предъявления: OpenID4VP через редиректы и пользовательские URI-схемы, например openid4vp://, OpenID4VP через W3C Digital Credentials API или ISO/IEC 18013-7 через этот API.^[2][17] Прежде чем что-либо передать, кошелек проверяет подлинность вашего сертификата доступа, убеждается, что вы не запрашиваете больше атрибутов, чем зарегистрировали, и дает пользователю подтвердить каждый атрибут.^[2] Портрет становится обязательным в данных идентификации личности (PID) только с 11 августа 2028, за исключением случаев, когда пользователь явно от него отказывается.^[18]

1. 23 июля 2026ARF v3.0.0Текущая версия рамочной архитектуры кошелька.
2. 24 декабря 2026Срок для кошельковКаждое государство-член предоставляет как минимум один кошелек.
3. 24 декабря 2027Обязательный приемЧастные доверяющие стороны, которые по закону или договору обязаны применять строгую аутентификацию пользователя, принимают кошелек по запросу пользователя. Микро- и малые предприятия освобождены.
4. 11 августа 2028ПортретПортрет в PID становится обязательным, если пользователь от него не отказался.

Даты по EUDI Wallet, которые определяют дорожную карту eID API.^[1][2][18]

В руководстве по EUDI Wallet описаны регистрация доверяющей стороны и готовность по странам.

Ошибки, резервные сценарии и повторные попытки

Вход заканчивается одним из исходов: завершен, отменен, истекло время ожидания или сбой. Последние три обрабатывайте одинаково и для каждой страны решайте, что происходит дальше.

Никогда не повторяйте отменённый вход автоматически. Сделайте обработку callback идемпотентной, чтобы обновление страницы или повторное событие не могли открыть два аккаунта. Сохраните путь для людей без eID. Обычно это документ, удостоверяющий личность, с чтением чипа по NFC, проверкой liveness и сравнением лица. Этот путь описан в статье Проверка eID по NFC и безопасность чипа.

Чек-лист безопасности для интеграции eID API

• Генерируйте новые state и nonce для каждого входа и отклоняйте callback, который им не соответствует.
• Проверяйте подпись каждого токена или результата до чтения любого атрибута.
• Проверяйте уровень доверия в результате, а не только в запросе.^[5]
• Требуйте уровень «существенный» или «высокий», если к вам применяется путь eID по AMLR.^[3]
• Никогда не принимайте PIN-код eID на своей странице. Его вводят в приложении схемы.^[20]
• Для входа с другого устройства используйте QR-код или запуск из приложения в приложение, а не ввод кодов вручную.^[11]
• Запрашивайте только те атрибуты, которые вы зарегистрировали и которые вам нужны.^[1]
• Проверяйте подписи и временные метки webhook, прежде чем доверять результату.

Правовая основа: Регламент о противодействии отмыванию денег (AMLR), который применяется с 10 июля 2027 года. Статья 22(6)(b) допускает «средства электронной идентификации, отвечающие требованиям Регламента (ЕС) № 910/2014 в отношении уровней доверия „существенный“ или „высокий“».^[3] Не все схемы нотифицированы: MitID входит в список нотифицированных схем ЕС, Smart-ID нет.^[4]

Как Didit помогает с интеграцией eID API

Didit объединяет пять действующих eID в одном API сессий (MitID, BankID Sweden, Finnish Trust Network, Smart-ID и Mobile-ID, в семи странах), с путём проверки по документу в том же рабочем процессе. Другие схемы есть в дорожной карте Didit, а приём EUDI Wallet скоро появится. Didit никогда не запрашивает PIN-код. Подробнее на странице цифровых ID-кошельков и в документации по кошелькам.^[19]

Включите действующие eID по странам

В консоли: Workflows, шаг ID Verification, Countries, «Wallets accepted». Через API функция ID Verification (OCR) принимает объект methods с ключами в виде кодов стран ISO 3166-1 alpha-3, который передаётся в POST /v3/workflows/. Документированный фрагмент для Дании:^[21]

{ "feature": "OCR", "config": { "methods": { "DNK": { "document": { "enabled": true }, "wallet": { "enabled": true, "providers": ["mitid"], "on_failure": "fallback_to_document" } } } } }

И для Эстонии, с приёмом обоих eID на базе телефона:^[20]

{ "EST": { "document": { "enabled": true }, "wallet": { "enabled": true, "providers": ["smart_id", "mobile_id"], "on_failure": "fallback_to_document" } } }

providers является списком разрешённых провайдеров, а не рейтингом. on_failure принимает значение fallback_to_document или decline. Если кошелёк недоступен в вашей среде, сохранение отклоняется целиком, поэтому сначала изучите каталог.^[21]

Создайте сессию и получите результат

POST /v3/session/ с вашим workflow_id (и, при необходимости, vendor_data и callback) возвращает session_id, url и session_token. Откройте URL или используйте SDK.^[24] Результат приходит через вебхук или GET /v3/session/{id}/decision/ с verification_method: "wallet", assurance: "cryptographic" и объектом wallet_verification.^[19]

Если уровень ниже запрошенного, вход не проходит. Оплачиваются только завершённые входы.^[19] Цены: MitID, Finnish Trust Network $0.25; BankID Sweden, Smart-ID, Mobile-ID $0.20.

Вебхуки и песочница

Проверяйте X-Signature-V2 с помощью секрета получателя, отклоняйте X-Timestamp старше 300 секунд и обеспечивайте идемпотентность по event_id. Неудачная доставка повторяется до двух раз.^[22] В песочнице приложение может включить все кошельки, одобряет сессии без реального входа и предлагает wallet_cancelled, wallet_timeout и wallet_provider_error для проверки вашего резервного сценария.^[23]

Часто задаваемые вопросы

Источники

1. Регламент (ЕС) 2024/1183 (eIDAS 2), EUR-Lex, Официальный журнал от 30 апреля 2024, статьи 5a, 5b и 5f.
2. Architecture and Reference Framework v3.0.0, проект Европейской комиссии EUDI Wallet, выпуск от 23 июля 2026, разделы 4.4.3, 5.7.1 и 6.6.3.
3. Регламент (ЕС) 2024/1624 (AMLR), EUR-Lex, статья 22(6).
4. Обзор предварительно уведомленных и уведомленных схем eID в рамках eIDAS, Европейская комиссия, просмотрено 5 октября 2026.
5. ID-токен ID-porten, Агентство по цифровизации Норвегии (Digdir).
6. Anbindung mit OpenID Connect, документация для разработчиков ID Austria.
7. Техническая спецификация TARA, Департамент государственных информационных систем Эстонии (RIA).
8. Auth and sign: collect, документация для разработчиков BankID.
9. QR-koden gjorde susen: BankID-bedrägerierna ned med 90 procent, Computer Sweden, 3 июля 2019 (вторичный источник).
10. Почему я иногда вижу один код подтверждения, а иногда три, Smart-ID.
11. Как новый Smart-ID защищает меня от мошенничества, Smart-ID.
12. Брокеры MitID, Агентство цифрового государственного управления Дании.
13. Стать поставщиком услуг, AusweisApp, федеральное правительство Германии.
14. Параграф 18 Закона о паспортах и удостоверениях личности (PAuswG), Gesetze im Internet.
15. Подключите свою компанию к BankID, BankID.
16. Утверждена финальная спецификация OpenID for Verifiable Presentations 1.0, OpenID Foundation.
17. Digital Credentials, W3C.
18. Имплементационный регламент Комиссии (ЕС) 2026/1731, EUR-Lex, портрет в PID с 11 августа 2028.
19. Кошельки цифровой идентификации, документация Didit.
20. Интеграция Smart-ID и Mobile-ID, документация Didit.
21. Настройки функций рабочих процессов, документация Didit.
22. Вебхуки, документация Didit.
23. Песочница и тестовые данные, документация Didit.
24. Быстрый старт, документация Didit.

Все национальные eID, их уровень и статус смотрите на странице верификации eID.