Документация upID

Как устроен вход

upID подтверждает личность пользователя через OpenID Connect. Ваша система остаётся владельцем своих пользователей, сессий, ролей и бизнес-прав. Подтверждённый вход в upID не назначает пользователю роль и не даёт доступ к данным вашей организации автоматически.

1. Ваш сервер создаёт одноразовую попытку входа и перенаправляет браузер на upID.
2. upID показывает QR-код или вход по номеру телефона. Пользователь подтверждает запрос в приложении upID на привязанном устройстве.
3. Браузер возвращается на ваш callback с одноразовым code и state. Секрет клиента и verifier через браузер не передаются.
4. Ваш сервер обменивает code на токены, проверяет ID Token и согласованную политику допуска. После этого он связывает личность с локальным пользователем и создаёт сессию приложения.

Интегратор реализует начало входа, callback и свою сессию. QR, подтверждение устройства, номер телефона и восстановление аккаунта обслуживает upID. Копировать внутренние мобильные API в свой проект не требуется.

Перед подключением

Текущий профиль рассчитан на серверное веб-приложение, которое может хранить client_secret вне браузера. Используйте OIDC-библиотеку вашей платформы; ручное декодирование JWT не заменяет проверку личности.

Для нового приложения нужен отдельный серверный шаг допуска: согласовать клиента, callback и политику сессии. Саморегистрации клиентов пока нет. Наличие произвольной записи client_id само по себе не снимает ограничения текущего пилота.

Получите у оператора upID

• Точный HTTPS issuer для согласованной среды. Храните его в серверной конфигурации, а не выбирайте по данным callback или заголовку Host.
• Отдельные client_id и client_secret для приложения и среды. Секрет хранится в серверном хранилище секретов; он не входит в HTML, frontend bundle, мобильное приложение или Git.
• Зарегистрированный HTTPS callback без масок и произвольных адресов возврата. Одна и та же точная строка redirect_uri используется в запросе входа и при обмене code.
• Подтверждение доступных scopes, метода аутентификации клиента, алгоритма подписи и требований к проверке актуальности доступа и выходу.

Профиль серверного клиента

issuer = OPERATOR_CONFIRMED_HTTPS_ISSUER
client_id = REGISTERED_CLIENT_ID
client_secret = SERVER_SECRET_STORE
redirect_uri = https://app.example.com/auth/upid/callback
response_type = code
scope = openid profile
code_challenge_method = S256
token_endpoint_auth_method = client_secret_basic
id_token_signed_response_alg = RS256

Это схема с условными значениями, а не готовые реквизиты или запрос к боевой среде. Реальные адреса и параметры формирует ваша OIDC-библиотека. Переносы строк в HTTP-примерах добавлены для чтения.

Среда и endpoints

Загрузите /.well-known/openid-configuration относительно согласованного issuer. Проверьте точное совпадение поля issuer с вашей конфигурацией. Адреса authorization_endpoint, token_endpoint и jwks_uri берите из проверенных метаданных и сверяйте с согласованной средой; не подставляйте адреса из пользовательского ввода.

Серверные запросы выполняются по HTTPS с проверкой сертификата и имени сервера. Сертификат локальной среды настраивается отдельно; отключать TLS-проверку ради подключения нельзя.

OpenID Connect Discovery 1.0: проверка конфигурации провайдера

Важная особенность текущей реализации: Discovery формируется OIDC-модулем и может объявлять больше возможностей, чем опубликовано серверными маршрутами. Наличие UserInfo, logout или другого поля в metadata не означает, что эта возможность подключена в upID.

Начните вход

Для каждой попытки создайте независимые криптографически случайные state, nonce и code_verifier. Привяжите попытку к браузеру, issuer, клиенту, callback, языку и ограниченному сроку. На сервере сохраните исходные значения; затем перенаправьте браузер на authorization_endpoint.

PKCE обязателен и для confidential-клиента. Получите code_challenge как BASE64URL(SHA256(code_verifier)) без padding. Например, verifier можно сформировать из 32 случайных байт в base64url; не используйте постоянное значение и не переиспользуйте попытку.

RFC 7636: PKCE и преобразование S256

GET AUTHORIZATION_ENDPOINT_FROM_DISCOVERY?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=URL_ENCODED_REGISTERED_CALLBACK&
  scope=openid%20profile&
  state=ONE_TIME_RANDOM_STATE&
  nonce=ONE_TIME_RANDOM_NONCE&
  code_challenge=BASE64URL_SHA256_VERIFIER&
  code_challenge_method=S256&
  ui_locales=az

Это схема с условными значениями, а не готовые реквизиты или запрос к боевой среде. Реальные адреса и параметры формирует ваша OIDC-библиотека. Переносы строк в HTTP-примерах добавлены для чтения.

Публичный authorization-запрос допускает только перечисленные параметры, без повторов и массивов; query ограничен 4096 байтами. prompt, max_age, claims и request objects в этот профиль не входят. Настройте OIDC-библиотеку так, чтобы она не добавляла response_mode, prompt или другие неописанные параметры. Открывайте upID обычным перенаправлением браузера: встраивание в iframe и обмен code из frontend в этот профиль не входят.

Обработайте callback

До обращения к token endpoint сопоставьте state с неистёкшей попыткой этого браузера. Одноразово и атомарно потребите попытку. Чужой, отсутствующий или повторный state не должен приводить к обмену code и созданию сессии.

Ответ error обрабатывайте только в контексте сопоставленной попытки. Отказ или отмена не создают вход. Не принимайте access_token, id_token, refresh_token или code_verifier из callback query; этот профиль ожидает code и state либо ошибку провайдера.

Обменяйте code серверным POST на token_endpoint. Передайте исходный code_verifier и тот же redirect_uri. Для аутентификации используйте client_secret_basic через библиотеку; client_secret в теле запроса и client_assertion текущий профиль не принимает.

POST TOKEN_ENDPOINT_FROM_DISCOVERY
Authorization: Basic ENCODED_CLIENT_CREDENTIALS
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=CODE_FROM_CALLBACK&
redirect_uri=URL_ENCODED_REGISTERED_CALLBACK&
code_verifier=ORIGINAL_VERIFIER

Это схема с условными значениями, а не готовые реквизиты или запрос к боевой среде. Реальные адреса и параметры формирует ваша OIDC-библиотека. Переносы строк в HTTP-примерах добавлены для чтения.

Не создавайте локальный вход только по успешному HTTP-ответу или наличию access_token: сначала проверьте ID Token. После обработки уберите code и state из видимого адреса перенаправлением на чистый внутренний URL. Этот URL выбирается из серверного списка разрешённых переходов, а не из произвольного return_to.

Проверьте ID Token

Используйте полный verifier вашей OIDC-библиотеки. Текущий клиентский профиль ожидает RS256 и подпись по ключам из проверенного jwks_uri. Простое чтение payload JWT или наличие sub не подтверждает личность.

• Проверьте подпись и разрешённый алгоритм. Не доверяйте одному только alg или адресу ключа из непроверенного токена.
• iss должен точно совпасть с настроенным issuer; aud должен включать ваш client_id. При нескольких aud требуется azp вашего клиента; присутствующий azp также проверяется.
• Проверьте exp и iat по политике библиотеки и согласованному допуску часов. Отсутствующий, просроченный или некорректный обязательный claim означает отказ.
• nonce обязан присутствовать и совпасть с исходной серверной попыткой; sub должен быть непустой строкой. Пара issuer + sub — ключ связи с локальным пользователем.

OpenID Connect Core 1.0: Authorization Code и проверка ID Token

Не связывайте аккаунты автоматически по телефону, email или отображаемому имени. Не обещайте пользователю профильные данные только на основании scope profile. ID Token не является универсальным access token для API вашего продукта.

Текущий пилот также использует подписанный claim upid_correlation. Это частное расширение upID для связи входа и допуска, а не стандартный OIDC claim и не самостоятельный bearer credential. Его нельзя игнорировать при воспроизведении политики upHome или считать готовым контрактом для любого внешнего клиента.

Сессия, актуальность и выход

После полной проверки личности и согласованных условий допуска создайте собственную серверную сессию с новым идентификатором. Cookie, CSRF, сроки, роли и доступ к вашим ресурсам остаются ответственностью приложения. Не сохраняйте ненужные токены в браузере или localStorage.

В локальном upHome актуальность допуска проверяется отдельным серверным API upID: состояние аккаунта, устройства и конкретного контекста входа. Этот механизм не является стандартным OAuth introspection и пока не открыт для произвольного клиента. Срок действия JWT сам по себе не доказывает, что доступ ещё разрешён.

Пути /api/v1/rp-sessions/status и /close проверяют и закрывают контекст допуска; /confirm и /end сообщают о сессии продукта. Эти частные API требуют отдельно допущенного клиента. Сигнал confirmed не заменяет разрешение доступа; unconfirmed не доказывает выход. Контракт внешнего клиента нужно согласовать до подключения.

Локальный upHome кеширует положительный допуск максимум на 30 секунд от начала серверного запроса. После этого при недоступности upID защищённые действия закрываются, а локальная сессия сохраняется в прежних сроках. Это политика текущего продукта, а не обещание мгновенного отключения всех открытых страниц.

Выход из вашего приложения завершает его локальную сессию через защищённое действие, например POST с CSRF. Он не означает выход из всех продуктов, отзыв устройства или завершение сессии провайдера. RP-initiated и back-channel logout не входят в доступный профиль upID.

Ошибки и повтор входа

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

Не записывайте client_secret, code, verifier, токены, Cookie и полный callback URL в access logs, аналитику, отчёты ошибок или Git. Сырые ответы провайдера и технические исключения не показываются пользователю.

Что пока недоступно

• Самостоятельное подключение внешних клиентов, Dynamic Client Registration, общий SDK и готовый профиль для SPA или native public client.
• Refresh grant, offline_access, implicit, password и client_credentials не включены. Текущий профиль использует только Authorization Code и не предоставляет сценарий обновления токенов.
• UserInfo и end-session: модуль может объявлять их в Discovery, но текущие маршруты upID их не публикуют. Не используйте их как обязательный шаг входа или выхода.
• Silent SSO, prompt=none, max_age, request objects и произвольные claims. Текущий вход требует нового явного подтверждения на привязанном устройстве.
• Глобальный logout и универсальные OAuth API introspection/revocation не входят в опубликованный профиль. Доступность production-среды, условия эксплуатации и поддержка согласуются отдельно.

Перед вводом интеграции в работу

• Оператор подтвердил вашу среду, допуск клиента, callback и политику сессии. Примеры заменены реальной конфигурацией, секреты остаются на сервере.
• Вручную пройдены вход с подтверждением устройства, создание своей сессии, локальный выход и повторный вход.
• Отказ пользователя, неверный или повторный state, повтор code, неверный verifier, callback и подпись приводят к отказу без нового доступа. Эти проверки нужно выполнить в вашей согласованной среде; здесь они не объявляются пройденными.
• При недоступности Discovery/JWKS/token endpoint и истечении сроков приложение не принимает непроверенную личность; поздний callback после выхода не восстанавливает старый вход.
• Проверены сообщения, сохранение существующей сессии, чистый адрес после callback, отсутствие секретов в логах и доступность входа на нужных языках.

Стандарты

Протокол реализуется через OIDC-библиотеку. Нормативные правила обмена и проверки описаны в первичных спецификациях; возможности конкретного upID ограничены профилем выше.

• OpenID Connect Core 1.0: Authorization Code и проверка ID Token
• OpenID Connect Discovery 1.0: проверка конфигурации провайдера
• RFC 7636: PKCE и преобразование S256
• RFC 9700: актуальные рекомендации по защите OAuth 2.0