authorize

[GET] /oauth/authorize

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

Минимальный запрос содержит тип ответа code, идентификатор клиента и адрес возврата. Для безопасной интеграции добавьте state и PKCE-параметры.

GET https://auth.regos.uz/oauth/authorize?response_type=code&client_id=your_client_id&redirect_uri=https%3A%2F%2Fyour.app%2Fcallback&scope=openid%20profile%20email&state=random_state&code_challenge=your_code_challenge&code_challenge_method=S256

Параметры передаются в query string:

Название	Обязательность	Описание
`response_type`	Да	Всегда `code`.
`client_id`	Да	Идентификатор вашего приложения.
`redirect_uri`	Да	Адрес возврата после входа. Должен совпадать с зарегистрированным адресом.
`scope`	Нет	Запрашиваемые права, разделенные пробелами, например `openid profile email`. Если не передать, REGOS использует разрешения клиента.
`state`	Рекомендуется	Случайное значение для защиты от подмены ответа. REGOS вернет его без изменений.
`prompt`	Нет	Управляет поведением входа. Например, `login` просит войти заново, `consent` показывает согласие, `none` запрещает показывать экран входа.
`nonce`	Нет	Значение для связывания запроса с `id_token`. Используется в OpenID Connect.
`code_challenge`	Да при `RequirePkce=true` или временном входе	PKCE challenge, вычисленный из `code_verifier`. У новых public-клиентов PKCE обязателен.
`code_challenge_method`	Рекомендуется	Используйте `S256`.

После успешного входа REGOS перенаправит пользователя на redirect_uri:

https://your.app/callback?code=one_time_code&state=random_state&iss=https%3A%2F%2Fauth.regos.uz

Если вход невозможен, REGOS вернет OAuth-ошибку. Если redirect_uri принят, ошибка будет отправлена на него в query string, например error=login_required. Ваше приложение должно обработать и успешный ответ, и ошибку.

Адрес возврата и PKCE

REGOS сравнивает адрес возврата с зарегистрированным адресом точно: регистр пути, завершающий слеш и query string имеют значение. Для native-приложений с HTTP loopback-адресом 127.0.0.1 или [::1] может отличаться только порт. Например, регистрация http://127.0.0.1/callback разрешает возврат на http://127.0.0.1:49152/callback. Это исключение не распространяется на localhost, другие хосты или custom scheme. При обмене кода на токены передайте точный адрес из исходного запроса, включая фактически использованный порт.

Для новых public-клиентов PKCE обязателен, разрешён только метод S256. Для совместимости обычный вход существующих клиентов с RequirePkce=false допускается без PKCE. Это временное исключение: новые native-интеграции должны использовать PKCE. Переданный challenge всегда проверяется, а при обмене кода требуется соответствующий verifier. Временный вход всегда требует S256, даже при RequirePkce=false.

Сгенерируйте случайный code_verifier длиной 43–128 символов из букв ASCII, цифр и -._~, затем вычислите BASE64URL(SHA256(code_verifier)) без padding. Метод plain возможен только для confidential-клиента, которому он отдельно разрешён, и только вне временного входа; для новых интеграций используйте S256.

Управление входом

Параметр	Поведение
`prompt=login`	Требует новой аутентификации. Простого выбора сохранённого аккаунта недостаточно.
`prompt=select_account`	Открывает выбор аккаунта, включая текущий. Выбор текущего аккаунта не требует смены сессии и не считается повторной аутентификацией. Повторный ввод учётных данных зависит от состояния выбранного аккаунта.
`prompt=consent`	Запрашивает экран согласия даже при ранее выданном разрешении.
`prompt=none`	Запрещает интерактивные экраны; при необходимости входа возвращает `login_required`, согласия — `consent_required`. Нельзя сочетать с другими значениями `prompt`.
`max_age`	Неотрицательное число секунд с последней аутентификации. При превышении нужна новая аутентификация; `0` требует её сразу. В ID token возвращается `auth_time`.
`login_hint`	Подсказка для поля телефона на странице входа. Не подтверждает личность и не ограничивает выбор аккаунта.
`ui_locales`	Предпочтительные языки через пробел, например `uz ru en`. Используется первый поддерживаемый язык; неподдерживаемые пропускаются.

Текущие интеграции с внешними провайдерами входа не подтверждают время активной аутентификации. Такой вход доступен для обычной авторизации, но не удовлетворяет prompt=login или max_age: в этом случае REGOS возвращает login_required. Для повторной аутентификации используйте вход с паролем REGOS. Время внешнего callback не подставляется в auth_time.

Выбранный через ui_locales язык сохраняется на экранах входа и выбора аккаунта и имеет приоритет над языком профиля в этом процессе. Настройка языка профиля не меняется.

Если во время показа согласия пользователь сменил сессию в другой вкладке, REGOS возвращает login_required. Форма согласия действует 10 минут; после истечения возвращается invalid_request. В обоих случаях приложение должно начать новый запрос авторизации.

В успешном redirect и в redirect с OAuth-ошибкой возвращается iss. Приложение должно сравнить его с ожидаемым issuer из discovery, проверить state, и только затем обменивать код. Если сам адрес возврата не прошёл проверку, REGOS отвечает ошибкой напрямую и не перенаправляет пользователя на него.

Правила адресов описаны в RFC 8252, параметр iss — в RFC 9207.

Доступ после выхода из браузера

Чтобы приложение продолжало работать после выхода или переключения аккаунта в
REGOS Auth, запросите scope=openid offline_access и prompt=consent.
Для выбора аккаунта используйте prompt=select_account consent. Сервер и настройки
клиента должны разрешать offline-доступ и refresh tokens.

При RequireConsent=false доступ, включая offline, заранее разрешён администратором:
сервер сохраняет разрешение автоматически, prompt=consent не обязателен.
Если он явно передан, REGOS всё равно показывает согласие.
При RequireConsent=true REGOS показывает согласие на каждый новый offline grant.
Без prompt=consent значение offline_access игнорируется; ранее сохранённое согласие
не заменяет подтверждение нового offline grant. Если offline-доступ отключён, явный запрос
offline-доступа возвращает invalid_scope.

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

Временный вход без сохранения входа в браузере

Для клиента с включённой настройкой UseTemporaryLogin сервер показывает минимальную форму:
телефон и пароль. При необходимости согласия добавляются разрешения и кнопка «Войти и разрешить»,
при административном разрешении — кнопка «Войти». Настройка действует для клиента;
параметра URL для её включения нет. На сервере должны быть разрешены EnableTemporaryLogin
и EnableOfflineAccess, у клиента — offline_access и оба grant: authorization_code, refresh_token.

Запрос: response_type=code, PKCE S256, scope=openid offline_access,
prompt=login consent. Дополнительные scopes, state, nonce, login_hint и ui_locales
передаются как обычно. prompt=consent тоже допустим: пароль всё равно потребуется.
prompt=none возвращает login_required; отсутствие offline scope — invalid_scope,
отсутствие consent в prompt при RequireConsent=true — consent_required.
При RequireConsent=false можно использовать prompt=login или не передавать prompt:
offline-доступ разрешён администратором, дополнительное согласие не запрашивается.
Явный prompt=consent всегда показывает согласие. Если настройка изменилась на
RequireConsent=true после открытия формы без согласия, начните новый вход с prompt=consent.

Общий срок формы и обмена кода задаёт серверный Jwt:TemporaryLoginLifetime (по умолчанию
300 секунд). Ошибки ввода срок не продлевают. При отмене или истечении срока начните новый
запрос авторизации. max_age этот срок не меняет.

Вход не добавляет пользователя на полку и не создаёт cookie входа. Существующая сессия браузера
сохраняется. Обмен кода атомарно закрывает временный контекст и выдаёт токены независимой
offline-сессии; приложение продолжает работать после закрытия браузера. Выход из приложения —
отзыв refresh token через /oauth/revoke, который отзывает семейство токенов. Обычные правила
блокировки пользователя, смены пароля, отзыва сессий и истечения refresh token сохраняются.

Это дополнительная политика REGOS, а не новый OAuth grant или стандартный параметр prompt.
Для native-клиента используется системный браузер; пароль вводится только на странице REGOS Auth.