Как подключить вход через Сбер ID на свой сайт

Многие пользователи в РФ привыкли входить на сайты через Сбер ID. Это удобно: не нужно придумывать пароль, а телефон и имя подтягиваются из банка. Для владельца приложения это ещё и плюс в доверии — человек видит знакомый логотип и понимает, что ему не придётся запоминать очередной пароль. Мы недавно подключили Сбер ID к своему проекту. Ниже расскажем, как это устроено, что нужно получить заранее и на каких моментах можно споткнуться.

Что нужно до старта

Прежде чем ты увидишь первую рабочую кнопку «Войти через Сбер ID», придётся собрать несколько вещей. Без них заявку на портале просто не отправить.

ЭЦП Сбера, токен и ЭДО

Нужны три разных инструмента, и их легко перепутать:

• ЭЦП Сбера — электронная подпись. Она нужна, чтобы подписать заявление на подключение.
• Токен — отдельный ключ для входа в личный кабинет Сбер ID. Это не ЭЦП, хотя тоже выглядит как небольшое устройство или программный ключ.
• ЭДО СберБизнес — электронный документооборот. Заявление отправляется именно через него, а не по почте и не через чат поддержки.

У нас ушло заметное время, чтобы разобраться, что для чего. Если ты уже пользуешься СберБизнесом и у тебя есть подпись Сбера — это серьёзно ускорит процесс. Если нет — заложи несколько дней на оформление.

Что выдают после одобрения

Когда заявление подписано и отправлено, Сбер проверяет анкету. После одобрения ты получишь:

• Client ID — публичный идентификатор приложения.
• Client Secret — секрет для обмена кода на токены.
• Клиентский сертификат в формате .p12 с паролем. Он понадобится для mTLS, об этом ниже.

Храни Client Secret и сертификат как пароли. Никогда не вставляй их в код, который попадает в публичный репозиторий. Лучшее место — переменные окружения. Подробнее о безопасном хранении ключей читай в статье «Хранение секретов и токенов».

Как устроен вход: OIDC-флоу

Сбер ID работает по протоколу OIDC, OpenID Connect. Это стандартный способ, при котором сайт перенаправляет пользователя на страницу авторизации Сбера, а Сбер возвращает код, по которому сайт уже сам получает данные человека.

В нашем случае флоу выглядит так:

1. Пользователь нажимает кнопку «Войти через Сбер ID».
2. Сайт перенаправляет его на id.sber.ru/CSAFront/oidc/authorize.do с параметрами: response_type=code, client_type=PRIVATE, client_id, scope=openid name email mobile, state, nonce и redirect_uri.
3. Пользователь подтверждает вход в Сбере.
4. Сбер возвращает пользователя обратно на redirect_uri с кодом.
5. Сервер сайта обменивает этот код на токены.
6. По токену сервер запрашивает данные пользователя: имя, телефон, email, если есть.

Параметр redirect_uri должен совпадать с указанным в анкете символ в символ. Даже лишний слэш, www или другой протокол — и Сбер отклонит запрос. Заранее реши, какой именно адрес пропишешь в анкете, и используй ровно его.

Главные грабли и как их обойти

Техническая часть Сбер ID отличается от привычного OAuth вроде Яндекс ID. Вот на чём мы спотыкались лично.

mTLS вместо обычного запроса

Эндпоинт для обмена кода на токены — oauth.sber.ru/ru/prod/tokens/v2/oidc. Он требует не только Client Secret, но и клиентский сертификат .p12 в формате mTLS, то есть взаимного TLS. Обычный fetch в Node.js не умеет работать с .p12, поэтому пришлось использовать низкоуровневый node:https с опцией pfx.

Плюс к этому обязательный заголовок RqUID — 32 шестнадцатеричных символа. Без него запрос тоже не пройдёт.

Сертификаты Минцифры: «у меня локально работает»

Самая неприятная ловушка. oauth.sber.ru предъявляет TLS-сертификат, подписанный корнями Минцифры — Russian Trusted Root CA и Russian Trusted Sub CA. На домашнем компьютере или ноутбуке эти корни обычно уже есть в системе, и запрос проходит. А на чистом Linux-сервере их нет — и рукопожатие TLS рвётся с ошибкой self-signed certificate in certificate chain.

Мы столкнулись именно с этим: локально всё работало, а на сервере падало. Решение — скачать публичные корни Минцифры с gu-st.ru и явно добавить их в доверенные для этих запросов. Не отключай проверку сертификата полностью — это создаст уязвимость. Добавь именно официальные корни.

Userinfo со своими заголовками

Эндпоинт для получения данных — oauth.sber.ru/ru/prod/sberbankid/v2.1/userinfo. Здесь два важных нюанса:

• Адрес пишется строчными буквами. userInfo с заглавной буквы вернёт 404.
• Заголовки не стандартный RqUID, а x-ibm-client-id (твой Client ID) и x-introspect-rquid.

Мы потратили время, пока поняли, что регистр в пути и состав заголовков отличаются от token-эндпоинта.

Сертификат не влезает в одну переменную окружения

Клиентский .p12 в base64 может занимать больше 5 КБ. В нашем хостинге Amvera есть ограничение на размер одного значения переменной окружения примерно в 5 КБ, поэтому сертификат пришлось разрезать на две части и склеивать в коде перед использованием. Это не красиво, но работает.

Email может не прийти

Сбер ID не всегда возвращает email. Если у пользователя в банке почта не привязана, в ответе будет только имя и телефон. Телефон при этом банк-верифицирован — это хороший якорь для идентификации.

У нас в системе email был обязателен, и на этом этапе регистрация ломалась. Мы разрешили создавать аккаунт по телефону, а вместо отсутствующего email использовали служебный плейсхолдер. Если у тебя тоже стоит жёсткое требование email — решай заранее, что делать в таком случае. Важно понимать, что чек 54-ФЗ и письма пользователю без реальной почты уйдут в никуда. Про требования к персональным данным можно почитать в статье «152-ФЗ для владельца приложения».

Проверка id_token

После обмена кода Сбер отдаёт id_token — подписанный JWT с данными о пользователе. Мы проверяем в нём nonce, срок действия и получателя (aud), но не проверяем подпись. Это осознанное решение: канал уже защищён mTLS, а ключи для проверки подписи Сбера добавляют лишнюю сложность. В более чувствительных системах можно включить и проверку подписи.

Что решить до запуска

Перед тем как открыть вход через Сбер ID всем пользователям, стоит ответить себе на несколько вопросов:

• Обязателен ли email? Если да — что делать, если Сбер его не дал?
• Как слать чеки и письма? Без почты остаётся только SMS, а для чеков 54-ФЗ нужен реальный контакт.
• Как связывать аккаунты? Если пользователь раньше входил по почте или Яндексу с тем же телефоном, он должен попасть в тот же аккаунт, а не получить дубль.
• Как хранить сертификат? Уточни лимиты переменных окружения у своего хостинга.

Мы связали вход через Сбер ID с уже существующими аккаунтами по банк-верифицированному телефону. Это сработало: один и тот же человек зашёл и через Яндекс ID, и через Сбер ID, и попал в один профиль.

Готовый промпт для ИИ

Скопируй текст ниже в Codex, Claude Code или другой ИИ-агент, который видит файлы проекта. Перед запуском замени значения в квадратных скобках. Секреты и сертификат в промпт не вставляй: укажи только имена переменных окружения и путь к защищённому файлу.

Нужно подключить Sber ID к существующему сайту.

Контекст проекта:
- стек: [Next.js / Node.js / другой]
- хостинг: [Amvera / VPS / другой]
- текущие способы входа: [перечисли]
- база пользователей: [PostgreSQL / другая]
- точный redirect_uri из анкеты Сбера: [URL]
- Client ID лежит в env SBER_CLIENT_ID
- Client Secret лежит в env SBER_CLIENT_SECRET
- сертификат .p12 и пароль к нему хранятся вне репозитория

Сначала изучи текущую реализацию авторизации и официальную документацию Sber ID. Покажи план и список файлов, которые собираешься изменить. После этого реализуй интеграцию и тесты.

Обязательные требования:
1. Сгенерируй state и nonce криптографически стойким способом, сохрани их в защищённой серверной сессии и проверь в callback. redirect_uri должен совпадать с анкетой символ в символ.
2. Обменяй authorization code на токены через mTLS. Для .p12 используй node:https с pfx и passphrase либо равноценный серверный клиент. Обычного fetch без клиентского сертификата недостаточно.
3. Добавь официальные корневые и промежуточные сертификаты Минцифры только для запросов к Sber ID. Запрещено ставить NODE_TLS_REJECT_UNAUTHORIZED=0, rejectUnauthorized:false или отключать TLS-проверку другим способом.
4. Для token endpoint передавай обязательный RqUID: 32 шестнадцатеричных символа. Для userinfo используй точный путь в нижнем регистре и заголовки x-ibm-client-id и x-introspect-rquid по документации Сбера.
5. Проверь id_token: issuer, audience, exp, nonce и подпись по официальным ключам Сбера. Если в документации не найден JWKS или другой способ проверки подписи, остановись и явно покажи, чего не хватает. Не подменяй проверку подписи проверкой mTLS.
6. Email может отсутствовать. Связывай пользователя с существующим аккаунтом по подтверждённому Сбером телефону, не создавай дубль. Служебный email нельзя использовать для чеков, рассылок и восстановления доступа.
7. Сохрани обычный вход как резервный. Ошибка Sber ID не должна блокировать владельца существующего аккаунта.
8. Секреты, .p12, пароль сертификата и токены не должны попадать в клиентский код, логи, git или текст ответа.
9. Добавь тесты на неверный state/nonce, повторный callback, несовпавший redirect_uri, отсутствующий email, дубль телефона, просроченный id_token и TLS-ошибку.
10. В конце выдай: список env, команды проверки на тестовом окружении, чек-лист выкладки и откат без потери существующих способов входа.

Не меняй боевой контур до успешных тестов. Не выдумывай параметры Sber ID: каждое имя endpoint, scope и заголовка сверь с актуальной официальной документацией.

Если агент предлагает «быстро» отключить проверку сертификата или хранить .p12 в репозитории, останавливай работу. Это не обход ошибки, а новая уязвимость.

Заключение

Сбер ID — рабочий способ входа для российской аудитории, но подготовка и интеграция сложнее, чем у большинства OAuth-провайдеров. Основные сложности не в самой кнопке, а в бюрократическом старте (ЭЦП, ЭДО, анкета) и в mTLS с сертификатами Минцифры на сервере.

Если ты проходишь этот путь, не торопись: сначала получи ключи, потом отладь обмен кода на тестовом окружении, а уже потом выкатывай на пользователей. Особое внимание удели redirect_uri, сертификатам Минцифры и сценарию без email — именно там чаще всего возникают сюрпризы.

Если хочешь разобраться с авторизацией, платежами и другими шагами запуска цифрового продукта — посмотри наш практический курс. Там мы идём от первой настройки окружения до готового приложения с входом и оплатой.

Частые вопросы

Нужен ли сайт-юридическое лицо для подключения Сбер ID?

Скорее всего, да. Регистрация приложения идёт через портал для разработчиков Сбера, и заявление подписывается ЭЦП. Точные требования к типу организации лучше уточнить в документации Сбера на момент подключения.

Можно ли использовать обычный fetch для запросов к Сбер ID?

Для authorize-эндпоинта — да, это обычный редирект. Но для обмена кода на токены потребуется mTLS с клиентским .p12. В Node.js стандартный fetch не умеет использовать .p12, поэтому используй node:https или библиотеку с поддержкой pfx.

Почему локально работает, а на сервере падает с ошибкой сертификата?

Скорее всего, на твоём локальном компьютере установлены корни Минцифры в системном хранилище, а на сервере их нет. Скачай публичные корни Russian Trusted CA и добавь их в доверенные для HTTPS-запросов к oauth.sber.ru.

Что делать, если у пользователя нет email в Сбере?

Разрешить вход по телефону и заранее продумать, как будут приходить чеки и сервисные письма. Если email критичен для твоего сервиса — попроси пользователя указать его отдельно после первого входа.

Нужно ли проверять подпись id_token?

Мы не проверяем, потому что канал защищён mTLS. Это упрощает код, но в высокочувствительных системах проверка подписи будет более правильным подходом.

Источники

• Сбер ID для разработчиков: developers.sber.ru/portal/products/sber-id
• Портал государственных услуг — корни Минцифры: gu-st.ru