OAuth/OIDC: интеграция

Discovery

curl --fail --silent --show-error https://id.zorin.cloud/.well-known/openid-configuration

Получайте endpoint и jwks_uri через discovery, проверяя ожидаемый issuer. Не принимайте произвольный issuer из непроверенного токена. По текущему контроллеру поддержаны Authorization Code, refresh, ограниченный client credentials и Device Authorization; доступ определяется типом клиента и серверной политикой.

Публичная поверхность

Метод	Путь	Назначение
GET	/.well-known/openid-configuration	Discovery
GET	/oauth2/jwks	Public signing keys
GET	/oauth2/authorize	Authorization Code
POST	/oauth2/par	Pushed Authorization Request
POST	/oauth2/token	Выдача/обновление токенов
GET	/oauth2/userinfo	Профиль по Bearer access token/scopes
POST	/oauth2/revoke	Отзыв токена/семейства
POST	/oauth2/introspect	Проверка токена для разрешённого confidential client
GET	/oauth2/logout	Выход с проверенным post_logout_redirect_uri
POST	/oauth2/device/authorize	Начало device flow

Пути и параметры сверены с OAuthController/OAuthService. OpenAPI 3.1: текущий source profile содержит schemas и ограничения grant. Это описание текущей реализации, не подтверждение полной совместимости OAuth/OIDC и не authenticated E2E проверка.

Обработка ошибок

Отмену consent, недействительный/истёкший code и state, неверный client и redirect URI обрабатывайте как отказ входа. Не повторяйте обмен одноразового code бесконечно. Не записывайте code/access/refresh/ID tokens в URL аналитики и логи. Для сети/5xx используйте bounded retries только там, где повтор безопасен; повторное использование refresh token может отозвать семейство.

Ограничения

FIRST_PARTY native Account/Console cookie/CSRF endpoints не являются публичным SaaS API. events.ingress и machine grants не доступны любому стороннему приложению. Device Authorization не следует обещать всем клиентам только потому, что endpoint указан в discovery.

Совместимость текущего source profile

У POST-методов OAuthController отсутствует явный @HttpCode: стандартный Nest response status — 201. Обработка ошибок использует BadRequestException/UnauthorizedException, а не выделенный OAuth error serializer; например, device polling ошибки могут оказаться в message, а не error. Это технический долг перед выпуском универсальных OAuth-клиентов, а не целевой протокольный контракт. Поведение Nest.

PAR допускает PUBLIC клиентов в текущем профиле; confidential client передаёт Basic или client_secret_post. Introspection и revocation требуют confidential client. Device Authorization ограничен FIRST_PARTY + MIX Account, пока не реализован device consent для внешних клиентов. Client credentials для THIRD_PARTY запрещён; SECOND_PARTY ограничен разрешёнными ingress scopes.

Discovery публичного issuer и read-only доступность проверены 2026-10-16. Успешная выдача/обновление токенов в этой итерации не проверялась; реальные credentials не использовались.