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

Как работает вход через OneID

OneID — единая система идентификации Узбекистана: один аккаунт для госуслуг и подключённых к ней частных сервисов. Для вас это способ получить проверенную личность пользователя без собственной проверки паспорта.

Схема похожа на OAuth 2.0 Authorization Code:

1. Пользователь нажимает «Войти через OneID» на вашем сайте.
2. Вы перенаправляете его на страницу OneID с идентификатором клиента, адресом возврата, запрашиваемыми данными (scope) и параметром state.
3. Пользователь входит в OneID (логин и пароль, ЭЦП или другой доступный способ) и подтверждает передачу данных.
4. OneID возвращает его на ваш redirect_uri с одноразовым кодом.
5. Ваш сервер обменивает код на access token, используя секрет клиента.
6. По токену сервер запрашивает данные пользователя и создаёт или находит учётную запись.

Браузер -> ваш сайт -> OneID (вход) -> redirect_uri?code=...&state=...
ваш сервер -> OneID: code + client_secret -> access_token
ваш сервер -> OneID: access_token -> данные пользователя

Точные адреса, названия параметров и значения grant_type берите из документации, которую выдаёт оператор после подключения: они могут отличаться от стандартного OAuth.

Что нужно для подключения

• Юридическое лицо или госорганизация — частным лицам доступ обычно не выдают.
• Заявка оператору OneID с описанием сервиса, целей обработки данных и перечнем нужных полей.
• Домен и адрес возврата, которые будут зарегистрированы для вашего клиента.
• Соблюдение закона о персональных данных: политика конфиденциальности, согласие пользователя, хранение данных граждан Узбекистана на серверах в республике.
• Тестовый контур, если оператор его предоставляет, — отлаживайте интеграцию там, а не на рабочих аккаунтах.

Запрашивайте только те поля, которые действительно нужны. Чем шире scope, тем больше вопросов при согласовании и тем выше ответственность за хранение.

Какие данные вы получаете

Состав зависит от согласованного доступа и типа пользователя. Обычно речь идёт о:

Используйте ПИНФЛ или постоянный идентификатор OneID как ключ связки, а не телефон или e-mail: контакты меняются.

Безопасность интеграции

• Секрет клиента только на сервере. Никогда не кладите его в мобильное приложение или фронтенд. Мобильное приложение открывает вход в системном браузере, а обмен кода выполняет ваш бэкенд.
• Проверяйте state. Генерируйте случайное значение, сохраняйте в сессии и сверяйте при возврате — это защита от CSRF.
• Строгий redirect_uri. Только HTTPS и только заранее зарегистрированные адреса.
• Код одноразовый и короткоживущий. Обменивайте его сразу и не логируйте.
• Не храните access token дольше нужного. Получили данные — выдайте пользователю свою сессию.
• Шифрование и доступы. Паспортные данные храните зашифрованными, доступ к ним — по ролям, с журналом действий.
• Выход. Решите, завершает ли выход из вашего сервиса сессию в OneID, и сообщите об этом пользователю.

Запасные способы входа

OneID может быть недоступен, а у части пользователей нет аккаунта. Поэтому:

• оставьте вход по телефону с SMS-кодом или e-mail для базовых функций;
• позвольте привязать OneID к существующему аккаунту, чтобы не плодить дубли;
• функции, где нужна подтверждённая личность, показывайте после входа через OneID, а остальное — без него;
• при ошибке OneID показывайте понятное сообщение и кнопку повтора, а не пустую страницу.

Частые ошибки

• Обмен кода на токен прямо в браузере или приложении с вшитым секретом.
• Создание нового аккаунта при каждом входе из-за связки по телефону.
• Запрос всех доступных полей «на всякий случай».
• Отсутствие мониторинга: о падении интеграции узнают от пользователей.